Bonsai

On this repository Bonsai reduced ~76,911 raw tokens to 13,450 shrunk tokens (~82.5% savings) using AST skeletonization — keep your LLM contexts small, accurate, and cheap.

Naming note: the GitHub repository, CLI binary, Codex plugin, and Claude plugin are bonsai; the VS Code package is bonsai-vscode.

Examples

Command:

Output:

Quick Start

Run inside a repo:

bonsai .

This writes:

bonsai.xml

Copy it into your LLM and ask:

Use this Bonsai XML as repo context. Summarize the architecture and tell me where to start reading.

Need the binary? Download a release. No Rust needed.

macOS Apple Silicon:

curl -L -o bonsai https://github.com/MickyBalladelli/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/MickyBalladelli/bonsai/releases/latest/download/bonsai-linux-x64
chmod +x bonsai
sudo mv bonsai /usr/local/bin/bonsai

Or install from source:

cargo install --path .

Install straight from GitHub:

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

What It Is Good For

Use Bonsai when you want broad repo context that is visible and repeatable:

Summarize this project.
Explain the architecture.
Find likely entry points.
Prepare context before asking another LLM.
Compare token savings before sending repo context.

It is less useful when the agent already has the exact file or function you want edited.

Install

Release binaries:

bonsai-macos-arm64
bonsai-linux-x64

Download from:

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

From this repo:

cargo install --path .

From git:

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

Or build a local binary:

cargo build --release
target/release/bonsai .

Tagged releases publish:

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

The Codex plugin, Claude Code plugin, and VS Code extension find the binary in this order:

BONSAI_BIN
bonsai on PATH
repo-local target/release/bonsai

Advanced Commands

Paste-ready clipboard prompt:

bonsai . --prompt --output clipboard

Custom paste-ready prompt:

bonsai . --ask-template "Use this repo context to find likely bugs." --output clipboard

Architecture map:

bonsai . --level 3

Detailed repo context:

bonsai . --max-tokens 12000 --level 2

Only scan src:

bonsai src

Write somewhere else:

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

Write JSON:

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

Write a paste-ready prompt file:

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

Show selected files:

bonsai . --print-files

Only write the project map:

bonsai . --project-map-only

Write metadata and project map without file bodies:

bonsai . --no-content

Sort output:

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

Add per-directory token summaries:

bonsai . --directory-summaries

Fail when output is still over budget after maximum compression:

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

Write starter agent instructions:

bonsai init-agent
bonsai init-agent . --force

Measure token savings:

bonsai . --max-tokens 12000 --stats

Filter files:

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

Skip files larger than the default 1 MiB limit:

bonsai . --max-file-bytes 2097152

Use --max-file-bytes 0 to disable the size cap.

Use With Agents

Plain Paste

Generate context:

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

Paste /tmp/bonsai-prompt.txt into an LLM. It starts with:

Use this repo context to explain the architecture, identify the main entry points, and tell me where to start reading.

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.

The helper command is:

plugins/bonsai/skills/bonsai/scripts/run_bonsai.sh . 12000 2 /tmp/bonsai.xml

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

The helper command is:

claude/bonsai/bin/bonsai-claude . 12000 2 /tmp/bonsai.xml

For local marketplace testing:

claude plugin marketplace add .

Then inside Claude Code:

/plugin install 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.3.1.vsix

Run Command Palette:

Bonsai: Generate and Ask

If chat does not open automatically, paste the copied prompt into Copilot Chat, ChatGPT, or Codex in VS Code.

Other commands:

Bonsai: Generate Context
Bonsai: Copy Context Prompt
Bonsai: Copy Project Map
Bonsai: Preview Project Map
Bonsai: Open Last Context

Levels

--level 1 keeps full code first, then shrinks files if the token budget is too small.

--level 2 keeps imports, signatures, types, classes, and function shapes. Function bodies become ....

--level 3 keeps a compact tree map only.

Before And After

Full source:

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

Skeleton:

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

Tree map:

fn greet(name: &str) -> String

Markdown and config files are treated differently from source code. Bonsai keeps compact headings, important lines, and top-level config shape.

Output Format

XML is the default. Use --format json for JSON.

Both formats include:

metadata: generated time, repo root, token budget, compression level, file count
project map: file paths, selected levels, per-file token counts
files: compressed file contents with per-file token counts

Schema notes live in:

docs/output-schema.md

Supported Files

Bonsai scans:

.js .jsx .ts .tsx .py .rs .go .java .cs .swift .kt .md .json .yaml .yml .toml

It parses JavaScript, TypeScript, Python, Rust, Go, Java, C#, Swift, and Kotlin with tree-sitter. Docs and config files use compact line-based context.

It respects .gitignore and .cursorignore.

Troubleshooting

Binary not found:

Install with `cargo install --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` when ignored files should be included.

Output over budget:

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

Development

Check:

cargo check

Test:

cargo test

Build release binary:

cargo build --release

Build VS Code extension:

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

Release

CI and releases are configured in:

.github/workflows/ci.yml
.github/workflows/release.yml

Create a release:

git tag v0.3.1
git push origin v0.3.1

Version bump checklist:

Cargo.toml
copilot/bonsai-vscode/package.json
copilot/bonsai-vscode/package-lock.json
plugins/bonsai/.codex-plugin/plugin.json
claude/bonsai/.claude-plugin/plugin.json
.claude-plugin/marketplace.json, if pinning marketplace version
README install/package examples