### Install Dependencies and Run Documentation Site

Source: https://github.com/sageil/kodacode/blob/main/CONTRIBUTING.md

Navigate to the documentation site directory, install its dependencies using pnpm, and start the development server to preview the documentation.

```bash
cd site
pnpm install
pnpm run dev
```

--------------------------------

### Install and Run Development Server

Source: https://github.com/sageil/kodacode/blob/main/site/README.md

Use these tasks to manage dependencies and start the local development server. Requires Node.js 22+ and pnpm.

```bash
task install   # install dependencies
task dev       # start dev server at http://localhost:4321/
```

```bash
task build     # build static site to dist/ 
task preview   # build + preview locally
task clean     # remove build artifacts
```

--------------------------------

### Install KodaCode with Go

Source: https://github.com/sageil/kodacode/blob/main/README.md

Install the KodaCode command-line tool using Go. Ensure your Go environment is set up.

```bash
go install github.com/sageil/kodacode/cmd/kodacode@latest
```

--------------------------------

### Install KodaCode with Homebrew

Source: https://github.com/sageil/kodacode/blob/main/README.md

Use Homebrew to install KodaCode. Ensure you tap the repository first.

```bash
brew tap sageil/tap && brew install --cask kodacode
```

--------------------------------

### Install from Source

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/getting-started/installation.mdx

Build and install KodaCode from its source code. This method requires Go 1.26+ and Task (https://taskfile.dev).

```bash
git clone https://github.com/sageil/kodacode.git
cd kodacode
task build
mv bin/kodacode /usr/local/bin/
```

--------------------------------

### Example Budget Settings

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/budgets.mdx

Illustrates a configuration for setting individual session and total budget limits with warning levels.

```yaml
sessions:
  budget: 3
  budget_warn: 0.75
  total_budget: 25
  total_budget_warn: 0.8
```

--------------------------------

### Configure MCP Server

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/reference/configuration.mdx

Example of configuring an external Model Context Protocol (MCP) tool using stdio. This setup specifies the server name, type, command to execute, arguments, environment variables, and tool hints for search functionality.

```yaml
mcp:
  servers:
    - name: docs
      type: stdio
      command: node
      args:
        - /Users/me/tools/company-docs-mcp/dist/server.js
      env:
        DOCS_TOKEN: "replace-with-your-token"
      tool_hints:
        search:
          summary: Search internal product documentation.
          guidance: Use for billing, plan, and support-procedure questions.
```

--------------------------------

### Full Primary Agent Example

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/agents.mdx

This example demonstrates a complete primary agent definition with delegation guidance. It includes frontmatter for description, model, mode, allowed tools, and disallowed tools, followed by a detailed prompt body.

```markdown
---
description: Delivery-focused engineer with planner and reviewer handoffs
model: openai/gpt-5-mini
mode: all
AllowTools:
  - read
  - search
  - symbols
  - definition
  - diagnostics
  - refs
  - trace
  - apply_patch
  - write
  - bash
  - git_diff
  - delegate
  - question
  - task_workflow
DisallowedTools:
  - task_review
---

You are the delivery agent for this repository.

<workflow>
Own the main implementation from start to finish.

When the task needs architecture mapping or repo-scoped planning before edits,
delegate to `planner`.

If the user explicitly asks for a plan, implementation sequence, architecture
map, design exploration, or repo-scoped "what needs to change" analysis,
delegate to `planner` unless the work is obviously limited to one or two
files.

When implementation is complete and you want an acceptance pass before
finishing, delegate to `reviewer`.

Use `task_workflow` when the work naturally breaks into durable steps.
</workflow>

<execution>
Read the relevant code before editing.
Prefer small, verifiable changes.
Use `question` only when a real user decision is required.
</execution>

<delegation_examples>
- Delegate to `planner` for: "Map the auth flow and identify the files that must change."
- Delegate to `reviewer` for: "Review the patch for regressions and missing tests."
</delegation_examples>

```

--------------------------------

### Install KodaCode with Curl

Source: https://github.com/sageil/kodacode/blob/main/README.md

Quickly install KodaCode using a curl command to download and execute the installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/sageil/kodacode/main/install.sh | sh
```

--------------------------------

### Budget Configuration Example

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/budgets.mdx

Defines session and total budget limits and warning thresholds in KodaCode's configuration.

```yaml
sessions:
  budget: 5              # cap one session at $5
  budget_warn: 0.8       # warn at 80% of budget
  total_budget: 100      # cap all stored sessions at $100
  total_budget_warn: 0.8 # warn at 80% of total_budget
```

--------------------------------

### Search Configuration Example

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/search.mdx

Configure search settings including directories to skip, embedding model details, and cache location.

```yaml
search:
  skip_dirs: [coverage, .next]                     # optional extra directory names to ignore
  embeddings_model: openai/text-embedding-3-small  # required for hybrid mode
  embeddings_dimensions: 1536                       # optional; omit to use the model default
  prewarm_embeddings: false                         # embed workspace files on session open
  index_dir: ~/.local/state/kodacode/search         # cache location
```

--------------------------------

### Example of Good Project Memory Entry

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/project-memory.mdx

This example shows a concise project memory entry that includes durable takeaways and the file path for a larger artifact.

```markdown
Performance optimization plan stored in docs/performance-plan.md.
Durable takeaways: API hot paths are project list aggregation and dashboard queries; avoid reintroducing N+1 reads; prefer cached summary endpoints for dashboard cards.
```

--------------------------------

### Project-Local Skill Mention

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/skills.mdx

Example of using a project-local skill named 'release' to prepare release notes from the current branch.

```text
$release prepare the 1.8.0 release notes from the current branch

```

--------------------------------

### Build and Run KodaCode

Source: https://github.com/sageil/kodacode/blob/main/CONTRIBUTING.md

Clone the repository, build the project using Task, and run the executable. Ensure you have Go and Task installed.

```bash
git clone https://github.com/<your-username>/kodacode.git
cd kodacode

task build

test

./bin/kodacode
```

--------------------------------

### Example of Bad Project Memory Entry

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/project-memory.mdx

This example illustrates an overly verbose project memory entry that should instead be stored in a separate workspace file.

```markdown
Full 4-page performance review with phase-by-phase implementation detail, temporary findings, and one-off task notes...
```

--------------------------------

### Complete Search Configuration

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/search.mdx

A comprehensive example of KodaCode search configuration, including provider setup and all public search settings.

```yaml
version: 1

providers:
  - id: openai

search:
  index_dir: /Users/you/.local/state/kodacode/search
  skip_dirs:
    - coverage
    - dist
    - .next
  embeddings_model: openai/text-embedding-3-small
  embeddings_dimensions: 1536
  prewarm_embeddings: true
```

--------------------------------

### Configure KodaCode Model Settings

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/getting-started/quick-start.mdx

Example configuration file to set default providers and models. This can be set in `~/.config/kodacode/config.yaml` to establish default routes.

```yaml
version: 1

providers:
  - id: openai
  - id: anthropic

model:
  primary: openai/gpt-5

utility_model: openai/gpt-5-mini  # unset by default; cheaper background tasks
```

--------------------------------

### Subagent Example

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/agents.mdx

This example defines a child-only helper agent intended for delegation. It is configured with `mode: subagent` and specific tools for preparing release notes.

```markdown
---
description: Release notes writer
mode: subagent
AllowTools:
  - read
  - search
  - git_diff
  - write
---

You only prepare release notes and changelog updates.

```

--------------------------------

### Example Context Packet Content

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/context.mdx

Illustrates the typical content of a context packet, including repository name, git branch, and changed file information.

```text
name: kodacode
git: detected

branch: docs-refresh
changed_files: 3

total_changed_files: 3
files:
- M README.md
- M site/src/content/docs/features/context.mdx
- ?? site/src/content/docs/features/skills.mdx
```

--------------------------------

### Example of structured instructions for cost savings

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/cost-tracking.mdx

Use structured instructions with headings and bullets for better prompt compaction. Avoid long, repeated prose.

```markdown
## Engineering Priorities

- Correctness first
- Clear ownership boundaries
- Run focused tests before finishing

```

--------------------------------

### Basic Session Configuration

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/sessions.mdx

Configure session persistence, budget warnings, and provider request limits. This setup ensures sessions can be resumed and provides warnings before exceeding a defined budget.

```yaml
sessions:
  budget: 5           # default: 0 (no limit)
  budget_warn: 0.8    # default: 0 (no warning)
  max_provider_requests_per_turn: 32  # default: 32
```

--------------------------------

### Enable Deterministic Context Packet Sections

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/context.mdx

Configure which sections of the context packet are enabled. This example enables repository, git, and git_dirty_summary sections.

```yaml
context_packet:
  enabled_sections:
    - repo
    - git
    - git_dirty_summary
```

--------------------------------

### OpenAI-Compatible Provider Setup

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/providers.mdx

Configures OpenAI-compatible providers by specifying their `id` and `base_url`. Local providers like Ollama may use an empty API key if authentication is not required.

```yaml
version: 1

providers:
  - id: openrouter
    base_url: https://openrouter.ai/api/v1
  - id: ollama
    base_url: http://localhost:11434/v1

model:
  primary: openrouter/openai/gpt-5
```

--------------------------------

### Example Prompt for Engineer Agent

Source: https://github.com/sageil/kodacode/blob/main/README.md

A prompt for the 'engineer' agent to inspect the app structure, propose a plan, and await approval before making changes. This is suitable for broad or risky tasks.

```text
Before editing, inspect the app structure, propose a short implementation plan,
and wait for approval before making code changes.
```

--------------------------------

### Global Skill Mention

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/skills.mdx

Example of using a global skill named 'perf-debug' to investigate performance regressions in dashboard queries.

```text
$perf-debug investigate why the dashboard query regressed after this branch

```

--------------------------------

### Example Prompt for Calculator

Source: https://github.com/sageil/kodacode/blob/main/README.md

A detailed prompt for building a calculator application. It specifies inputs, outputs, calculation logic, validation, testing requirements, and constraints.

```text
Build a calculator that estimates monthly payment, total interest, and affordability range.

Acceptance criteria:

- Inputs: home price, down payment, interest rate, amortization years, property tax, insurance, condo fees, gross monthly income, monthly debts.
- Outputs: loan amount, estimated monthly principal + interest, total monthly housing cost, debt-to-income ratio, and affordability status.
- Use standard fixed-rate mortgage amortization math.
- Validate invalid inputs clearly.
- Add focused tests for payment calculation, DTI calculation, and edge cases.
- Do not use fake values or hardcoded backend state.
- Run the relevant test suite before finishing.
```

--------------------------------

### Run KodaCode in the Terminal

Source: https://github.com/sageil/kodacode/blob/main/README.md

Start KodaCode in your current repository to begin working. This command launches the terminal user interface.

```bash
kodacode
```

--------------------------------

### Configure MCP Server in config.yaml

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/mcp.mdx

Define an MCP server named 'docs' using stdio transport, specifying the command and arguments to start the Node.js server. Environment variables can also be passed.

```yaml
version: 1

mcp:
  servers:
    - name: docs
      type: stdio
      command: node
      args:
        - /Users/me/tools/company-docs-mcp/dist/server.js
      env:
        DOCS_TOKEN: "replace-with-your-token"
```

--------------------------------

### Specifying a Skill for the First Turn

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/getting-started/quick-start.mdx

Mention a specific skill using the --skill flag to guide Kodacode's response for the initial prompt.

```bash
kodacode --skill migration "update the schema"
```

--------------------------------

### Configure Enabled MCP Server

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/mcp.mdx

Example of configuring an MCP server with 'stdio' type and enabling it. The 'enabled' flag defaults to true and can be set to false to disable a server without removing it from the configuration.

```yaml
mcp:
  servers:
    - name: local-api
      type: stdio
      command: npx
      args:
        - "-y"
        - "@acme/local-api-mcp"
      enabled: true
```

--------------------------------

### Basic KodaCode Configuration

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/reference/configuration.mdx

A starting point for a single user with one primary model. It sets up default providers, specifies a primary and utility model, configures session budgets and response style, and defines execution and permission settings for various actions. It also sets the TUI theme.

```yaml
version: 1

providers:
  - id: openai
  - id: anthropic

model:
  primary: openai/gpt-5

utility_model: openai/gpt-5-mini

sessions:
  budget: 5                 # default: 0 (no limit)
  budget_warn: 0.8          # default: 0 (no warning)
  response_style: terse     # default: terse

execution:
  permission_mode: auto     # default: auto
  network: disabled         # default: disabled

permissions:
  external_directory:
    "*": ask
    "/Users/you/src/personal/**": allow
  bash:
    "*": ask
    "git status*": allow
  web_fetch:
    "*": ask
    "https://docs.go101.org/**": allow
  network_target:
    "*": ask
    "api.github.com": allow

tui:
  theme: ayu-dark
  # layout: shell    # default; use classic for the persistent inspector
  # shell_tool_calls: true
  # display_turns: 6

```

--------------------------------

### Install via Homebrew

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/getting-started/installation.mdx

Install KodaCode using Homebrew on macOS. This method requires Homebrew to be installed on your system.

```bash
brew tap sageil/tap
brew install --cask kodacode
```

--------------------------------

### Build and Verify KodaCode

Source: https://github.com/sageil/kodacode/blob/main/CONTRIBUTING.md

Build the project and run the KodaCode binary to verify your changes locally. This step is crucial after making modifications.

```bash
task build
./bin/kodacode
```

--------------------------------

### Configure MCP Server with Tool Hints

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/mcp.mdx

Add 'tool_hints' to an MCP server configuration to provide a summary, guidance, and triggers for a specific tool ('search' in this case). This helps the model choose the tool more effectively.

```yaml
mcp:
  servers:
    - name: docs
      type: stdio
      command: node
      args: [/Users/me/tools/company-docs-mcp/dist/server.js]
      tool_hints:
        search:
          summary: Search the internal product documentation index.
          guidance: Use before answering questions about billing, plans, or support procedures.
          triggers:
            - billing docs
            - support runbook
          file_exts:
            - md
            - mdx
```

--------------------------------

### Skill Discovery with Tools

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/skills.mdx

Illustrates how an agent can discover and use a skill for accessibility review when the exact skill name is unknown, relying on KodaCode's discovery mechanisms.

```text
Find the right skill for accessibility review, then audit the changed React components.

```

--------------------------------

### Hybrid Search Scope Limit Notice

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/search.mdx

Example of a notice displayed when the hybrid search scope is too large and falls back to lexical search.

```text
notice: semantic search scope is too large; narrow path or glob
```

--------------------------------

### Mentioning a Skill

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/skills.mdx

Demonstrates how to invoke a skill named 'migration' with a specific task description using the '$' mention syntax.

```text
$migration add a nullable billing_status column and update the tests

```

--------------------------------

### CLI Skill Invocation

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/skills.mdx

Shows how to use a skill named 'migration' directly from the command line using the 'kodacode --skill' command.

```bash
kodacode --skill migration "add a nullable billing_status column and update the tests"

```

--------------------------------

### Stopping Option Parsing

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/getting-started/quick-start.mdx

Use '--' to stop option parsing and treat subsequent arguments literally, especially useful if your prompt starts with dashes.

```bash
kodacode -- --literal-prompt-starts-with-dashes
```

--------------------------------

### Complete Web Search Configuration with Multiple Providers

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/web-search.mdx

This configuration enables both Exa and Parallel providers and sets Exa as the default. It shows optional base_url and timeout_ms settings.

```yaml
# ~/.config/kodacode/config.yaml
web_search:
  default_provider: exa
  providers:
    exa:
      kind: exa
      base_url: https://api.exa.ai        # optional; shown for clarity
      timeout_ms: 15000                   # optional; default is 15000
    parallel:
      kind: parallel
      base_url: https://api.parallel.ai   # optional; shown for clarity
      timeout_ms: 15000                   # optional; default is 15000
```

--------------------------------

### Basic Provider Configuration

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/providers.mdx

Defines available providers and sets the primary and utility models. Ensure the provider IDs here match those in `auth.yaml`.

```yaml
version: 1

providers:
  - id: openai
  - id: anthropic

model:
  primary: openai/gpt-5

utility_model: openai/gpt-5-mini
```

--------------------------------

### Enable OpenAI Reasoning Replay

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/features/cost-tracking.mdx

Configure OpenAI providers to use stateless requests with encrypted reasoning replay enabled for stateful tool-loop continuation.

```yaml
providers:
  - id: openai
    responses_store: false
    encrypted_reasoning_replay: true
```

--------------------------------

### Workflow Settings Example

Source: https://github.com/sageil/kodacode/blob/main/site/src/content/docs/reference/configuration.mdx

Configure the review mode and the primary model for review passes in Kodacode workflows. The 'review_mode' can be set to 'off', 'manual', or 'auto'. 'review_model' specifies an alternative model for review turns.

```yaml
workflow:
  review_mode: manual       # off | manual | auto; default: manual
  review_model:
    primary: openai/gpt-5-mini
```

--------------------------------

### Run Tests

Source: https://github.com/sageil/kodacode/blob/main/CONTRIBUTING.md

Execute the test suite using the Task build tool to ensure code quality and functionality.

```bash
task test
```