Agents

Agents are purpose-built AI assistants you can tune for particular tasks and workflows. They let you build focused tools with their own prompts, models, and tool access.

Tip

The plan agent is great for analyzing code and reviewing suggestions without touching any files.

Switch agents mid-session, or summon one directly with an @ mention.

---

Types

Kodine has two kinds of agents: primary agents and subagents.

---

Primary agents

Primary agents are the assistants you talk to directly. Cycle through them with the Tab key or whatever keybind you’ve set for switch_agent. They own your main conversation. Their tool access comes from permissions — Build, for instance, has every tool enabled, whereas Plan is locked down.

Tip

Press Tab during a session to flip between primary agents.

Kodine ships with two primary agents out of the box: Build and Plan. Both are covered below.

---

Subagents

Subagents are focused assistants that primary agents can delegate specific tasks to. You can also call them yourself by @ mentioning them in a message.

Kodine ships with three subagents out of the box: General, Explore, and Scout. These are covered below.

---

Built-in

Out of the box, Kodine includes two primary agents and three subagents.

---

Use build

Mode: primary

Build is the default primary agent, with every tool enabled. It’s the everyday agent for development work that needs unrestricted file operations and system commands.

---

Use plan

Mode: primary

Plan is a locked-down agent built for planning and analysis. A permission system keeps you in control and guards against accidental changes. Out of the box, everything below is set to ask:

• file edits: All writes, patches, and edits
• bash: All bash commands

Reach for this agent when you’d like the LLM to read code, propose changes, or draft plans — without it actually modifying your codebase.

---

Use general

Mode: subagent

General is an all-purpose subagent for digging into complex questions and carrying out multi-step work. It has full tool access (except todo), so file changes are on the table. Handy for running several units of work in parallel.

---

Use explore

Mode: subagent

Explore is a quick, read-only subagent for poking around codebases. It can’t change files. Use it to locate files by pattern, search code for keywords, or get fast answers about the codebase.

---

Use scout

Mode: subagent

Scout is a read-only subagent for researching external docs and dependencies. It can clone a dependency repository into Kodine’s managed cache, read library source, or compare local code against upstream implementations — all without touching your workspace.

---

Use compaction

Mode: primary

A hidden system agent that compresses long context into a compact summary. It kicks in automatically when needed and can’t be selected in the UI.

---

Use title

Mode: primary

A hidden system agent that writes short titles for sessions. It runs on its own and can’t be selected in the UI.

---

Use summary

Mode: primary

A hidden system agent that produces session summaries. It runs on its own and can’t be selected in the UI.

---

Usage

1. Cycle primary agents with the Tab key during a session, or use your configured switch_agent keybind.

2. Subagents can be invoked:

   • Automatically, when a primary agent delegates specialized work based on their descriptions.

   • Manually, by @ mentioning the subagent in a message. For example.

     @general help me search for this function

3. Moving between sessions: subagents spawn child sessions. Press session_child_first (default: <Leader>+Down) in the parent to step into the first child session.

4. Inside a child session, use:

   • session_child_cycle (default: Right) to jump to the next child session
   • session_child_cycle_reverse (default: Left) to jump to the previous child session
   • session_parent (default: Up) to head back to the parent session

   That’s how you hop between the main conversation and focused subagent work.

---

Configure

Both the built-in agents and your own custom ones can be adjusted through configuration. There are two ways to configure agents:

---

JSON

Define agents in the kodine.json config file:

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "kodine/kodine-large",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "kodine/kodine-swift",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "kodine/kodine-large",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

---

Markdown

Agents can also be written as markdown files, stored in:

• Global: ~/.config/kodine/agents/
• Per-project: .kodine/agents/

~/.config/kodine/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: kodine/kodine-large
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

The agent takes its name from the markdown filename — review.md registers a review agent.

---

Options

Here is what each configuration option does.

---

Description

description is a short summary of the agent’s job and when to reach for it.

kodine.json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

This config option is required.

---

Temperature

The temperature config tunes how random or creative the LLM’s output gets.

Low values keep responses focused and deterministic; high values make them more creative and varied.

kodine.json

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Typical temperature values fall between 0.0 and 1.0:

• 0.0-0.2: Highly focused, deterministic output — a good fit for code analysis and planning
• 0.3-0.5: A balance of focus and creativity — good for everyday development
• 0.6-1.0: Looser, more varied output — handy for brainstorming and exploration

kodine.json

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

When temperature isn’t set, Kodine falls back to model-specific defaults — usually 0 for most models and 0.55 for a few model families.

---

Max steps

steps caps how many agentic iterations an agent may run before it must reply with plain text. It’s a lever for cost-conscious users who want a hard limit on agentic actions.

Left unset, the agent keeps iterating until the model stops on its own or the user interrupts the session.

kodine.json

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

On hitting the limit, the agent gets a special system prompt telling it to wrap up with a summary of what it did and which tasks remain.

Caution

maxSteps is a deprecated legacy field. Use steps going forward.

---

Disable

Setting this to true turns the agent off.

kodine.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

---

Prompt

Point prompt at a custom system prompt file for the agent. That file should hold instructions tailored to what the agent is for.

kodine.json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

The path resolves relative to the config file, which means it works identically in the global Kodine config and in a project’s config.

---

Model

The model config swaps in a different model for the agent. This helps when different tasks favor different models — say, a quick model for planning and a stronger one for implementation.

Tip

Without an explicit model, primary agents inherit the globally configured model, while subagents inherit the model of whichever primary agent invoked them.

kodine.json

{
  "agent": {
    "plan": {
      "model": "kodine/kodine-swift"
    }
  }
}

Model IDs in a Kodine config are written as provider/model-id. With Kodine Aura, for instance, Kodine Large becomes kodine/kodine-large.

---

Tools (deprecated)

tools is deprecated. New configs should prefer the agent’s permission field, which is kept up to date and offers finer control.

It controls which tools the agent may use — set a tool to true or false to enable or disable it. Inside an agent’s tools config, true behaves like the {"*": "allow"} permission and false like {"*": "deny"}.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Note

An agent’s own config wins over the global config.

Legacy tools entries also accept wildcards, letting you toggle groups of tools together — for instance, switching off every tool from one MCP server:

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Learn more about tools.

---

Permissions

Permissions decide which actions an agent may perform. Every permission key takes one of:

• "ask" — Request approval before the tool runs
• "allow" — Run everything without asking
• "deny" — Turn the tool off

These are the permission keys:

Key	Tools it gates
read	read
edit	write, edit, apply_patch
glob	glob
grep	grep
list	list
bash	bash
task	task
external_directory	Any tool that reads or writes files outside the project worktree
todowrite	todowrite, todoread
webfetch	webfetch
websearch	websearch
lsp	lsp
skill	skill
question	question
doom_loop	Recovery prompts when an agent appears stuck

For read, edit, glob, grep, list, bash, task, external_directory, lsp, and skill, you can give either the shorthand action ("allow" | "ask" | "deny") or an object mapping glob/pattern → action when you need finer control. The other keys only take the shorthand action.

Note

Because permission keys match as wildcard patterns against the underlying tool name, one syntax covers built-ins, custom tools, and MCP tools alike — "mymcp_*": "deny" blocks an entire MCP server’s tools, while "mymcp_search": "ask" singles out just one.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "permission": {
    "edit": "deny"
  }
}

Permissions can be overridden per agent.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Markdown agents can carry permissions too.

~/.config/kodine/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

Individual bash commands can have their own permissions.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Glob patterns are supported here.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

And the * wildcard covers every command at once. Since the last matching rule wins, list the * wildcard first, with specific rules after it.

kodine.json

{
  "$schema": "https://kodine.net/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Learn more about permissions.

---

Mode

The mode config sets the agent’s mode, which decides how the agent may be used.

kodine.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Valid values for mode are primary, subagent, and all. When omitted, mode defaults to all.

---

Hidden

hidden: true keeps a subagent out of the @ autocomplete menu. It’s meant for internal subagents that only other agents should trigger programmatically via the Task tool.

kodine.json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Visibility in the autocomplete menu is the only thing this changes. As long as permissions allow it, hidden agents remain callable by the model through the Task tool.

Note

Only relevant for agents with mode: subagent.

---

Task permissions

permission.task decides which subagents an agent may call through the Task tool, using glob patterns for flexible matching.

kodine.json

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

A deny here removes the subagent from the Task tool’s description altogether, so the model never even tries to call it.

Tip

Rules apply in order, with the last matching rule winning. Above, orchestrator-planner hits both * (deny) and orchestrator-* (allow); because orchestrator-* is listed after *, the outcome is allow.

Tip

The @ autocomplete menu always lets users call any subagent directly, regardless of what task permissions would deny.

---

Color

The color option changes how the agent looks in the UI.

Pass a valid hex color (e.g., #FF5733) or one of the theme colors: primary, secondary, accent, success, warning, error, info.

kodine.json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

---

Top P

top_p adjusts response diversity — an alternative knob to temperature for randomness.

kodine.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Accepted values run from 0.0 to 1.0: lower means more focused, higher means more diverse.

---

Additional

Any extra options you put in an agent’s config are passed straight through to the provider as model options, unlocking provider-specific features and parameters.

Reasoning-capable models, for instance, let you dial the reasoning effort up or down:

kodine.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "kodine/kodine-max",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Which additional options exist depends on the model and provider — check your provider’s docs for the parameters it accepts.

Tip

kodine models prints every model available to you.

---

Create agents

New agents can be scaffolded with:

kodine agent create

The interactive flow will:

1. Ask whether the agent should be saved globally or for the current project.
2. Ask what the agent is supposed to do.
3. Produce a fitting system prompt and identifier.
4. Let you pick which permissions the agent gets (anything left unselected is denied).
5. Write out a markdown file holding the agent’s configuration.

---

Use cases

A few typical ways to put different agents to work.

• Build agent: Everyday development with every tool switched on
• Plan agent: Analysis and planning that leaves the codebase untouched
• Review agent: Read-only code review, plus documentation tools
• Debug agent: Investigation-focused, with bash and read tools on
• Docs agent: Writing documentation with file operations but no system commands

---

Examples

A handful of example agents you might find handy.

Tip

Got an agent worth sharing? Submit a PR.

---

Documentation agent

~/.config/kodine/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

---

Security auditor

~/.config/kodine/agents/security-auditor.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues