Bonsai

Bonsai turns a local repository into a small, repeatable context file for LLMs.

It scans source files, compresses code with syntax-aware summaries, respects your token budget, and writes XML or JSON you can paste into ChatGPT, Codex, Claude, Copilot, or another agent.

Use it when you want an LLM to understand a whole project before asking for architecture, onboarding, review, or branch-change help.

Quick Start

Install Bonsai, then run it inside a repository:

bonsai .

This writes:

bonsai.xml

Paste that file into an LLM and ask:

Use this Bonsai repo context. Explain the architecture and tell me where to start reading.

For a larger context budget:

bonsai . --max-tokens 12000 --level 2 --output-file /tmp/bonsai.xml

For a paste-ready prompt:

bonsai . --prompt --output-file /tmp/bonsai-prompt.txt

Quick Setup For Agents

Run this once in any repo where you want agents to use Bonsai first:

bonsai init-agent

It writes:

AGENTS.md
CLAUDE.md

Those files tell Codex, Claude Code, and similar agents to run Bonsai before answering broad project questions.

Overwrite existing files:

bonsai init-agent --force

Install

Download a release binary:

https://github.com/mickyhq/bonsai/releases/latest

Release assets:

bonsai-linux-x64
bonsai-macos-arm64
bonsai-linux-x64.sha256
bonsai-macos-arm64.sha256
bonsai-vscode-*.vsix

macOS Apple Silicon:

curl -L -o bonsai https://github.com/mickyhq/bonsai/releases/latest/download/bonsai-macos-arm64
chmod +x bonsai
sudo mv bonsai /usr/local/bin/bonsai

Linux x64:

curl -L -o bonsai https://github.com/mickyhq/bonsai/releases/latest/download/bonsai-linux-x64
chmod +x bonsai
sudo mv bonsai /usr/local/bin/bonsai

Install from this checkout:

cargo install --path .

Install from GitHub:

cargo install --git https://github.com/mickyhq/bonsai.git

Check your install:

bonsai doctor

What Bonsai Keeps

Bonsai has three compression levels:

--level 1  Full code first, then shrink if needed
--level 2  Imports, signatures, types, classes, and function shapes
--level 3  Compact tree map only

Example source:

fn greet(name: &str) -> String {
    let message = format!("hello {name}");
    println!("{message}");
    message
}

Level 2 skeleton:

fn greet(name: &str) -> String { ... }

Level 3 tree map:

fn greet(name: &str) -> String

Markdown keeps headings, useful summary text, tables, lists, links, and code fence language names. Config files keep important top-level shape, supported top-level comments, and tuned nested sections for common manifests like package.json, GitHub workflows, Cargo.toml, Codex plugin manifests, and VS Code manifests. Markdown, config, and web-template line truncation is token-aware. Long Markdown tables/lists and import/include/use blocks keep the first few lines and collapse the rest.

Common Commands

Write XML to bonsai.xml:

bonsai .

Write JSON:

bonsai . --format json --output-file /tmp/bonsai.json
bonsai . --format text --output-file /tmp/bonsai.txt

Copy a prompt to the clipboard:

bonsai . --prompt --output clipboard

Use a model-family tokenizer:

bonsai . --tokenizer gpt-4o
bonsai . --tokenizer o200k_base

Make a compact architecture map:

bonsai . --level 3

Write only the project map:

bonsai . --project-map-only
bonsai . --project-map compact --project-map-only

Include stable file hashes in the project map:

bonsai . --file-hashes

Omit token count fields from XML/JSON:

bonsai . --no-token-counts

Write metadata and project map without file bodies:

bonsai . --no-content

Show selected files:

bonsai . --print-files

Preview selected files and estimated tokens without writing output:

bonsai . --dry-run

Suppress normal stdout for scripts:

bonsai . --quiet --output-file /tmp/bonsai.xml

Generate shell completions:

bonsai completions bash > ~/.local/share/bash-completion/completions/bonsai
bonsai completions zsh > ~/.zfunc/_bonsai
bonsai completions fish > ~/.config/fish/completions/bonsai.fish

Filter files:

bonsai . --include 'src/**' --exclude '**/generated.rs'
bonsai . --exclude-generated

--exclude-generated skips minified, vendored, generated, and lockfile-like files. A matching --include pattern keeps explicit paths.

Sort output:

bonsai . --sort priority
bonsai . --sort tokens
bonsai . --sort path

Add directory token summaries:

bonsai . --directory-summaries

Use only metadata, the project map, and directory summaries when the requested budget is tiny:

bonsai . --max-tokens 800 --map-only-under 1000

Fail if output cannot fit after maximum compression:

bonsai . --max-tokens 12000 --fail-over-budget

Drop lowest-priority files if maximum compression still does not fit:

bonsai . --max-tokens 12000 --drop-low-priority

Cap very large files before the global budget pass:

bonsai . --max-file-tokens 2000

Change-Focused Context

Only include files changed since the last cached local run:

bonsai . --incremental

Show the incremental counts:

bonsai . --incremental --incremental-summary

Compare with another checkout or cache file:

bonsai . --incremental-base /path/to/base/repo
bonsai . --incremental-base /path/to/base.cache

Include tracked changes and untracked files against a git ref:

bonsai . --changed-since main

Clear the local parse cache for a repo:

bonsai cache clear
bonsai cache clear /path/to/repo

Bonsai stores file-selection options with the cache. If --include, --exclude, --exclude-generated, --max-file-bytes, or gitignore handling changes, the next incremental run includes selected files once instead of comparing against stale selection.

Output

XML is default. JSON is available with --format json. Lower-overhead text is available with --format text.

Output includes:

metadata     generated time, repo root, token budget, level, file count
project_map  file path, selected level, token count, optional hash
files        compressed file content and per-file token count

Use --no-token-counts to omit token count fields from XML/JSON output.

Schema details:

docs/output-schema.md

Supported Files

Bonsai scans:

.js .jsx .ts .tsx .py .rs .go .java .cs .swift .kt
.c .h .cpp .hpp .m .mm
.vue .svelte .astro .html
.md .json .yaml .yml .toml

Tree-sitter parsers:

JavaScript, TypeScript, Python, Rust, Go, Java, C#, Swift, Kotlin, C, C++

Compact structure extraction:

Objective-C, web templates, Markdown, JSON, YAML, TOML

Bonsai respects .gitignore and .cursorignore by default.

Use With Codex, Claude, And VS Code

Codex

This repo includes a Codex plugin:

plugins/bonsai

Add the local marketplace:

codex plugin marketplace add "$HOME/dev/bonsai/.agents/plugins"

Then install or enable bonsai in Codex.

Ask:

Use $bonsai to compress this repo before answering.

Claude Code

This repo includes a Claude Code plugin:

claude/bonsai

Run Claude Code with the plugin:

claude --plugin-dir ./claude/bonsai

Use the skill:

/bonsai:bonsai

VS Code

The VS Code extension lives here:

copilot/bonsai-vscode

Install the packaged VSIX:

code --install-extension copilot/bonsai-vscode/bonsai-vscode-0.5.3.vsix

Command Palette commands:

Bonsai: Generate and Ask
Bonsai: Generate Context
Bonsai: Copy Context Prompt
Bonsai: Copy Changed Context
Bonsai: Copy Project Map
Bonsai: Preview Project Map
Bonsai: Open Last Context

Examples

Command palette:

Output stats:

Troubleshooting

Binary not found:

Install Bonsai, put it on PATH, set BONSAI_BIN, or run cargo build --release.

Clipboard failure:

Use --output file --output-file /tmp/bonsai.xml.
Clipboard access can fail in headless shells, remote sessions, or sandboxes.

No files selected:

Run with --print-files.
Check --include, --exclude, .gitignore, and .cursorignore.
Use --no-respect-gitignore if ignored files should be included.

Output over budget:

Use a smaller path, add --exclude, increase --max-tokens, or use --level 3.

Check parser and tokenizer health:

bonsai doctor
bonsai doctor --json

It also reports the cache path, cache size, cache entry count, stored selection metadata, and stale entries.

Development

Check:

cargo check

Test:

cargo test

CLI integration tests include golden output and token-cost fixtures for large Markdown tables, large config files, import-heavy code, and many-file repos.

Build:

cargo build --release

Build the VS Code extension:

cd copilot/bonsai-vscode
npm install
npm run compile
npm run package

Names

The GitHub repository, CLI binary, Codex plugin, and Claude plugin are named bonsai.

The VS Code package is named bonsai-vscode.