Troubleshooting

bonsai init says config already exists

Symptom: Running bonsai init fails with a message that .bonsai.yaml already exists.

Cause: The project has already been initialized with Bonsai.

Solution: Use bonsai add to install additional agents or abilities, or bonsai update to sync the workspace with the latest catalog. If you want to start fresh, delete .bonsai.yaml and .bonsai-lock.yaml first.

# Add a new agent to an existing project
bonsai add

# Or start completely fresh
rm .bonsai.yaml .bonsai-lock.yaml
bonsai init

Build errors after editing generated files

Symptom: After manually editing files in the agent/ directory, running bonsai update or bonsai add produces unexpected results or errors.

Cause: Bonsai tracks generated files by content hash. When you edit a generated file, the hash no longer matches, and Bonsai treats it as a conflict on the next run.

Solution: Run bonsai update to sync your workspace. Bonsai will detect modified files and prompt you to skip, overwrite, or backup and overwrite each one.

bonsai update

If you intentionally modified a file and want to keep your changes, choose Skip when prompted. Your custom version will be preserved.

Sensor hooks not running

Symptom: Sensors (scope guards, context injection, status bar) are not triggering during Claude Code sessions.

Cause: The sensor hooks may not be configured in .claude/settings.json, or the sensor script may not be installed.

Solution:

1. Verify the sensor is installed:

   bonsai list

   Check that the sensor appears in the installed sensors list for the relevant agent.

2. Check .claude/settings.json (inside the agent’s workspace directory) for hook entries. Each sensor should have a corresponding hook configuration.

3. Run bonsai update to regenerate the settings file:

   bonsai update

4. Make sure the sensor script exists and is executable:

   ls -la station/agent/Sensors/

Tip

Sensors are configured per-workspace in <workspace>/.claude/settings.json. If you are launching Claude Code from the project root, make sure the root-level .claude/settings.json also has the relevant hooks.

”Agent not found” when running bonsai add

Symptom: Running bonsai add or selecting an agent type fails with an agent-not-found error.

Cause: The agent type name must match one of the 6 catalog types exactly: tech-lead, backend, frontend, fullstack, devops, security.

Solution: Run bonsai catalog to see available agent types and their exact names. Use the interactive picker in bonsai add to select the correct one.

bonsai catalog

Lock file conflicts

Symptom: Running bonsai add or bonsai update shows conflict warnings for multiple files.

Cause: Files generated by Bonsai have been modified since they were last written. Bonsai detects this by comparing SHA-256 hashes stored in .bonsai-lock.yaml against the current file contents.

Solution: For each conflict, Bonsai prompts you with three options:

• Skip — Keep your modified version. The file will not be updated.
• Overwrite — Replace your version with the freshly generated one. Your changes are lost.
• Backup & Overwrite — Your file is saved as filename.bak, then the new version is written.

If you have many conflicts and want to accept all new versions:

# Regenerate everything (will prompt for conflicts)
bonsai update

Note

Scaffolding files (INDEX.md, Playbook/, Logs/, Reports/) never conflict. They use a write-once policy: if the file exists, it is always skipped.

Cannot remove the Tech Lead agent

Symptom: Running bonsai remove tech-lead fails or warns that removal is not possible.

Cause: The Tech Lead agent owns the station directory, which contains the shared project scaffolding (Playbook, Logs, Reports) that other agents reference. It must be the last agent removed.

Solution: Remove all code agents first, then remove the Tech Lead:

bonsai remove backend
bonsai remove frontend
bonsai remove tech-lead

Custom files not detected by bonsai update

Symptom: You created a custom skill, sensor, or routine file, but bonsai update does not pick it up.

Cause: Custom files must be in the correct directory and have valid YAML frontmatter for Bonsai to detect them.

Solution: Verify the following:

1. Correct directory: Custom files must be in the agent’s ability directory:

   • Skills: <workspace>/agent/Skills/<name>.md
   • Sensors: <workspace>/agent/Sensors/<name>.sh
   • Routines: <workspace>/agent/Routines/<name>.md

2. Valid frontmatter: The file must start with YAML frontmatter between --- delimiters:

   ---
   description: What this custom ability does
   ---
   
   Content here...

   For sensors, also include event (and optionally matcher):

   #!/bin/bash
   # ---
   # description: My custom sensor
   # event: PreToolUse
   # matcher: Edit
   # ---

   For routines, also include frequency:

   ---
   description: My custom routine
   frequency: 7 days
   ---

3. Run update:

   bonsai update

See the Creating Custom Skills, Creating Custom Sensors, and Creating Custom Routines guides for complete examples.