Your First Workspace

This guide walks you through setting up a complete Bonsai workspace from scratch — from installation to your first agent session.

Prerequisites

Claude Code — installed and configured in your project. Bonsai generates instruction files that Claude Code agents read.
Go 1.24+ — only required if installing from source.

Install Bonsai

brew install LastStep/tap/bonsai

Grab the latest from GitHub Releases:

# Example for Linux amd64
curl -sL https://github.com/LastStep/Bonsai/releases/latest/download/bonsai_Linux_amd64.tar.gz | tar xz
sudo mv bonsai /usr/local/bin/

Requires Go 1.24+:

go install github.com/LastStep/Bonsai@latest

Verify the installation:

bonsai --version

Initialize Your Project

Navigate to your project
Terminal window
```
cd your-project
bonsai init
```
Bonsai launches an interactive TUI that walks you through setup.
Project name and description

Enter a name and a short description for your project. These are used in generated files — the project name appears in agent identity files, and the description appears in INDEX.md.
```
? Project name: my-app
? Project description: A task management API with a React frontend
```
Station directory

Choose where the station (command center) lives. The default is station/ — this is where the Tech Lead agent and project scaffolding are generated.
```
? Station directory: station/
```

Scaffolding selection

Pick which project infrastructure modules to include. Three are required (INDEX, Playbook, Logs); Reports is optional.

? Select scaffolding:
  [x] index      — Project snapshot
  [x] playbook   — Status, roadmap, plans, standards
  [x] logs       — Field notes, decisions, routine log
  [ ] reports    — Completion reports (optional)

Tech Lead abilities

The Tech Lead is always installed first. You’ll see four pickers — one each for skills, workflows, sensors, and routines. Defaults are pre-selected based on the Tech Lead agent type. Required items (protocols, core sensors) are checked and locked.
- Skills picker: planning-template, issue-classification, dispatch, review-checklist (defaults)
- Workflows picker: issue-to-implementation, planning, code-review, session-logging (defaults)
- Sensors picker: session-context, scope-guard-files, context-guard, status-bar (required), plus dispatch-guard, scope-guard-commands, subagent-stop-review (defaults)
- Routines picker: backlog-hygiene, dependency-audit, doc-freshness-check, memory-consolidation, roadmap-accuracy, status-hygiene, vulnerability-scan
You can add or remove items from the defaults. Required items cannot be unchecked.
Review and confirm

Bonsai shows a summary of everything that will be generated — files, directories, hooks. Review it and confirm.

What Got Generated

After bonsai init completes, your project has this structure:

Directoryyour-project/
- .bonsai.yaml — project config (tracks all agents and components)
- .bonsai-lock.yaml — file hashes for conflict detection
- Directory.claude/
  - settings.json — auto-wired sensor hooks
- CLAUDE.md — root navigation (points agents to their workspaces)
- Directorystation/ — Tech Lead workspace + project scaffolding
  - CLAUDE.md — Tech Lead navigation table
  - INDEX.md — project snapshot
  - Directoryagent/
    DirectoryCore/ — identity.md, memory.md, self-awareness.md, routines.md
    …
    DirectoryProtocols/ — memory.md, security.md, scope-boundaries.md, session-start.md
    …
    DirectoryWorkflows/ — planning.md, code-review.md, session-logging.md, …
    …
    DirectorySkills/ — planning-template.md, review-checklist.md, …
    …
    DirectorySensors/ — session-context.sh, scope-guard-files.sh, dispatch-guard.sh, …
    …
    DirectoryRoutines/ — backlog-hygiene.md, dependency-audit.md, …
    …
  - DirectoryPlaybook/
    Status.md
    Roadmap.md
    Backlog.md
    DirectoryPlans/
    DirectoryActive/
    …
    DirectoryStandards/
    SecurityStandards.md
  - DirectoryLogs/
    FieldNotes.md
    KeyDecisionLog.md
    RoutineLog.md
  - DirectoryReports/
    report-template.md
    DirectoryPending/
    …

Every file reference inside the workspace is a clickable markdown link — you can browse the structure in GitHub, VS Code, or Obsidian.

Add a Code Agent

Now add a code agent to do the actual implementation work:

Run bonsai add
Terminal window
```
bonsai add
```
Pick an agent type
```
? Agent type:
  > backend
    frontend
    fullstack
    devops
    security
```
For this tutorial, pick backend. If you’re unsure, fullstack is a safe default for any project.
Customize abilities

Just like during bonsai init, you’ll see pickers for skills, workflows, and sensors. Defaults are pre-selected based on the agent type. For a backend agent:
- Skills: coding-standards, testing, database-conventions
- Workflows: plan-execution, reporting, session-logging
- Sensors: session-context, scope-guard-files (required), plus any extras you want
Review and confirm

Bonsai generates the code agent’s workspace in a new directory (e.g., backend/).

After adding the backend agent, your project now has:

Directoryyour-project/
- .bonsai.yaml — updated with the new agent
- .claude/settings.json — updated with new sensor hooks
- Directorystation/ — Tech Lead workspace (unchanged)
  - …
- Directorybackend/ — new code agent workspace
  - CLAUDE.md — backend agent navigation
  - Directoryagent/
    DirectoryCore/ — identity.md, memory.md, self-awareness.md
    …
    DirectoryProtocols/ — memory.md, security.md, scope-boundaries.md, session-start.md
    …
    DirectoryWorkflows/ — plan-execution.md, reporting.md, session-logging.md
    …
    DirectorySkills/ — coding-standards.md, testing.md, database-conventions.md
    …
    DirectorySensors/ — session-context.sh, scope-guard-files.sh
    …

Start Your First Session

Open your project in Claude Code and start a conversation:

You:    Hi, get started
Agent:  [reads identity, checks memory, loads protocols, reviews status,
         flags any overdue routines...]

Wait for the agent to report its status, then give it work:

You:    I need a REST API for user profiles — CRUD endpoints with pagination
Lead:   [asks clarifying questions, researches codebase, writes plan]

The Tech Lead will write an implementation plan to station/Playbook/Plans/Active/. Review the plan, then dispatch it:

You:    Looks good. Dispatch to the backend agent.
Lead:   [dispatch-guard validates -> dispatches with worktree isolation]

What to Try Next

Read How Bonsai Works to understand the full architecture
Learn about Abilities — skills, workflows, and protocols
Study Working With Agents for communication patterns that get the best results
Browse the Catalog to see all available abilities, sensors, and routines
Explore Customizing Abilities to tailor the workspace to your project