Agent System

KodaCode’s agent system lets you define specialized AI personas with custom prompts, tools, permissions, and model preferences. Models delegate to agents automatically when the task fits.

Built-in Agents

Engineer (default)

Full-lifecycle development agent. Best for broad or multi-step work where you want a controller-managed workflow before code is changed. The engineer can use all tools — including code_action, rename_symbol, and subagent delegation — but broad requests go through a structured workflow instead of jumping straight into edits.

When plan_approval is enabled (default), the engineer cannot execute the approved plan until you answer the approval question.

Automatic bootstrap

The controller detects broad-scope requests (reviews, refactors, multi-step implementations) and automatically runs the explore, plan, and approve sequence without the model needing to orchestrate it. Narrow or casual prompts bypass the workflow entirely.

Engineer workflow

For broad review, improvement, refactor, or multi-step implementation requests, the engineer workflow is controller-driven:

1. Prebuild verification

   • Before the controller starts exploration/planning, the engineer must run the test tool once to establish a baseline.
   • The baseline may pass or fail. The goal is to capture the real starting state before exploration and planning.
   • This is the gate that moves the session from prebuild to preplan.

2. Explore

   • The controller runs the explorer subagent to gather architecture, file, and constraint context.
   • If completed explorer results already exist in the current session, the controller reuses them instead of re-running exploration.

3. Plan

   • The controller runs the planner subagent in structured mode. The planner returns a JSON object:

     {"summary": "...", "tasks": [{"title": "...", "kind": "implementation|analysis|report", "notes": "..."}]}

   • kind is required. implementation for code changes, analysis for audit/research, report for synthesis.
   • The controller persists those tasks itself. The planner is not the source of truth for task storage. If the planner returns invalid JSON, the controller retries once with stricter instructions.

4. Approval

   • The adopted plan is shown in the main session.
   • If plan_approval: true, execution pauses until you answer the approval question.

5. Execute

   • On approval, the first pending task is activated automatically.
   • Engineer executes tasks one at a time.
   • It cannot complete one task and start the next in the same response.

6. Review

   • The controller automatically spawns the reviewer subagent for each completed task.
   • On FAIL, the task is re-opened to in_progress with the failure details injected into the engineer’s context.
   • On PASS or CONCERN, the task stays completed and the next pending task is activated.
   • After engineer_review_limit (default 3) reviewer invocations within the current review window, the controller asks the user instead of retrying. See Reviewer for verdict format.

Workflow-owned questions

The engineer workflow can ask these controller-owned questions:

1. Plan approval

   • Question: How would you like to proceed?
   • Options:
     • Save plan and proceed
     • Proceed without saving plan files
     • Reject plan

2. Reviewer retry limit reached

   • Question: Reviewer retry limit reached. How should KodaCode proceed?
   • Options:
     • Continue fixing this task without more automatic reviews
     • Accept unresolved reviewer findings and proceed
     • Stop execution and wait for me

3. Execution stalled on the current task

   • Question: Execution is stalled on the current task. How should KodaCode proceed?
   • Options:
     • Keep working on the current task
     • Mark the current task blocked and stop
     • Stop and wait for me

Retry limits

• session.max_retries controls retryable provider/API failures only.
• session.engineer_review_limit controls engineer workflow retries:
  • reviewer reruns before the review-cap question is shown
  • repeated stalled-task execution retries before the stall question is shown
• Default engineer_review_limit is 3.

Scope

• Casual prompts such as greetings should be answered directly with no workflow.
• Narrow implementation tasks may stay model-driven.
• The full controller-managed workflow is mainly for broad requests that need exploration, planning, approval, and tracked execution.

Coder

Direct implementation agent. Reads code, understands it, and makes changes immediately — no subagents, no planning phases, no approval gates. Best for quick fixes, one-file edits, and tasks where you know exactly what you want. Same tools as engineer except no subagent delegation.

Use the coder agent when:

• The task is straightforward and doesn’t need a plan
• You want fast iteration without the explore → plan overhead
• You’re making targeted fixes across a few files

# Switch to coder via Tab cycling, /agents picker, or:
default_agent: coder

Adviser

Read-only research and advisory agent. Explores your codebase, analyzes architecture, compares approaches, and gives recommendations — without modifying any files. Has access to web_fetch for researching external documentation and solutions.

Use the adviser when:

• You want to understand how something works before changing it
• You need architectural guidance or trade-off analysis
• You’re evaluating different approaches for a feature
• You want a code review or security audit without auto-fixes

# Switch via Tab cycling or /agents picker
/adviser how should I structure the caching layer?
/adviser explain the auth flow and suggest improvements
/adviser compare REST vs GraphQL for this use case

Explorer

Fast, read-only codebase research agent. Uses the utility model for cost savings. Has only read-only tools (read, glob, grep, search, lsp, tree, git) — no write, bash, or subagent access.

/explorer how does authentication work?
/explorer what files handle database migrations?

Planner

Creates structured implementation plans. In the engineer workflow, the planner is often asked for structured output and the controller persists tasks from that output.

/planner add rate limiting to the API
/planner migrate the auth system to JWT

Polish

Detects and removes AI-generated code artifacts. Calibrates against your project’s actual style by sampling sibling files, then applies targeted fixes. Runs build/test to verify changes don’t break anything.

/polish src/handler.go
/polish clean up the recent changes

Refactor

Restructures code for clarity and maintainability without changing behavior. Orchestrates multiple subagents in parallel — explorer agents map callers and tests, then targeted edits are applied and verified.

/refactor extract the auth middleware
/refactor split the monolithic handler into separate files

Reviewer

Reviews implementation against acceptance criteria — checks correctness, not style. Read-only: cannot create, edit, or delete files. Can be routed to a separate model via the reviewer_model config.

In the engineer workflow, the reviewer is automatically triggered after each task is marked completed. It is not invoked manually by the model — the controller spawns it. On a FAIL verdict, the task is re-opened to in_progress and the engineer receives the failure details. After engineer_review_limit failed reviews (default 3), the controller stops automatic reviews and asks the user how to proceed.

Verdict format

The reviewer produces one line per acceptance criterion:

• [PASS] — criterion met
• [CONCERN] — criterion appears met, with a caveat
• [FAIL] — criterion not met, with explanation

Ends with an overall verdict line: Overall: PASS, Overall: CONCERN, or Overall: FAIL.

Review modes

• Implementation verification — inspects git diff and changed files against criteria
• Analysis verification — validates completion summary claims against repository state (no diff required)
• Report verification — checks synthesis accuracy against completed task summaries

/reviewer check the auth middleware changes against the requirements

Insight

Extracts non-obvious learnings (hidden dependencies, gotchas, implicit conventions) and persists them to AGENTS.md files. Only appends — never overwrites existing entries.

/insight
/insight analyze the patterns in the auth module

Agent Modes

• primary — shown in the agent picker (/agents) and Tab cycling
• subagent — hidden from the picker, invoked via delegation or slash commands

The engineer, coder, and adviser agents are primary — shown in the picker and Tab cycling. The explorer, planner, polish, refactor, reviewer, and insight agents are subagent mode — they’re invoked via /<agent-name> commands or by the model’s subagent tool.

Custom Agents

Create agents as markdown files with YAML frontmatter:

Global: ~/.config/kodacode/agents/reviewer.md Project-local: .kodacode/agents/reviewer.md

---
name: reviewer
description: Careful code reviewer
mode: primary
model: anthropic/claude-sonnet-4-6
tools:
  - read
  - grep
  - glob
  - search
  - lsp
  - git
permission:
  read:
    "*": allow
reasoning_budget: 5000
---

You are a careful code reviewer. Focus on correctness,
security, and maintainability. Never execute commands.

Frontmatter Fields

Field	Type	Description
name	string	Display name shown in the agent picker
description	string	Short description of the agent’s purpose
mode	string	primary (shown in picker) or subagent (hidden, invoked via tool)
model	string	utility, provider/model-id, or empty (inherit session model)
temperature	float	Sampling temperature (0-2). Omit for provider default
max_tokens	int	Max response tokens. 0 = provider default
tools	list	Allowlist of tool names. Empty = all tools available
deny_tools	list	Denylist applied after allowlist filtering
permission	object	Per-tool permission overrides (same format as global permissions)
reasoning_budget	int	Thinking token budget for extended reasoning
skills.allow	list	Skill allowlist
skills.deny	list	Skill denylist

Example: Read-Only Auditor

---
name: auditor
description: Security-focused code auditor
mode: primary
tools:
  - read
  - grep
  - glob
  - search
  - lsp
  - tree
  - git
deny_tools:
  - bash
  - write
  - edit
---

You are a security auditor. Analyze code for vulnerabilities,
injection risks, and authentication issues. Never modify files.
Report findings with file paths and line numbers.

Example: Fast Utility Agent

---
name: quick
description: Fast answers using a cheap model
mode: primary
model: utility
max_tokens: 2048
---

Answer questions concisely. Use tools only when necessary.
Prefer short, direct responses.

Model Routing

Agents inherit the session’s model by default. The model field supports three modes:

• Empty — inherits the parent session’s model
• utility — uses the configured utility_model (cheap/fast)
• provider/model-id — uses a specific model regardless of session

System Prompt Overrides

Beyond agent-level prompts, you can override the system prompt per provider or per model by dropping a markdown file in ~/.config/kodacode/prompts/:

~/.config/kodacode/prompts/
├── anthropic.md              # All Anthropic models
├── openai.md                 # All OpenAI models
├── gemini.md                 # All Google Gemini models
├── default.md                # Fallback for any provider
├── anthropic/
│   └── claude-sonnet-4-6.md  # Specific model override
└── lmstudio/
    └── qwen3-coder-30b.md    # Specific local model

Supports both .md and .txt extensions. No config changes needed — just create the file.

Resolution order

The prompt loader checks in this order, using the first match:

1. Agent system prompt — markdown body from the agent definition file
2. Per-model override — prompts/{providerID}/{modelID}.md
3. Per-provider override — prompts/{providerID}.md
4. Canonical override — prompts/anthropic.md, openai.md, gemini.md, or default.md
5. Built-in prompt — embedded in the KodaCode binary

This means you can tailor instructions for specific models without affecting other models.

Subagent Delegation

When a model uses the subagent tool, it spawns an ephemeral session with a specific agent and task. Ephemeral sessions skip compaction, title generation, and persistence for efficiency. Multiple subagents can run concurrently (up to max_subagents, default 10).

Each subagent has a timeout (default 5 minutes) after which it is cancelled. Increase this for complex tasks or slower providers:

session:
  subagent_timeout: 10   # minutes

subagent agentId="explorer" task="Find all API endpoints"
subagent agentId="planner" task="Plan the auth migration"

Example: Engineer Planning Workflow

For a broad task, the engineer workflow looks like this:

User: Add rate limiting to all API endpoints

1. Engineer records a baseline verification run first:
   test path="."

2. Controller spawns explorer subagent:
   subagent agentId="explorer" task="Find all API endpoints, middleware chain, and existing rate limiting"
   → Explorer reads router files, middleware, searches for existing rate limit code
   → Returns findings: 14 endpoints, no existing rate limiting, Chi router with middleware chain

3. Controller spawns planner subagent:
   subagent agentId="planner" task="Create a structured implementation plan from the explorer findings"
   → Planner returns structured tasks
   → Controller persists the tasks and renders the adopted plan

4. Engineer presents the approval question:
   question text="How would you like to proceed?"
   options=["Save plan and proceed", "Proceed without saving plan files", "Reject plan"]
   → You review the plan and choose how to continue

5. After approval:
   → First task becomes in_progress automatically
   → Engineer implements one task at a time
   → Reviewer verifies completed tasks against their criteria
   → Engineer continues until the task list is done or blocked

With plan_approval: true (default), the engineer cannot execute the approved plan until you approve it.

Example: Custom Agent for Database Migrations

---
name: migrator
description: Database migration specialist
mode: primary
tools:
  - read
  - write
  - edit
  - glob
  - grep
  - bash
  - git
  - lsp
  - test
permission:
  bash:
    "go test *": allow
    "go run *migrate*": allow
    "*": ask
---

You are a database migration specialist. When asked to make schema changes:

1. Check existing migrations in db/migrations/ for naming conventions
2. Create a new migration file with the next sequential number
3. Write both up and down migrations
4. Run the migration locally to verify
5. Update any affected repository layer code
6. Run tests to ensure nothing breaks

Never modify existing migration files — always create new ones.
Always include rollback (down) migrations.

Tip

Agents are loaded in priority order: built-in, then global (~/.config/kodacode/agents/), then project-local (.kodacode/agents/). Later sources override earlier ones by filename.