Agents

Bonsai agents are Claude Code agents equipped with a structured instruction layer — identity, memory, protocols, skills, workflows, and sensors. Think of each agent as a new hire who arrives with full onboarding materials:

What a new hire needs	Bonsai equivalent
Role description	Identity — job title, mindset, relationships
Company handbook	Protocols — security policy, scope boundaries
Playbooks	Workflows — how to plan, review, report
Domain training	Skills — coding standards, API patterns
Automated guardrails	Sensors — catch mistakes in real time
Maintenance duties	Routines — periodic audits on a schedule

When an agent starts a session, it reads its identity, checks its memory, follows its startup protocol, and gets context injected by sensors — all before you ask it anything.

The Six Agent Types

Tech Lead

Architects, plans, reviews — never writes application code.

The orchestrator. It reads requirements, writes implementation plans, dispatches work to code agents via worktrees, and reviews their output. Every project starts with a Tech Lead.

Default skills: planning-template, issue-classification, dispatch, review-checklist.

Backend

API, database, server-side logic.

Executes backend implementation plans. Knows coding standards, testing conventions, and database patterns. Focused on server-side code.

Default skills: coding-standards, testing, database-conventions.

Frontend

UI components, state management, styling.

Executes frontend plans. Equipped with coding standards, testing, and UI/UX design knowledge. Focused on client-side code.

Default skills: coding-standards, testing, design-guide.

Full-Stack

End-to-end — UI, API, database, auth, tests.

A generalist code agent that handles the full stack. Carries the broadest set of default skills — coding standards, testing, design, databases, API design, and auth patterns.

Default skills: coding-standards, testing, design-guide, database-conventions, api-design-standards, auth-patterns.

DevOps

Infrastructure-as-code, CI/CD, containers, deployment.

Manages infrastructure. Comes with IaC and container standards, plus the iac-safety-guard sensor that blocks dangerous commands like terraform destroy.

Default skills: coding-standards, iac-conventions, container-standards.

Security

Vulnerability audits, auth review, dependency scanning.

Audits code for security issues. Equipped with auth patterns, review checklists, and the security-audit workflow. The api-security-check sensor auto-detects common vulnerabilities in code changes.

Default skills: coding-standards, testing, auth-patterns, review-checklist.

The Tech Lead Model

The Tech Lead is the central agent in every Bonsai project. It operates fundamentally differently from code agents:

  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

Tech Lead does	Code agents do
Writes implementation plans	Executes plans step-by-step
Dispatches work via worktrees	Implements in isolated branches
Reviews code agent output	Writes completion reports
Runs routines (maintenance)	Focuses on implementation
Manages scaffolding (status, roadmap, plans)	References scaffolding for context

Caution

The Tech Lead never writes application code. It creates plans, dispatches them to code agents via worktree-isolated subagents, and reviews the output. The dispatch-guard sensor enforces this — every dispatch must reference a plan and use worktree isolation.

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.

Which Agent Type Do I Need?

Start with the Tech Lead (always installed via bonsai init), then add code agents based on your project:

Your situation	Add these agents	Why
Solo developer, any stack	fullstack	One agent handles everything — UI, API, database, tests
Separated frontend and backend	backend + frontend	Domain-specific skills and conventions for each layer
Infrastructure work	+ devops	IaC conventions, container standards, iac-safety-guard sensor
Security-sensitive project	+ security	Vulnerability scanning, dependency audits, security-audit workflow
Full team	backend + frontend + devops + security	Maximum specialization and coverage

Tip

Start small. You don’t need every code agent from day one. Begin with fullstack for a solo project, then split into specialized agents as complexity demands. bonsai add is designed to be run incrementally.

Multi-Agent Workspace Patterns

Solo Developer

The simplest setup. One Tech Lead, one Full-Stack agent:

  You
   └── Tech Lead (station/)
        └── Full-Stack (fullstack/)

The Tech Lead plans features and reviews work. The Full-Stack agent implements everything. Good for small-to-medium projects where you don’t need domain specialization.

Separated Concerns

Split code agents by domain for larger projects:

  You
   └── Tech Lead (station/)
        ├── Backend (backend/)
        └── Frontend (frontend/)

Each agent has domain-specific skills and conventions. The Tech Lead coordinates across both — planning features that span frontend and backend, reviewing each agent’s output, maintaining shared standards.

Full Team

Maximum specialization with infrastructure and security coverage:

  You
   └── Tech Lead (station/)
        ├── Backend (backend/)
        ├── Frontend (frontend/)
        ├── DevOps (devops/)
        └── Security (security/)

The DevOps agent adds iac-safety-guard (blocks dangerous infrastructure commands) and infrastructure routines. The Security agent adds api-security-check (detects vulnerabilities in code), scope-guard-commands (blocks execution), and the security-audit workflow.

How Agents Are Installed

• Tech Lead: Always installed during bonsai init. It lives in the station directory alongside scaffolding.
• Code agents: Added with bonsai add. Each gets its own workspace directory (e.g., backend/, frontend/). The interactive picker lets you select agent type and customize abilities.

Each agent gets:

• A CLAUDE.md navigation file with cross-linked references
• An agent/ directory with Core (identity, memory), Protocols, Workflows, Skills, and Sensors
• Hook entries in .claude/settings.json for all installed sensors
• A config entry in .bonsai.yaml tracking all installed components

See Your First Workspace for a step-by-step walkthrough.