Context-filter guidance, Brex framing, and read-only/--allow-write fix - #3
Merged
Conversation
Adds a "context filter" use case: prefer just-bash to reduce large read-only output inside the sandbox (grep/jq/wc) and return only what matters, instead of dumping full payloads into the conversation. Adds a README "Why just-bash (and where this fits)" section that distinguishes the safety layer this project provides (steer coding agents to sandbox generated shell) from the in-process workbench layer for product agents (embed the just-bash library), citing the Brex writeup and benchmark repo. Notes that the one-shot CLI does not provide persistent-workbench state. Also corrects the write semantics across the skill, AGENTS.md, and copilot-instructions.md: the CLI is read-only by default (writes fail with EROFS) and requires --allow-write for in-memory, discarded writes. Verified against just-bash v3.1.0 (CLI 1.0.0); all documented examples were run. Co-authored-by: Copilot App <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up on the Brex "give agents bash" writeup. Two doc additions plus a real accuracy fix discovered while verifying against the CLI.
1. Context-filter use case (skill)
The skill sold
just-bashpurely as a safety dry-run. Brex highlights a second win: even for non-destructive work, running inside a workbench keeps large raw output out of the model context. Added guidance + examples to preferjust-bashfor read-only exploration that would otherwise flood the conversation — reduce it in the sandbox (grep,jq,wc) and return only the rows that matter.2. "Why just-bash (and where this fits)" (README)
New section distinguishing the two adoption models, so readers don't expect behavior this project doesn't provide:
just-bashlibrary for context reduction. Cites the Brex post (P90 tokens ~3M → ~600–700k, P95 latency ~halved) and the benchmark repo.It explicitly notes the one-shot CLI does not give the persistent workbench (files-as-memory) behavior — overlay writes are discarded per invocation.
3. Accuracy fix: read-only by default
While verifying the examples I found the CLI is read-only by default — writes fail with
EROFSunless you pass--allow-write(writes then go to an in-memory overlay and are discarded). The old docs claimed "writes stay in the overlay and are discarded" without the flag, which is wrong. Fixed across the skill,AGENTS.md, and.github/copilot-instructions.md, and added--allow-writeto the write/dry-run examples.Verification
All documented commands were run against
just-bashv3.1.0 (CLI reports 1.0.0):grep … | wc -l,jq … | length) work with no flag.find … -deletedry-runs work only with--allow-write; the host file was confirmed unchanged after an in-sandbox delete.node scripts/validate.mjspasses.