How Bonsai Works

Bonsai is a CLI generator, not a runtime. It runs once to write a workspace under station/ plus per-agent workspaces, then Claude Code agents read those files via hooks at session start and during tool use.

What bonsai init generates

Generated artifact	What it does
agent/Core/identity.md + agent/Core/memory.md	Who the agent is and what it carries forward between sessions
agent/Protocols/ (security.md, scope-boundaries.md, session-start.md)	Hard rules read at the top of every session
agent/Workflows/	Step-by-step procedures (planning, code review, PR review, audits) loaded on demand
agent/Skills/	Domain knowledge (standards, checklists, templates) referenced during work
agent/Sensors/*.sh	Shell scripts wired into Claude Code hooks (SessionStart, PreToolUse, Stop)
agent/Routines/ + agent/Core/routines.md	Periodic maintenance procedures with a tracked dashboard (Tech Lead only)
station/Playbook/, station/Logs/, station/Reports/	Shared scaffolding — status, roadmap, plans, decisions, reports — referenced by every agent

Note

Every generated file is tracked in .bonsai-lock.yaml with a content hash. Re-running bonsai init or bonsai add detects user edits and prompts before overwriting them.

The station

station/ is the Tech Lead’s workspace and the shared scaffolding every code agent’s plans, status, and decisions reference. Code agents (backend, frontend, devops, security) get their own <agent>/ workspaces, but they all link back to station/Playbook/Status.md, station/Playbook/Plans/Active/, and station/Logs/KeyDecisionLog.md so coordination lives in one place under version control.

The instruction stack

Each agent’s instructions are layered, from foundational to automated:

  Layer 6 │ Sensors       │ Automated enforcement (hook scripts)
  Layer 5 │ Routines      │ Periodic maintenance procedures (Tech Lead)
  Layer 4 │ Skills        │ Domain knowledge and standards
  Layer 3 │ Workflows     │ Step-by-step task procedures
  Layer 2 │ Protocols     │ Hard rules (security, scope, startup)
  Layer 1 │ Core          │ Identity + memory + self-awareness

Note

Layers exist because they load at different times. Core and Protocols load every session via the session-context sensor on SessionStart — identity, memory, and the non-negotiable rules are always in scope. Workflows and Skills are pulled in on demand when the agent starts a matching task. Sensors fire automatically on Claude Code tool-use events: PreToolUse to block writes outside an agent’s workspace, PostToolUse to checklist a dispatched agent’s output, Stop to refresh the status bar after every reply.

How it works

bonsai init sets up the station with the Tech Lead. You talk to the Tech Lead; it plans, dispatches, and reviews. Code agents execute.

  You (human)
   └── Tech Lead (station/)      plans, reviews, orchestrates, runs routines
        ├── Backend (backend/)    API, database, server logic
        ├── Frontend (frontend/)  UI, components, styling
        ├── DevOps (devops/)      infrastructure, CI/CD
        └── Security (security/)  audits, scanning

Caution

The Tech Lead never writes application code. It creates plans, dispatches them to code agents via worktree-isolated subagents, and reviews the output.

Tip

You don’t have to go through the Tech Lead for everything. Quick fixes and small tasks work fine directly with a code agent. The Tech Lead shines when work needs planning, coordination, or cross-agent review.

What gets generated

After bonsai init followed by bonsai add backend:

• Directoryyour-project/

  • .bonsai.yaml — project config
  • .bonsai-lock.yaml — file tracking (hashes for conflict detection)
  • .claude/settings.json — auto-wired sensor hooks
  • CLAUDE.md — root navigation
  • Directorystation/ — Tech Lead workspace + project scaffolding

    • CLAUDE.md — navigation (cross-linked)
    • INDEX.md — project snapshot
    • Directoryagent/

      • DirectoryCore/ — identity, memory, self-awareness

        • …
      • DirectoryProtocols/ — security, scope, startup sequence

        • …
      • DirectoryWorkflows/ — planning, code-review, audit, etc.

        • …
      • DirectorySkills/ — standards, patterns, checklists

        • …
      • DirectorySensors/ — hook scripts (.sh)

        • …
      • DirectoryRoutines/ — maintenance procedures

        • …
    • DirectoryPlaybook/ — status, roadmap, plans, standards

      • …
    • DirectoryLogs/ — field notes, decisions, routine log

      • …
    • DirectoryReports/ — completion reports

      • …
  • Directorybackend/ — code agent workspace

    • CLAUDE.md — agent-specific navigation
    • Directoryagent/

      • DirectoryCore/ — identity, memory, self-awareness

        • …
      • DirectoryProtocols/ — hard rules

        • …
      • DirectoryWorkflows/ — task procedures

        • …
      • DirectorySkills/ — domain knowledge

        • …
      • DirectorySensors/ — hook scripts

        • …

Every file reference is a clickable markdown link — open the workspace in Obsidian to see the full knowledge graph, or browse it on GitHub.