Skip to main content

Bonsai

Bonsai is a suite of local-first developer tools for worktree isolation, agent-driven implementation, local PR review, run triage, and nightly code-factory PRs.

The original Bonsai CLI is still the foundation: it runs multiple local development branches side by side, creates and tracks git worktrees, assigns each branch a stable port slot, writes generated environment files, and keeps local HTTPS routing predictable through Caddy. The wider suite builds on the same local-first model for agent lifecycles and review workflows.

Use Bonsai when you often need to switch between feature branches, test several branches at once, hand an AI agent exact per-worktree ports and URLs, review PRs locally before posting comments, or run controlled automation that produces reviewable artifacts.

Products​

  • Bonsai CLI - per-branch worktrees, ports, env files, and local URLs.
  • Devgraph - a watchable lifecycle DAG for ticket, prompt, and PR review workflows.
  • Cloud Agents - one local inbox and artifact layout for devgraph, Codex, and Claude runs.
  • PR Review Dashboard - local Claude/Codex PR review triage with human approval before posting.
  • Factory - a nightly code factory that opens verified PRs and never merges.

What Bonsai Manages​

  • A workspace rooted at a project directory.
  • A default worktree for the base branch.
  • Managed worktrees for feature branches.
  • Generated .env.local values for branch-specific ports and names.
  • Optional Caddy snippets for local HTTPS URLs.
  • Configured lifecycle commands and hooks with managed logs.
  • Interactive shell checkout, PR worktrees, and ad hoc command execution per worktree or across all worktrees.
  • Rich and JSON workspace, process, and global workspace summaries for humans, scripts, and AI agents.
  • State repair, generated-file sync, workspace diagnostics, PR-aware cleanup, and Compose teardown during removal.

Core Workflow​

bonsai clone git@github.com:org/my-app.git my-app
bonsai add ma-123-implement-auth
# or: bonsai add --pr 123
bonsai checkout ma-123-implement-auth
bonsai start
bonsai logs --command start
bonsai status
bonsai open

bonsai checkout needs shell integration to change the parent shell's working directory. Without the integration, it prints the resolved path and setup instructions instead.

Find Your Way Around​

  • Product Docs — every app and product in this repository.
  • Install and the Quickstart — from zero to a running app.
  • Configuration — everything .bonsai.toml controls.
  • Worktrees — add, checkout, remove, move, PR worktrees, and PR-aware cleanup.
  • Running Apps — foreground start, background up/down, stop, restart, exec, each, and logs.
  • Ports & URLs — port slots, machine-global Caddy routing, open, urls, and ports.
  • Workspace Views — list, list --all, ps, status, and agent context output.
  • Command Reference — every command and option, generated from the CLI.
  • Troubleshooting — doctor, repair, and common symptoms.