Product Docs
Bonsai is a suite of local-first developer tools. The packages share a bias toward local credentials, reviewable artifacts, and explicit gates before anything is pushed, posted, or opened for review.
| Product | Package | Path | Primary job |
|---|---|---|---|
| Bonsai CLI | bonsai | apps/bonsai | Manage per-branch git worktrees, ports, generated env files, and local URLs. |
| Devgraph | @bonsai/devgraph | apps/devgraph | Run a ticket or prompt through an agent-visible implementation DAG. |
| Cloud Agents | @bonsai/cloud-agents | apps/cloud-agents | Launch and monitor local agent runs through one normalized control plane. |
| PR Review Dashboard | @bonsai/pr-review-dashboard | apps/pr-review-dashboard | Review a GitHub PR with Claude and Codex findings in a local triage UI. |
| Factory | @bonsai/factory | apps/factory | Run a nightly human-in-the-loop code factory that opens verified PRs. |
How the Products Fit Together
- Bonsai CLI creates isolated worktrees and stable local URLs so humans and agents can work on multiple branches at once.
- Devgraph uses a deterministic graph around Codex agents to turn a ticket, prompt, or PR review task into verified artifacts.
- Cloud Agents normalizes run artifacts across devgraph, Codex, and Claude so blocked, failed, running, and complete runs are easy to triage.
- PR Review Dashboard focuses on one workflow: local, subscription-authenticated AI PR review with human approval before posting.
- Factory automates low-risk improvement discovery and PR creation while leaving merge decisions to humans.
Shared Conventions
- Local run artifacts live under
.lifecycle/runs/<run-id>/when a product needs durable run state. - External write actions are gated: the dashboard waits for a UI confirmation before posting a review; factory opens PRs but never merges; devgraph pushes and opens PRs only after its verification gates.
- CLI tools use local auth stores where possible:
gh, Codex CLI auth, Claude CLI auth, Atlassian CLI, or environment variables for provider-specific modes. - Monorepo development is managed with Bun workspaces and Turborepo from the repository root:
bun install
bunx turbo run typecheck test build
Internal Packages
The apps also share private workspace packages:
@bonsai/core(packages/core) contains shared Bonsai workspace and config utilities.@bonsai/protocol(packages/protocol) defines normalized run ids, status files, blocker files, and other artifact schemas used by agent-facing products.@bonsai/tsconfig(packages/tsconfig) centralizes TypeScript config.
These packages are implementation dependencies rather than standalone user products, so the product pages focus on the apps under apps/.