provider-independent terminal agent
Bonsai is a local-first coding agent that can inspect, plan, edit, run, diagnose, verify, review, remember, and coordinate. Switch models without losing the conversation, and choose how much runs without asking.
cargo install --git https://github.com/strozynskiw/bonsai.git --tag v0.2.0 --locked
one continuous workflow
Plan, implement, verify, and review in one resumable conversation.
The actual interface in forest, the default of 18 themes—switch coding and plan mode without losing the conversation.
the full workshop
Bonsai combines the engineering loop with the controls and evidence needed for longer, more autonomous runs.
Read, grep, glob, Rust symbols, rust-analyzer navigation, atomic patches, shell commands, Git inspection, web fetch, image input for compatible models, background jobs, and todos—batched when their access paths do not conflict.
Research in read-only plan mode, hand the canvas to coding with /start, then inspect pending changes in a read-only review pass. The conversation stays intact.
Switch connections, models, and reasoning effort mid-conversation—including local OpenAI-compatible endpoints. Bind model-and-effort combinations to one-letter shortcuts. Metadata, pricing, context limits, and capabilities come from models.dev.
Cache-aware compaction, exact tokenizers where available, /ctx diagnostics, the SMOL profile, read-result reuse, and task episodes with untrusted recall framing.
User preferences follow you; project facts can ship with the repository. Hybrid retrieval combines BM25 and embeddings to recall relevant entries on demand. Sessions, plans, todos, usage, and context resume from SQLite.
Delegate exploration and review to scoped read-only subagents. Coordinate separate Bonsai sessions with messages, changed-file visibility, advisory work claims, wait relationships, and wake-on-finish.
Layer project and global config. Add MCP over stdio or Streamable HTTP, lifecycle hooks, skills, custom agents, providers, and themes under explicit trust and effect boundaries.
Text, JSON, or streaming JSON events; documented exit codes; turn, time, output, tool, and session budgets; observed-state completion reports; and recovery worktrees for autonomous mutations.
Keyboard and mouse input, queued steering, selection and copy, diff cards, live task views, model and provider pickers, Serenity transcript mode, truecolor/256-color adaptation, and 18 built-in themes.
Usage, cost, retries, cache reads, verification freshness, file changes, authorization decisions, caveats, and budget exhaustion come from durable evidence—not the model’s recollection.
autonomy without ambiguity
Autonomy decides what may run without asking. The sandbox decides what a child process can physically touch. They are separate controls.
macOS Seatbelt or Linux Bubblewrap confines writes to approved roots and denies network by default. Yolo does not silently disable it.
Allow once, for the session, or for the project. Rules cannot re-enable the hard-deny floor.
Project-supplied config, hooks, MCP servers, skills, agents, and steering files remain inert until the repository is trusted.
Web, MCP, recalled history, files, and background output are framed so content cannot promote itself to instructions.
context lifecycle
Bonsai measures each request, preserves cache-friendly prefixes, and prunes or reuses bulky results. Task episodes keep archived bytes available for recall.
Stable prefixes stay stable. Superseded reads and bulky tool output are reclaimed before a larger context rewrite is needed.
A deliberately compact prompt and tool surface for smaller or local models. Toggle it with /smol.
Finished task spans archive as whole units — one compact card replaces the span when that actually saves context — instead of splitting message groups.
The model can search or page archived bytes back in through an untrusted frame. Repeated live recalls collapse to pointers.
a coordinated grove
Use subagents for focused, read-only work inside a turn. Use peers to coordinate separate Bonsai sessions in the same repository.
use it your way
The TUI and headless mode share the same agent, persistence, permissions, budgets, and verification semantics.
$ bonsai › /autonomy balanced # routine dev loop runs without asking › /sandbox on # OS-level command confinement › /model 3 # switch model mid-conversation › fix the flaky retry test, then review your diff # the agent inspects, edits, and self-reviews in the live transcript › /test # run the configured test verification profile › /commit # commit the reviewed diff
$ bonsai -p "upgrade sqlx, run tests, and summarize changes" \ --autonomy balanced --isolation auto \ --max-turns 30 --max-tool-seconds 300 \ --output-format stream-json {"type":"tool_finished","id":"call_7","result":"14 tests passed","status":"succeeded"} {"type":"status","text":"Recovery 1783857600123-4821-0-a1b2c3d4 ready. Inspect with: bonsai recovery inspect 1783857600123-4821-0-a1b2c3d4"} # mutating runs land in an isolated git worktree — the source checkout # is never changed automatically. Inspect, then merge, keep, or discard. $ bonsai recovery inspect 1783857600123-4821-0-a1b2c3d4 $ bonsai recovery merge 1783857600123-4821-0-a1b2c3d4
# pipe a prompt from stdin, get machine-readable output $ echo "summarize the diff on this branch" | bonsai -p --output-format json # set defaults through the environment $ BONSAI_AUTONOMY=balanced BONSAI_PROVIDER=opencode bonsai -p 'run `git status` via bash' # exit codes a script can branch on 0 completed 1 tool/provider/runtime failure 2 CLI usage 3 auth/config 124 timeout 130 SIGINT 143 SIGTERM
# every session persists locally — pick up where you left off $ bonsai -c # resume the most recent session for this project $ bonsai -c 52 # resume a specific session by id # resume headlessly: same session, one more turn, then exit $ bonsai -c -p "What did we decide about the retry backoff?" # on exit, bonsai prints the session id and the exact # command to bring it back
catalog-driven connections · switch connections or models without restarting the conversation
ready to grow
Install with Cargo straight from GitHub (needs a stable Rust toolchain; the binary lands in ~/.cargo/bin). The first command installs the latest release; the second tracks master. To update, rerun with the new tag — or add --force to refresh a master build. Prebuilt binaries are planned for a later release.