bonsai documentation
bonsai is a terminal coding agent: a single static Rust binary that can
inspect, change, run, debug, verify, and review real software through a
catalog-driven set of LLM provider connections, a tool-based execution loop,
and a ratatui terminal UI. This directory is the reference documentation,
split by topic.
Orientation
| Document |
What it covers |
| Overview |
What bonsai is, the product contract, and a feature map |
| Architecture |
Module layout, startup sequence, the agent loop, and the key abstractions |
| Getting started |
Installation, first-run onboarding, and the first task |
Using bonsai
| Document |
What it covers |
| Configuration |
.bonsai/config.toml layering, every recognized key, env vars, /settings, /config |
| Providers |
The built-in connections, wire transports, authentication, and credential storage |
| Models |
The model catalog, /model, reasoning effort, shortcuts, custom model definitions, pricing |
| Agents and modes |
Agent/plan/review modes, subagents, and custom agent definitions |
| Tools |
Complete reference for every built-in tool the model can call |
| Slash commands |
Complete reference for every /command |
| TUI guide |
Layout, keybindings, the composer, transcript features, serenity mode |
| Sessions |
Session lifecycle, resume, persistence, budgets, and the usage ledger |
| Context management |
Token accounting, compaction, task episodes, recall, and /ctx |
| Memory |
The persistent user/project memory stores and relevance-gated recall |
| Theming |
Built-in themes, custom palettes, the role contract, terminal color modes |
Safety
| Document |
What it covers |
| Autonomy and permissions |
Autonomy levels, command risk classification, permission rules |
| Sandbox |
OS command confinement: Seatbelt, Bubblewrap, writable roots, network policy |
| Security model |
Trust boundaries, workspace trust, untrusted content, credentials, redaction, release signing |
Extending bonsai
| Document |
What it covers |
| Skills |
On-demand instruction sets: format, discovery, built-ins |
| Hooks |
Lifecycle hooks: events, actions, the wire protocol, trust |
| MCP servers |
Model Context Protocol: stdio/HTTP transports, OAuth, namespacing, gating |
| Language intelligence |
Tree-sitter symbols, the repository map, managed language servers |
Automation and operations
| Document |
What it covers |
| Headless mode |
bonsai -p print mode, output formats, event stream, exit codes, CI recipes |
| Recovery worktrees |
Isolated runs, bonsai recovery commands, merge semantics |
| Eval harness |
The deterministic eval suite, graders, live mode, reports |
| Troubleshooting |
bonsai doctor, common failures, and where to look |
| Compatibility and upgrades |
The 1.x compatibility contract, upgrade backups, rollback |
Contributing
| Document |
What it covers |
| Development |
Building, testing, style, adding tools and providers, releasing |
Reading paths
The top-level README.md remains the quick tour;
AGENTS.md is the working guide for coding agents in this
repository; ROADMAP.md tracks unfinished work only.