Agent kinds
Built-in agent personas spawned via /agent <kind> <prompt>: the five kinds ship as markdown in the kcode-essentials content bundle (materialized to ~/.kcode/plugins-builtin/ at boot).
Full notes from the app
Each kind comes with its own system prompt and permission posture, and may list the tools it is offered. The kind file's body is that prompt: however the kind is started (/agent, the agent's spawn tools, the advisor tool or a plugin) its turns read the body after the session's own system prompt, as an ## Agent role section. The tool list holds at the call too: a call to a tool the kind doesn't list is refused unrun, whatever mode the session is in. A kind with no list (general, planner, researcher and security-reviewer) is offered every tool the session has, or, in plan mode, every tool Plan mode allows. A subagent is never offered the tools that act on the session itself (run_command, set_timer, cancel_timer, set_activity, fork_session and spawn_worktree_session) whatever its kind lists, and a call it makes to one is refused unrun. A kind with permission_mode: plan (the planner, security-reviewer and advisor) is held to what Plan mode allows whatever mode the session is in: it may call only the tools that read, the web and browser tools, session_manager, its own bookkeeping and the shell tools, and a shell command it runs goes ahead only when the command only reads. plan (in any case) is the one mode a kind takes, since a kind can only narrow the session's permissions: any other value, such as accept-edits, is ignored and the kind runs under the session's mode, kcode plugins validate fails on it and /doctor warns (agent.permission-mode). A file in ~/.kcode/agents/ named like a built-in kind replaces it; a project's or a plugin's does not, and /doctor names a project file a built-in kind shadows (agent.shadowed). User-authored kinds in ~/.kcode/agents/*.md (or <project>/.kcode/agents/*.md) additionally accept optional model (a full model id like claude-opus-4-8, a display label like Claude Opus 4.8, or Claude Code's opus, sonnet or haiku for the newest Claude model of that family, resolved to an id when the kind is spawned; inherit is the session's) and effort (minimal/low/medium/high) frontmatter to pin the model + reasoning effort per kind; omit either to inherit the session's model / the default effort. Plugin bundles can ship kinds too (<plugin>/agents/*.md, same frontmatter): they load last, so a user, built-in or project kind of the same name wins, and a plugin blocklisted in <project>/.kcode/policy.toml contributes none.
6 entries · kcode 0.6.5097
| Kind | Tools | Permission | What it does |
|---|---|---|---|
| general | Default | General-purpose coding agent with every tool the session has: it reads, edits, runs commands and checks its work. The default kind. | |
| planner | Plan | Read-only planning agent. Reads the code, runs shell commands that only read, and writes a plan (goal, findings, steps, tests, risks) without carrying it out. | |
| researcher | Default | Investigator. Answers a question about the code or the web with evidence for each claim (path:line, a command's output or a URL) keeping what it saw apart from what it infers. It runs under the session's mode, so it can run a short script to check a claim; its prompt, not plan mode, keeps it from changing the project. | |
| security-reviewer | Plan | Reviews code changes for security issues without modifying anything: the diff, branch, commit or files it is given, else the uncommitted changes. Runs shell commands that only read, such as git diff HEAD, and reports each finding with its severity, place and fix. | |
| advisor | fs_read fs_glob grep sem_search lsp bash shell_status shell_wait shell_kill shell_output_head shell_output_tail shell_output_slice shell_output_grep web_fetch web_search view_image read_pdf memory_search memory_list session_search | Plan | A second opinion from a different model. Reads, never writes. The agent's advisor tool runs this kind on the model pinned in subagent.advisor_model. |
| System prompt override | The built-in system prompt is assembled from per-section Markdown files compiled into the binary (libs/context/prompt/*.md: identity, how-to-work, tools, style, rich-output, memory, recall, control-plane). The how-to-work section sets the agent's default way of working: a task list for work of more than one step, a memory search at the start of a task and a memory saved as soon as a later session needs it, a failing regression test before a bug fix, debugging from the whole error and a tested hypothesis, a search with both sem_search and lsp before a change, small changes that follow the project's patterns, the narrowest tests that cover a change, the whole task done with small problems found on the way fixed and named, and a question before an action that is hard to undo; your own and the project's instructions override it. Tool guidance covers the full toolset by workflow, including complementary search methods, scoped verification, delegation and shell lifecycle handling. The control-plane section separates raw Markdown from XML signals and gives parser-tested examples for working, finishing and a blocked goal. Drop a file at <data dir>/prompt/<section>.md (normally ~/.kcode/prompt/) to override that section globally without recompiling. Other sections keep their compiled-in defaults; an empty, absent or unreadable override falls back to its default. The tools section holds a {{coordination}} line and a {{session_actions}} line that kcode fills with the lines for the tools the session is offered: the app's whole set, or the smaller kcode -p set. An override of tools.md may keep those lines to get the same, or write its own. Changes apply when a session runtime is next built, not to an already-running prompt. There is no per-project section override. |