Skip to content
Bonsai

Configuration

The .bonsai.yaml file is the project configuration generated by bonsai init. It lives at the root of your project and tracks the project name, installed agents, their abilities, and scaffolding selections.

ProjectConfig

Section titled “ProjectConfig”

The root object in .bonsai.yaml.

FieldTypeRequiredYAML TagDescription
project_namestringYesproject_nameThe name of the project
descriptionstringNodescriptionOne-line project description
docs_pathstringNodocs_pathPath to the documentation/station directory (e.g., station/)
scaffolding[]stringNoscaffoldingList of installed scaffolding items (e.g., index, playbook, logs, reports)
agentsmap[string]InstalledAgentNoagentsMap of agent name to agent configuration. Key is the agent type name.

InstalledAgent

Section titled “InstalledAgent”

Each entry in the agents map describes one installed agent.

FieldTypeRequiredYAML TagDescription
agent_typestringYesagent_typeThe agent type identifier (e.g., tech-lead, backend)
workspacestringYesworkspacePath to the agent’s workspace directory (e.g., station/, backend/)
skills[]stringYesskillsList of installed skill names
workflows[]stringYesworkflowsList of installed workflow names
protocols[]stringYesprotocolsList of installed protocol names
sensors[]stringYessensorsList of installed sensor names
routines[]stringYesroutinesList of installed routine names
custom_itemsmap[string]CustomItemMetaNocustom_itemsMetadata for user-created custom items (parsed from frontmatter)

CustomItemMeta

Section titled “CustomItemMeta”

Metadata for user-created custom abilities. These are parsed from YAML frontmatter in custom files and stored in the config so Bonsai can track them.

FieldTypeRequiredYAML TagDescription
display_namestringNodisplay_nameHuman-readable name for the custom item
descriptionstringYesdescriptionDescription of the custom item
eventstringNoeventHook event (sensors only, e.g., PreToolUse)
matcherstringNomatcherTool filter (sensors only, e.g., Edit|Write)
frequencystringNofrequencyExecution frequency (routines only, e.g., 7 days)

Example

Section titled “Example”

This is the actual .bonsai.yaml from the Bonsai project itself (Bonsai manages its own workspace):

project_name: Bonsai
description: CLI tool for scaffolding Claude Code agent workspaces
docs_path: station/
scaffolding:
  - index
  - playbook
  - logs
  - reports
agents:
  tech-lead:
    agent_type: tech-lead
    workspace: station/
    skills:
      - planning-template
      - review-checklist
      - issue-classification
      - pr-creation
    workflows:
      - code-review
      - planning
      - pr-review
      - security-audit
      - session-logging
      - test-plan
      - session-wrapup
      - issue-to-implementation
      - routine-digest
    protocols:
      - memory
      - scope-boundaries
      - security
      - session-start
    sensors:
      - context-guard
      - scope-guard-files
      - session-context
      - status-bar
      - routine-check
      - agent-review
      - dispatch-guard
      - subagent-stop-review
    routines:
      - backlog-hygiene
      - dependency-audit
      - doc-freshness-check
      - memory-consolidation
      - roadmap-accuracy
      - status-hygiene
      - vulnerability-scan
    custom_items:
      pr-creation:
        description: >-
          How to create well-structured pull requests — branch naming,
          title conventions, body template, draft workflow.
      routine-digest:
        description: >-
          Synthesize all pending routine reports into a consolidated
          digest — extract actionable items, present interactive Q&A
          for decisions, route results to plans or backlog.
      session-wrapup:
        description: >-
          End-of-session verification, review, cleanup, and summary —
          triggered by session wrap-up phrases.
Section titled “Related”