{"owner":"Kuberwastaken","repo":"claurst","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":4849,"categories":["root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["docs/agents.md","AGENTS.md"],"skills":{"docs/agents.md":"# Agents and Multi-Agent Features\n\nClaurst has a named-agent system that lets you select a pre-configured persona with its own tool permissions, model, system prompt, and turn budget. For larger tasks the model can spawn sub-agents with the `Agent` tool, and `/managed-agents` configures a manager-executor split.\n\n---\n\n## Built-in Named Agents\n\nThree agents ship by default. Their definitions can be overridden per-user in `~/.claurst/settings.json`.\n\n### build\n\nFull tool access. Intended for implementing features and fixing bugs.\n\n| Property | Value |\n|---|---|\n| Access | `full` — all tools available |\n| Max turns | Unlimited (uses the global default) |\n| Display color | Cyan |\n\nDefault system prompt prefix:\n\n> You are the build agent. You have full access to read, write, and execute. Focus on implementing the requested changes completely and correctly.\n\n### plan\n\nRead-only analysis. Cannot write files or execute commands. Intended for understanding codebases and planning changes before committing to implementation.\n\n| Property | Value |\n|---|---|\n| Access | `read-only` — file reads, no writes or shell execution |\n| Max turns | 20 |\n| Display color | Yellow |\n\nDefault system prompt prefix:\n\n> You are the plan agent. You can read files and analyze code but cannot write files or execute commands. Focus on understanding the codebase and describing what changes should be made.\n\n### explore\n\nFast search-only exploration. Intended for quickly locating relevant code and answering questions about structure.\n\n| Property | Value |\n|---|---|\n| Access | `search-only` — search tools only |\n| Max turns | 15 |\n| Display color | Green |\n\nDefault system prompt prefix:\n\n> You are the explore agent. You can search and read files. Focus on quickly finding relevant code and answering questions about the codebase.\n\n---\n\n## Selecting an Agent with --agent\n\nPass `--agent <name>` to activate a named agent for a session:\n\n```\nclaurst --agent build \"implement the OAuth2 login flow\"\nclaurst --agent plan \"analyze the database schema and suggest improvements\"\nclaurst --agent explore \"find all usages of the deprecated config API\"\n```\n\nThe `--agent` flag can be combined with `--provider` and `--model`:\n\n```\nclaurst --agent plan --provider openai --model o3 \"review this architecture\"\n```\n\nAn unknown name prints a warning and runs without an agent. In the interactive TUI, pressing `Tab` on an empty prompt (while no response is streaming) toggles between the `build` and `plan` agents.\n\nAccess levels filter the tool list: `read-only` keeps tools whose permission level is read-only or none, plus `AskUserQuestion` (built-in tools only; `Agent` and MCP tools are removed); `search-only` keeps only `Grep`, `Glob`, `Read`, `WebSearch`, and `WebFetch`.\n\n---\n\n## The /agent and /agents Commands\n\nWithin an interactive session, `/agent` lists all available named agents (built-in and custom) and `/agent <name>` shows one agent's details:\n\n```\n/agent\n/agent plan\n```\n\nThe list shows the agent name, description, access level, and max turn limit. Agents with `visible: false` in their definition are hidden from this list. `/agent` does not switch agents; start Claurst with `--agent <name>` (or use `Tab`, above).\n\n`/agents` opens a separate TUI menu that browses and edits Markdown agent files in `~/.claurst/agents/` and `<project>/.claurst/agents/` (front-matter keys `name`, `description`, `model`, `tools`, `memory_scope`). These files are not the `settings.json` definitions below and are not selectable with `--agent`.\n\n---\n\n## Custom Agent Definitions\n\nDefine custom agents in `~/.claurst/settings.json` under the `agents` key. Custom definitions override built-in agents of the same name.\n\n```json\n{\n  \"agents\": {\n    \"review\": {\n      \"description\": \"Senior code reviewer focused on correctness and security\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.3,\n      \"prompt\": \"You are a senior software engineer performing code review. Focus on correctness, security vulnerabilities, performance issues, and maintainability. Be specific about problems and suggest concrete fixes.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"magenta\"\n    },\n    \"test-writer\": {\n      \"description\": \"Writes comprehensive unit and integration tests\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are a test engineer. Write thorough tests covering happy paths, edge cases, and error conditions. Use the project's existing test framework and conventions.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"blue\"\n    },\n    \"docs\": {\n      \"description\": \"Technical documentation writer\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"temperature\": 0.5,\n      \"prompt\": \"You are a technical writer. Write clear, accurate documentation for the code you are given. Use the project's existing documentation style.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 25,\n      \"color\": \"cyan\"\n    }\n  }\n}\n```\n\n### AgentDefinition Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `description` | string | Short description shown in `/agent` |\n| `model` | string | Model override in `provider/model` or bare `model` form. Omit to use the session default. |\n| `temperature` | number | Sampling temperature override (0.0–1.0). Omit to use the model default. |\n| `prompt` | string | System prompt prefix prepended before the main system prompt. |\n| `access` | string | Permission restriction: `\"full\"` (all tools), `\"read-only\"` (no writes/shell), `\"search-only\"` (search tools only). Default: `\"full\"`. |\n| `visible` | bool | Whether to show in `/agent` output. Default: `true`. |\n| `max_turns` | number or null | Maximum agentic turns. Null means unlimited. Overrides the global turn budget. |\n| `color` | string | ANSI terminal color for display: `\"cyan\"`, `\"magenta\"`, `\"green\"`, `\"yellow\"`, `\"blue\"`, etc. |\n\nUse the agent with the `--agent` flag:\n\n```\nclaurst --agent review \"check the authentication module for security issues\"\nclaurst --agent test-writer \"write tests for the payment processor\"\n```\n\n---\n\n## Sub-agents and Task Tools\n\nThe `Agent` tool lets the model spawn a sub-agent with its own prompt, optional tool list, model, turn cap (default 10), `isolation: \"worktree\"`, and `run_in_background`. `SendMessage`, `TeamCreate`, and `TeamDelete` are also in the standard tool set. See [Tools](tools.md) for each tool's parameters.\n\nThe task tools (`TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, `TaskStop`, `TaskOutput`) are part of the standard tool set in every session. `/tasks` (alias `/bashes`) asks the model to list current tasks with `TaskList`.\n\n### Coordinator mode (not wired)\n\n`CLAURST_COORDINATOR_MODE` is defined in `crates/query/src/coordinator.rs`, but nothing in the running agent loop reads it: no coordinator prompt is injected, no tools are withheld from workers, and resumed sessions are not mode-matched. Setting it has no effect. See [Local Models](local-models.md#is-claurst_coordinator_mode1-a-real-thing).\n\n---\n\n## Agent Definitions in settings.json: Complete Example\n\n```json\n{\n  \"provider\": \"anthropic\",\n  \"agents\": {\n    \"build\": {\n      \"description\": \"Full-access implementation agent\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are the build agent. Implement requested changes completely. Prefer targeted, minimal edits over rewrites.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"cyan\"\n    },\n    \"plan\": {\n      \"description\": \"Read-only analysis and planning agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.2,\n      \"prompt\": \"You are the plan agent. Analyse the codebase carefully before producing a detailed, step-by-step implementation plan. Do not write or execute anything.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 20,\n      \"color\": \"yellow\"\n    },\n    \"explore\": {\n      \"description\": \"Fast search-only exploration agent\",\n      \"model\": \"anthropic/claude-haiku-4-5-20251001\",\n      \"prompt\": \"You are the explore agent. Search and read files to answer questions quickly.\",\n      \"access\": \"search-only\",\n      \"visible\": true,\n      \"max_turns\": 15,\n      \"color\": \"green\"\n    },\n    \"security\": {\n      \"description\": \"Security-focused read-only audit agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.1,\n      \"prompt\": \"You are a security auditor. Look for authentication flaws, injection vulnerabilities, insecure dependencies, and data-exposure risks. Report findings with severity levels (critical, high, medium, low) and concrete remediation steps.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 40,\n      \"color\": \"magenta\"\n    },\n    \"architect\": {\n      \"description\": \"System design and architecture advisor\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.4,\n      \"prompt\": \"You are a software architect. Reason carefully about system design trade-offs, scalability, maintainability, and technical debt. Produce clear architectural recommendations with rationale.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"blue\"\n    }\n  }\n}\n```\n\n---\n\n## Managed Agents (Preview)\n\nManaged agents provide a **manager-executor** architecture: you configure separate models, turn budgets, concurrency limits, and budget splits for the manager and for executors. When enabled, the session runs on the manager model and gets orchestration instructions in its system prompt.\n\n### Enabling and configuring\n\n```\n/managed-agents presets                               — list presets\n/managed-agents preset <name>                         — apply a preset\n/managed-agents configure manager-model  anthropic/claude-opus-4-6\n/managed-agents configure executor-model anthropic/claude-sonnet-4-6\n/managed-agents configure concurrent     3\n/managed-agents budget 5.00\n/managed-agents enable\n```\n\nSee [Managed Agents](./advanced.md#managed-agents) in the advanced guide for the full configuration reference.\n","AGENTS.md":"# Development Rules\n\nAgent-facing rules for working on Claurst. Mirrors and extends `src-rust/.claude/CLAUDE.md`; when the two disagree, the rule closer to the code wins.\n\n## Conversational Style\n\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n- When the user asks a question, answer it first before making edits or running implementation commands.\n\n## Code Quality\n\n- Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n- No `.unwrap()` / `.expect()` on fallible operations in production paths — propagate via `Result` or pattern-match. `unwrap` is acceptable in tests and in cases where the invariant is statically obvious and commented.\n- Avoid speculative `.clone()` — borrow first, clone only when ownership is actually needed. Same applies to `.to_string()` on `&str`.\n- No `unsafe` blocks without a `// SAFETY:` comment explaining the invariant.\n- Single-line helper functions with a single call site are forbidden; inline them instead.\n- Don't guess external API shapes. Read the crate source under `~/.cargo/registry/` or check `cargo doc --open`. For Anthropic / OpenAI / Google wire formats, the `crates/api/src/providers/<provider>.rs` files are the authoritative reference inside this repo.\n- **NEVER use type erasure to silence the compiler** — no `Box<dyn Any>`, no `serde_json::Value` shoved through a typed boundary just because the right type is annoying to derive. If a type is hard to express, ask the user.\n- NEVER remove or downgrade code to fix compiler errors from outdated dependencies; bump the dependency in `Cargo.toml` or `src-rust/Cargo.toml` workspace deps instead.\n- Always ask before removing functionality or code that appears to be intentional.\n- Do not preserve backward compatibility unless the user explicitly asks for it.\n- Never hardcode keybinding checks inline (e.g. `key == KeyCode::Char('s') && mods.ctrl()`). All keybindings must flow through the configurable keybinding system in `crates/core/src/keybindings.rs` — add a default there.\n- NEVER modify generated files directly. Generated artefacts in this repo:\n  - `src-rust/Cargo.lock` — regenerated by cargo; for version bumps use [`scripts/bump-version.py`](scripts/bump-version.py).\n  - `npm/package.json` `version` field — also stamped by `bump-version.py`.\n\n## Commands\n\nRun from `src-rust/` unless noted.\n\n- After Rust changes (not docs): `cargo check --workspace` — fix every error and warning before committing.\n- Clippy: `cargo clippy --workspace --all-targets -- -D warnings`. Fix lints; do not `#[allow(...)]` without justification.\n- Format: `cargo fmt --all`. Run before committing.\n- Tests: `cargo test --workspace` for everything, `cargo test --package claurst-<crate>` for a single crate, `cargo test --package claurst-<crate> -- <pattern>` for a specific test.\n- Avoid running `cargo build --release` or `cargo run --release` unless you specifically need optimised output — debug builds and `cargo check` are 10× faster.\n- If you create or modify a test, run it and iterate until it passes.\n- For TUI changes: validate by hand with `cargo run -- \"test prompt\"` (interactive) or `cargo run -- --print \"test\"` (headless). The `--print` mode is faster for verifying non-TUI logic.\n- Don't run blocking interactive commands you can't exit — the agent will hang. If you must, capture output with `--print` mode or pipe into `head`.\n\n### Testing the TUI in a controlled terminal\n\nThe ratatui frontend is sensitive to terminal size and key encoding. For repeatable manual tests use tmux:\n\n```bash\n# Build a debug binary once\ncargo build\n\n# 80×24 session\ntmux new-session -d -s claurst-test -x 80 -y 24\ntmux send-keys -t claurst-test \"./target/debug/claurst\" Enter\n\n# Give it time to redraw, then capture\nsleep 2 && tmux capture-pane -t claurst-test -p\n\n# Drive input\ntmux send-keys -t claurst-test \"your prompt here\" Enter\ntmux send-keys -t claurst-test Escape\ntmux send-keys -t claurst-test C-o   # ctrl+o\n\n# Cleanup\ntmux kill-session -t claurst-test\n```\n\nOn Windows hosts, prefer `cargo run -- --print \"...\"` against the headless path. The Windows console has known quirks with the kitty keyboard protocol — see `crates/tui` for the push/pop workaround.\n\n## Issues & PR Comments\n\nWhen posting issue/PR comments:\n\n- Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`.\n- Never pass multi-line markdown directly via `--body` in shell commands.\n- Preview the exact comment text before posting.\n- Post exactly one final comment unless the user explicitly asks for multiple comments.\n- If a comment is malformed, delete it immediately, then post one corrected comment.\n- Keep comments concise, technical, and in the user's tone.\n\nWhen creating issues, add labels that map to the relevant crate(s) — for example `crate:tui`, `crate:api`, `crate:tools`, `crate:mcp`, `crate:acp`. If an issue spans multiple crates, add all relevant labels.\n\nWhen closing issues via commit, include `fixes #<number>` or `closes #<number>` in the commit message — GitHub closes the issue automatically on merge to main.\n\n### 1. Provider identifier (`crates/core/src/provider_id.rs`)\n\nAdd a well-known constant on `ProviderId`, e.g. `pub const FOO: &'static str = \"foo\";`. Use the canonical name the provider publishes for its API.\n\n### 2. Provider implementation (`crates/api/src/providers/`)\n\n- OpenAI-compatible: add an entry to `openai_compat_providers.rs`. This is one line + an optional base-URL helper.\n- Custom wire format: create `crates/api/src/providers/<name>.rs` exposing a struct that implements `LlmProvider` (see `provider.rs`). Mirror the structure of `anthropic.rs` or `google.rs` — request shaping, response parsing, streaming SSE handling, tool conversion.\n- Add `pub mod <name>; pub use <name>::<Name>Provider;` to `providers/mod.rs`.\n\n### 3. Register the provider (`crates/api/src/registry.rs`)\n\nImport the new provider and add it to the registry construction. The registry hands back `Arc<dyn LlmProvider>` by id.\n\n### 4. Model registry (`crates/api/src/model_registry.rs`)\n\nAdd the canonical model IDs and capability metadata (context window, supports thinking, supports vision, etc.).\n\n### 5. Auth & env detection (`crates/core/src/auth_store.rs`, related)\n\nIf the provider uses an env var (e.g. `FOO_API_KEY`), wire it into the auth-store probe. For OAuth-style providers, see `codex_oauth.rs` and `device_code.rs` for the existing patterns.\n\n### 6. Tests\n\n- Add a smoke test in `crates/api/tests/` that exercises request shaping and response parsing against a mocked HTTP body. No live API calls — use the fixture pattern that the existing provider tests follow.\n- If the provider supports tool calls, add a tool-call round-trip fixture.\n- For OpenAI-compatible providers, the shared test in `crates/api/tests/openai_compat.rs` covers most paths; usually just adding a row to its provider matrix is enough.\n\n### 7. Documentation\n\n- `README.md`: add the provider to the \"Supported Providers\" list if it's user-visible.\n- `docs/providers.md`: setup instructions, env var, and `settings.json` shape.\n\n## Releasing\n\nClaurst uses a **single workspace version** stamped across every surface (Cargo workspace, Cargo.lock entries for the 12 `claurst*` crates, `npm/package.json`, README badge, docs, ACP registry template). Versioning is forward-only — the release workflow refuses to ship a tag less than or equal to the highest existing tag.\n\n## **CRITICAL** Git Rules for Parallel Agents\n\nThis repo runs parallel agents in worktrees under `.claude/worktrees/`. Multiple agents may be modifying different files in the same checkout simultaneously. You MUST follow these rules:\n\n### Committing\n\n- **ONLY commit files YOU changed in THIS session.** Never commit unless the user has explicitly asked you to commit (see `src-rust/.claude/CLAUDE.md` — the rule is \"NEVER EVER commit\").\n- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR.\n- NEVER use `git add -A` or `git add .` — these sweep up changes from other agents.\n- ALWAYS use `git add <specific-file-paths>` listing only files you modified.\n- Before committing, run `git status` and verify you are only staging YOUR files.\n- Track which files you created/modified/deleted during the session.\n- Cargo.lock counts as yours if and only if your edits to `Cargo.toml` caused it to change.\n\n### Forbidden Git Operations\n\nThese can destroy other agents' work:\n\n- `git reset --hard` — destroys uncommitted changes\n- `git checkout .` / `git restore .` — destroys uncommitted changes\n- `git clean -fd` — deletes untracked files\n- `git stash` — stashes ALL changes including other agents' work\n- `git add -A` / `git add .` — stages other agents' uncommitted work\n- `git commit --no-verify` — bypasses required checks; never allowed\n- Force-push to `main` — never allowed; the patch-release workflow is the only thing that may force-move tags, and it does so via the workflow runner, not from your shell\n\n### Safe Workflow\n\n```bash\n# 1. Check status\ngit status\n\n# 2. Stage only your files\ngit add src-rust/crates/api/src/providers/foo.rs\ngit add docs/providers.md\n\n# 3. Commit (only when the user has asked)\ngit commit -m \"feat(api): add foo provider\"\n\n# 4. Push (pull --rebase if needed, but NEVER reset/checkout)\ngit pull --rebase && git push\n```\n\n### If Rebase Conflicts Occur\n\n- Resolve conflicts in YOUR files only.\n- If a conflict touches a file you didn't modify, abort the rebase and ask the user.\n- NEVER force-push.\n\n### User Override\n\nIf the user's instructions conflict with the rules above, ask for confirmation that they want to override the rules. Only then execute their instructions.\n"},"files":{"docs/agents.md":"# Agents and Multi-Agent Features\n\nClaurst has a named-agent system that lets you select a pre-configured persona with its own tool permissions, model, system prompt, and turn budget. For larger tasks the model can spawn sub-agents with the `Agent` tool, and `/managed-agents` configures a manager-executor split.\n\n---\n\n## Built-in Named Agents\n\nThree agents ship by default. Their definitions can be overridden per-user in `~/.claurst/settings.json`.\n\n### build\n\nFull tool access. Intended for implementing features and fixing bugs.\n\n| Property | Value |\n|---|---|\n| Access | `full` — all tools available |\n| Max turns | Unlimited (uses the global default) |\n| Display color | Cyan |\n\nDefault system prompt prefix:\n\n> You are the build agent. You have full access to read, write, and execute. Focus on implementing the requested changes completely and correctly.\n\n### plan\n\nRead-only analysis. Cannot write files or execute commands. Intended for understanding codebases and planning changes before committing to implementation.\n\n| Property | Value |\n|---|---|\n| Access | `read-only` — file reads, no writes or shell execution |\n| Max turns | 20 |\n| Display color | Yellow |\n\nDefault system prompt prefix:\n\n> You are the plan agent. You can read files and analyze code but cannot write files or execute commands. Focus on understanding the codebase and describing what changes should be made.\n\n### explore\n\nFast search-only exploration. Intended for quickly locating relevant code and answering questions about structure.\n\n| Property | Value |\n|---|---|\n| Access | `search-only` — search tools only |\n| Max turns | 15 |\n| Display color | Green |\n\nDefault system prompt prefix:\n\n> You are the explore agent. You can search and read files. Focus on quickly finding relevant code and answering questions about the codebase.\n\n---\n\n## Selecting an Agent with --agent\n\nPass `--agent <name>` to activate a named agent for a session:\n\n```\nclaurst --agent build \"implement the OAuth2 login flow\"\nclaurst --agent plan \"analyze the database schema and suggest improvements\"\nclaurst --agent explore \"find all usages of the deprecated config API\"\n```\n\nThe `--agent` flag can be combined with `--provider` and `--model`:\n\n```\nclaurst --agent plan --provider openai --model o3 \"review this architecture\"\n```\n\nAn unknown name prints a warning and runs without an agent. In the interactive TUI, pressing `Tab` on an empty prompt (while no response is streaming) toggles between the `build` and `plan` agents.\n\nAccess levels filter the tool list: `read-only` keeps tools whose permission level is read-only or none, plus `AskUserQuestion` (built-in tools only; `Agent` and MCP tools are removed); `search-only` keeps only `Grep`, `Glob`, `Read`, `WebSearch`, and `WebFetch`.\n\n---\n\n## The /agent and /agents Commands\n\nWithin an interactive session, `/agent` lists all available named agents (built-in and custom) and `/agent <name>` shows one agent's details:\n\n```\n/agent\n/agent plan\n```\n\nThe list shows the agent name, description, access level, and max turn limit. Agents with `visible: false` in their definition are hidden from this list. `/agent` does not switch agents; start Claurst with `--agent <name>` (or use `Tab`, above).\n\n`/agents` opens a separate TUI menu that browses and edits Markdown agent files in `~/.claurst/agents/` and `<project>/.claurst/agents/` (front-matter keys `name`, `description`, `model`, `tools`, `memory_scope`). These files are not the `settings.json` definitions below and are not selectable with `--agent`.\n\n---\n\n## Custom Agent Definitions\n\nDefine custom agents in `~/.claurst/settings.json` under the `agents` key. Custom definitions override built-in agents of the same name.\n\n```json\n{\n  \"agents\": {\n    \"review\": {\n      \"description\": \"Senior code reviewer focused on correctness and security\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.3,\n      \"prompt\": \"You are a senior software engineer performing code review. Focus on correctness, security vulnerabilities, performance issues, and maintainability. Be specific about problems and suggest concrete fixes.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"magenta\"\n    },\n    \"test-writer\": {\n      \"description\": \"Writes comprehensive unit and integration tests\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are a test engineer. Write thorough tests covering happy paths, edge cases, and error conditions. Use the project's existing test framework and conventions.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"blue\"\n    },\n    \"docs\": {\n      \"description\": \"Technical documentation writer\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"temperature\": 0.5,\n      \"prompt\": \"You are a technical writer. Write clear, accurate documentation for the code you are given. Use the project's existing documentation style.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 25,\n      \"color\": \"cyan\"\n    }\n  }\n}\n```\n\n### AgentDefinition Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `description` | string | Short description shown in `/agent` |\n| `model` | string | Model override in `provider/model` or bare `model` form. Omit to use the session default. |\n| `temperature` | number | Sampling temperature override (0.0–1.0). Omit to use the model default. |\n| `prompt` | string | System prompt prefix prepended before the main system prompt. |\n| `access` | string | Permission restriction: `\"full\"` (all tools), `\"read-only\"` (no writes/shell), `\"search-only\"` (search tools only). Default: `\"full\"`. |\n| `visible` | bool | Whether to show in `/agent` output. Default: `true`. |\n| `max_turns` | number or null | Maximum agentic turns. Null means unlimited. Overrides the global turn budget. |\n| `color` | string | ANSI terminal color for display: `\"cyan\"`, `\"magenta\"`, `\"green\"`, `\"yellow\"`, `\"blue\"`, etc. |\n\nUse the agent with the `--agent` flag:\n\n```\nclaurst --agent review \"check the authentication module for security issues\"\nclaurst --agent test-writer \"write tests for the payment processor\"\n```\n\n---\n\n## Sub-agents and Task Tools\n\nThe `Agent` tool lets the model spawn a sub-agent with its own prompt, optional tool list, model, turn cap (default 10), `isolation: \"worktree\"`, and `run_in_background`. `SendMessage`, `TeamCreate`, and `TeamDelete` are also in the standard tool set. See [Tools](tools.md) for each tool's parameters.\n\nThe task tools (`TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, `TaskStop`, `TaskOutput`) are part of the standard tool set in every session. `/tasks` (alias `/bashes`) asks the model to list current tasks with `TaskList`.\n\n### Coordinator mode (not wired)\n\n`CLAURST_COORDINATOR_MODE` is defined in `crates/query/src/coordinator.rs`, but nothing in the running agent loop reads it: no coordinator prompt is injected, no tools are withheld from workers, and resumed sessions are not mode-matched. Setting it has no effect. See [Local Models](local-models.md#is-claurst_coordinator_mode1-a-real-thing).\n\n---\n\n## Agent Definitions in settings.json: Complete Example\n\n```json\n{\n  \"provider\": \"anthropic\",\n  \"agents\": {\n    \"build\": {\n      \"description\": \"Full-access implementation agent\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are the build agent. Implement requested changes completely. Prefer targeted, minimal edits over rewrites.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"cyan\"\n    },\n    \"plan\": {\n      \"description\": \"Read-only analysis and planning agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.2,\n      \"prompt\": \"You are the plan agent. Analyse the codebase carefully before producing a detailed, step-by-step implementation plan. Do not write or execute anything.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 20,\n      \"color\": \"yellow\"\n    },\n    \"explore\": {\n      \"description\": \"Fast search-only exploration agent\",\n      \"model\": \"anthropic/claude-haiku-4-5-20251001\",\n      \"prompt\": \"You are the explore agent. Search and read files to answer questions quickly.\",\n      \"access\": \"search-only\",\n      \"visible\": true,\n      \"max_turns\": 15,\n      \"color\": \"green\"\n    },\n    \"security\": {\n      \"description\": \"Security-focused read-only audit agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.1,\n      \"prompt\": \"You are a security auditor. Look for authentication flaws, injection vulnerabilities, insecure dependencies, and data-exposure risks. Report findings with severity levels (critical, high, medium, low) and concrete remediation steps.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 40,\n      \"color\": \"magenta\"\n    },\n    \"architect\": {\n      \"description\": \"System design and architecture advisor\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.4,\n      \"prompt\": \"You are a software architect. Reason carefully about system design trade-offs, scalability, maintainability, and technical debt. Produce clear architectural recommendations with rationale.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"blue\"\n    }\n  }\n}\n```\n\n---\n\n## Managed Agents (Preview)\n\nManaged agents provide a **manager-executor** architecture: you configure separate models, turn budgets, concurrency limits, and budget splits for the manager and for executors. When enabled, the session runs on the manager model and gets orchestration instructions in its system prompt.\n\n### Enabling and configuring\n\n```\n/managed-agents presets                               — list presets\n/managed-agents preset <name>                         — apply a preset\n/managed-agents configure manager-model  anthropic/claude-opus-4-6\n/managed-agents configure executor-model anthropic/claude-sonnet-4-6\n/managed-agents configure concurrent     3\n/managed-agents budget 5.00\n/managed-agents enable\n```\n\nSee [Managed Agents](./advanced.md#managed-agents) in the advanced guide for the full configuration reference.\n","AGENTS.md":"# Development Rules\n\nAgent-facing rules for working on Claurst. Mirrors and extends `src-rust/.claude/CLAUDE.md`; when the two disagree, the rule closer to the code wins.\n\n## Conversational Style\n\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n- When the user asks a question, answer it first before making edits or running implementation commands.\n\n## Code Quality\n\n- Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n- No `.unwrap()` / `.expect()` on fallible operations in production paths — propagate via `Result` or pattern-match. `unwrap` is acceptable in tests and in cases where the invariant is statically obvious and commented.\n- Avoid speculative `.clone()` — borrow first, clone only when ownership is actually needed. Same applies to `.to_string()` on `&str`.\n- No `unsafe` blocks without a `// SAFETY:` comment explaining the invariant.\n- Single-line helper functions with a single call site are forbidden; inline them instead.\n- Don't guess external API shapes. Read the crate source under `~/.cargo/registry/` or check `cargo doc --open`. For Anthropic / OpenAI / Google wire formats, the `crates/api/src/providers/<provider>.rs` files are the authoritative reference inside this repo.\n- **NEVER use type erasure to silence the compiler** — no `Box<dyn Any>`, no `serde_json::Value` shoved through a typed boundary just because the right type is annoying to derive. If a type is hard to express, ask the user.\n- NEVER remove or downgrade code to fix compiler errors from outdated dependencies; bump the dependency in `Cargo.toml` or `src-rust/Cargo.toml` workspace deps instead.\n- Always ask before removing functionality or code that appears to be intentional.\n- Do not preserve backward compatibility unless the user explicitly asks for it.\n- Never hardcode keybinding checks inline (e.g. `key == KeyCode::Char('s') && mods.ctrl()`). All keybindings must flow through the configurable keybinding system in `crates/core/src/keybindings.rs` — add a default there.\n- NEVER modify generated files directly. Generated artefacts in this repo:\n  - `src-rust/Cargo.lock` — regenerated by cargo; for version bumps use [`scripts/bump-version.py`](scripts/bump-version.py).\n  - `npm/package.json` `version` field — also stamped by `bump-version.py`.\n\n## Commands\n\nRun from `src-rust/` unless noted.\n\n- After Rust changes (not docs): `cargo check --workspace` — fix every error and warning before committing.\n- Clippy: `cargo clippy --workspace --all-targets -- -D warnings`. Fix lints; do not `#[allow(...)]` without justification.\n- Format: `cargo fmt --all`. Run before committing.\n- Tests: `cargo test --workspace` for everything, `cargo test --package claurst-<crate>` for a single crate, `cargo test --package claurst-<crate> -- <pattern>` for a specific test.\n- Avoid running `cargo build --release` or `cargo run --release` unless you specifically need optimised output — debug builds and `cargo check` are 10× faster.\n- If you create or modify a test, run it and iterate until it passes.\n- For TUI changes: validate by hand with `cargo run -- \"test prompt\"` (interactive) or `cargo run -- --print \"test\"` (headless). The `--print` mode is faster for verifying non-TUI logic.\n- Don't run blocking interactive commands you can't exit — the agent will hang. If you must, capture output with `--print` mode or pipe into `head`.\n\n### Testing the TUI in a controlled terminal\n\nThe ratatui frontend is sensitive to terminal size and key encoding. For repeatable manual tests use tmux:\n\n```bash\n# Build a debug binary once\ncargo build\n\n# 80×24 session\ntmux new-session -d -s claurst-test -x 80 -y 24\ntmux send-keys -t claurst-test \"./target/debug/claurst\" Enter\n\n# Give it time to redraw, then capture\nsleep 2 && tmux capture-pane -t claurst-test -p\n\n# Drive input\ntmux send-keys -t claurst-test \"your prompt here\" Enter\ntmux send-keys -t claurst-test Escape\ntmux send-keys -t claurst-test C-o   # ctrl+o\n\n# Cleanup\ntmux kill-session -t claurst-test\n```\n\nOn Windows hosts, prefer `cargo run -- --print \"...\"` against the headless path. The Windows console has known quirks with the kitty keyboard protocol — see `crates/tui` for the push/pop workaround.\n\n## Issues & PR Comments\n\nWhen posting issue/PR comments:\n\n- Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`.\n- Never pass multi-line markdown directly via `--body` in shell commands.\n- Preview the exact comment text before posting.\n- Post exactly one final comment unless the user explicitly asks for multiple comments.\n- If a comment is malformed, delete it immediately, then post one corrected comment.\n- Keep comments concise, technical, and in the user's tone.\n\nWhen creating issues, add labels that map to the relevant crate(s) — for example `crate:tui`, `crate:api`, `crate:tools`, `crate:mcp`, `crate:acp`. If an issue spans multiple crates, add all relevant labels.\n\nWhen closing issues via commit, include `fixes #<number>` or `closes #<number>` in the commit message — GitHub closes the issue automatically on merge to main.\n\n### 1. Provider identifier (`crates/core/src/provider_id.rs`)\n\nAdd a well-known constant on `ProviderId`, e.g. `pub const FOO: &'static str = \"foo\";`. Use the canonical name the provider publishes for its API.\n\n### 2. Provider implementation (`crates/api/src/providers/`)\n\n- OpenAI-compatible: add an entry to `openai_compat_providers.rs`. This is one line + an optional base-URL helper.\n- Custom wire format: create `crates/api/src/providers/<name>.rs` exposing a struct that implements `LlmProvider` (see `provider.rs`). Mirror the structure of `anthropic.rs` or `google.rs` — request shaping, response parsing, streaming SSE handling, tool conversion.\n- Add `pub mod <name>; pub use <name>::<Name>Provider;` to `providers/mod.rs`.\n\n### 3. Register the provider (`crates/api/src/registry.rs`)\n\nImport the new provider and add it to the registry construction. The registry hands back `Arc<dyn LlmProvider>` by id.\n\n### 4. Model registry (`crates/api/src/model_registry.rs`)\n\nAdd the canonical model IDs and capability metadata (context window, supports thinking, supports vision, etc.).\n\n### 5. Auth & env detection (`crates/core/src/auth_store.rs`, related)\n\nIf the provider uses an env var (e.g. `FOO_API_KEY`), wire it into the auth-store probe. For OAuth-style providers, see `codex_oauth.rs` and `device_code.rs` for the existing patterns.\n\n### 6. Tests\n\n- Add a smoke test in `crates/api/tests/` that exercises request shaping and response parsing against a mocked HTTP body. No live API calls — use the fixture pattern that the existing provider tests follow.\n- If the provider supports tool calls, add a tool-call round-trip fixture.\n- For OpenAI-compatible providers, the shared test in `crates/api/tests/openai_compat.rs` covers most paths; usually just adding a row to its provider matrix is enough.\n\n### 7. Documentation\n\n- `README.md`: add the provider to the \"Supported Providers\" list if it's user-visible.\n- `docs/providers.md`: setup instructions, env var, and `settings.json` shape.\n\n## Releasing\n\nClaurst uses a **single workspace version** stamped across every surface (Cargo workspace, Cargo.lock entries for the 12 `claurst*` crates, `npm/package.json`, README badge, docs, ACP registry template). Versioning is forward-only — the release workflow refuses to ship a tag less than or equal to the highest existing tag.\n\n## **CRITICAL** Git Rules for Parallel Agents\n\nThis repo runs parallel agents in worktrees under `.claude/worktrees/`. Multiple agents may be modifying different files in the same checkout simultaneously. You MUST follow these rules:\n\n### Committing\n\n- **ONLY commit files YOU changed in THIS session.** Never commit unless the user has explicitly asked you to commit (see `src-rust/.claude/CLAUDE.md` — the rule is \"NEVER EVER commit\").\n- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR.\n- NEVER use `git add -A` or `git add .` — these sweep up changes from other agents.\n- ALWAYS use `git add <specific-file-paths>` listing only files you modified.\n- Before committing, run `git status` and verify you are only staging YOUR files.\n- Track which files you created/modified/deleted during the session.\n- Cargo.lock counts as yours if and only if your edits to `Cargo.toml` caused it to change.\n\n### Forbidden Git Operations\n\nThese can destroy other agents' work:\n\n- `git reset --hard` — destroys uncommitted changes\n- `git checkout .` / `git restore .` — destroys uncommitted changes\n- `git clean -fd` — deletes untracked files\n- `git stash` — stashes ALL changes including other agents' work\n- `git add -A` / `git add .` — stages other agents' uncommitted work\n- `git commit --no-verify` — bypasses required checks; never allowed\n- Force-push to `main` — never allowed; the patch-release workflow is the only thing that may force-move tags, and it does so via the workflow runner, not from your shell\n\n### Safe Workflow\n\n```bash\n# 1. Check status\ngit status\n\n# 2. Stage only your files\ngit add src-rust/crates/api/src/providers/foo.rs\ngit add docs/providers.md\n\n# 3. Commit (only when the user has asked)\ngit commit -m \"feat(api): add foo provider\"\n\n# 4. Push (pull --rebase if needed, but NEVER reset/checkout)\ngit pull --rebase && git push\n```\n\n### If Rebase Conflicts Occur\n\n- Resolve conflicts in YOUR files only.\n- If a conflict touches a file you didn't modify, abort the rebase and ask the user.\n- NEVER force-push.\n\n### User Override\n\nIf the user's instructions conflict with the rules above, ask for confirmation that they want to override the rules. Only then execute their instructions.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/Kuberwastaken/claurst/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Development Rules\n\nAgent-facing rules for working on Claurst. Mirrors and extends `src-rust/.claude/CLAUDE.md`; when the two disagree, the rule closer to the code wins.\n\n## Conversational Style\n\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n- When the user asks a question, answer it first before making edits or running implementation commands.\n\n## Code Quality\n\n- Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n- No `.unwrap()` / `.expect()` on fallible operations in production paths — propagate via `Result` or pattern-match. `unwrap` is acceptable in tests and in cases where the invariant is statically obvious and commented.\n- Avoid speculative `.clone()` — borrow first, clone only when ownership is actually needed. Same applies to `.to_string()` on `&str`.\n- No `unsafe` blocks without a `// SAFETY:` comment explaining the invariant.\n- Single-line helper functions with a single call site are forbidden; inline them instead.\n- Don't guess external API shapes. Read the crate source under `~/.cargo/registry/` or check `cargo doc --open`. For Anthropic / OpenAI / Google wire formats, the `crates/api/src/providers/<provider>.rs` files are the authoritative reference inside this repo.\n- **NEVER use type erasure to silence the compiler** — no `Box<dyn Any>`, no `serde_json::Value` shoved through a typed boundary just because the right type is annoying to derive. If a type is hard to express, ask the user.\n- NEVER remove or downgrade code to fix compiler errors from outdated dependencies; bump the dependency in `Cargo.toml` or `src-rust/Cargo.toml` workspace deps instead.\n- Always ask before removing functionality or code that appears to be intentional.\n- Do not preserve backward compatibility unless the user explicitly asks for it.\n- Never hardcode keybinding checks inline (e.g. `key == KeyCode::Char('s') && mods.ctrl()`). All keybindings must flow through the configurable keybinding system in `crates/core/src/keybindings.rs` — add a default there.\n- NEVER modify generated files directly. Generated artefacts in this repo:\n  - `src-rust/Cargo.lock` — regenerated by cargo; for version bumps use [`scripts/bump-version.py`](scripts/bump-version.py).\n  - `npm/package.json` `version` field — also stamped by `bump-version.py`.\n\n## Commands\n\nRun from `src-rust/` unless noted.\n\n- After Rust changes (not docs): `cargo check --workspace` — fix every error and warning before committing.\n- Clippy: `cargo clippy --workspace --all-targets -- -D warnings`. Fix lints; do not `#[allow(...)]` without justification.\n- Format: `cargo fmt --all`. Run before committing.\n- Tests: `cargo test --workspace` for everything, `cargo test --package claurst-<crate>` for a single crate, `cargo test --package claurst-<crate> -- <pattern>` for a specific test.\n- Avoid running `cargo build --release` or `cargo run --release` unless you specifically need optimised output — debug builds and `cargo check` are 10× faster.\n- If you create or modify a test, run it and iterate until it passes.\n- For TUI changes: validate by hand with `cargo run -- \"test prompt\"` (interactive) or `cargo run -- --print \"test\"` (headless). The `--print` mode is faster for verifying non-TUI logic.\n- Don't run blocking interactive commands you can't exit — the agent will hang. If you must, capture output with `--print` mode or pipe into `head`.\n\n### Testing the TUI in a controlled terminal\n\nThe ratatui frontend is sensitive to terminal size and key encoding. For repeatable manual tests use tmux:\n\n```bash\n# Build a debug binary once\ncargo build\n\n# 80×24 session\ntmux new-session -d -s claurst-test -x 80 -y 24\ntmux send-keys -t claurst-test \"./target/debug/claurst\" Enter\n\n# Give it time to redraw, then capture\nsleep 2 && tmux capture-pane -t claurst-test -p\n\n# Drive input\ntmux send-keys -t claurst-test \"your prompt here\" Enter\ntmux send-keys -t claurst-test Escape\ntmux send-keys -t claurst-test C-o   # ctrl+o\n\n# Cleanup\ntmux kill-session -t claurst-test\n```\n\nOn Windows hosts, prefer `cargo run -- --print \"...\"` against the headless path. The Windows console has known quirks with the kitty keyboard protocol — see `crates/tui` for the push/pop workaround.\n\n## Issues & PR Comments\n\nWhen posting issue/PR comments:\n\n- Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`.\n- Never pass multi-line markdown directly via `--body` in shell commands.\n- Preview the exact comment text before posting.\n- Post exactly one final comment unless the user explicitly asks for multiple comments.\n- If a comment is malformed, delete it immediately, then post one corrected comment.\n- Keep comments concise, technical, and in the user's tone.\n\nWhen creating issues, add labels that map to the relevant crate(s) — for example `crate:tui`, `crate:api`, `crate:tools`, `crate:mcp`, `crate:acp`. If an issue spans multiple crates, add all relevant labels.\n\nWhen closing issues via commit, include `fixes #<number>` or `closes #<number>` in the commit message — GitHub closes the issue automatically on merge to main.\n\n### 1. Provider identifier (`crates/core/src/provider_id.rs`)\n\nAdd a well-known constant on `ProviderId`, e.g. `pub const FOO: &'static str = \"foo\";`. Use the canonical name the provider publishes for its API.\n\n### 2. Provider implementation (`crates/api/src/providers/`)\n\n- OpenAI-compatible: add an entry to `openai_compat_providers.rs`. This is one line + an optional base-URL helper.\n- Custom wire format: create `crates/api/src/providers/<name>.rs` exposing a struct that implements `LlmProvider` (see `provider.rs`). Mirror the structure of `anthropic.rs` or `google.rs` — request shaping, response parsing, streaming SSE handling, tool conversion.\n- Add `pub mod <name>; pub use <name>::<Name>Provider;` to `providers/mod.rs`.\n\n### 3. Register the provider (`crates/api/src/registry.rs`)\n\nImport the new provider and add it to the registry construction. The registry hands back `Arc<dyn LlmProvider>` by id.\n\n### 4. Model registry (`crates/api/src/model_registry.rs`)\n\nAdd the canonical model IDs and capability metadata (context window, supports thinking, supports vision, etc.).\n\n### 5. Auth & env detection (`crates/core/src/auth_store.rs`, related)\n\nIf the provider uses an env var (e.g. `FOO_API_KEY`), wire it into the auth-store probe. For OAuth-style providers, see `codex_oauth.rs` and `device_code.rs` for the existing patterns.\n\n### 6. Tests\n\n- Add a smoke test in `crates/api/tests/` that exercises request shaping and response parsing against a mocked HTTP body. No live API calls — use the fixture pattern that the existing provider tests follow.\n- If the provider supports tool calls, add a tool-call round-trip fixture.\n- For OpenAI-compatible providers, the shared test in `crates/api/tests/openai_compat.rs` covers most paths; usually just adding a row to its provider matrix is enough.\n\n### 7. Documentation\n\n- `README.md`: add the provider to the \"Supported Providers\" list if it's user-visible.\n- `docs/providers.md`: setup instructions, env var, and `settings.json` shape.\n\n## Releasing\n\nClaurst uses a **single workspace version** stamped across every surface (Cargo workspace, Cargo.lock entries for the 12 `claurst*` crates, `npm/package.json`, README badge, docs, ACP registry template). Versioning is forward-only — the release workflow refuses to ship a tag less than or equal to the highest existing tag.\n\n## **CRITICAL** Git Rules for Parallel Agents\n\nThis repo runs parallel agents in worktrees under `.claude/worktrees/`. Multiple agents may be modifying different files in the same checkout simultaneously. You MUST follow these rules:\n\n### Committing\n\n- **ONLY commit files YOU changed in THIS session.** Never commit unless the user has explicitly asked you to commit (see `src-rust/.claude/CLAUDE.md` — the rule is \"NEVER EVER commit\").\n- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR.\n- NEVER use `git add -A` or `git add .` — these sweep up changes from other agents.\n- ALWAYS use `git add <specific-file-paths>` listing only files you modified.\n- Before committing, run `git status` and verify you are only staging YOUR files.\n- Track which files you created/modified/deleted during the session.\n- Cargo.lock counts as yours if and only if your edits to `Cargo.toml` caused it to change.\n\n### Forbidden Git Operations\n\nThese can destroy other agents' work:\n\n- `git reset --hard` — destroys uncommitted changes\n- `git checkout .` / `git restore .` — destroys uncommitted changes\n- `git clean -fd` — deletes untracked files\n- `git stash` — stashes ALL changes including other agents' work\n- `git add -A` / `git add .` — stages other agents' uncommitted work\n- `git commit --no-verify` — bypasses required checks; never allowed\n- Force-push to `main` — never allowed; the patch-release workflow is the only thing that may force-move tags, and it does so via the workflow runner, not from your shell\n\n### Safe Workflow\n\n```bash\n# 1. Check status\ngit status\n\n# 2. Stage only your files\ngit add src-rust/crates/api/src/providers/foo.rs\ngit add docs/providers.md\n\n# 3. Commit (only when the user has asked)\ngit commit -m \"feat(api): add foo provider\"\n\n# 4. Push (pull --rebase if needed, but NEVER reset/checkout)\ngit pull --rebase && git push\n```\n\n### If Rebase Conflicts Occur\n\n- Resolve conflicts in YOUR files only.\n- If a conflict touches a file you didn't modify, abort the rebase and ask the user.\n- NEVER force-push.\n\n### User Override\n\nIf the user's instructions conflict with the rules above, ask for confirmation that they want to override the rules. Only then execute their instructions.\n","isInternal":false,"tokens":2401,"sizeBytes":10063},{"name":"agents.md","path":"docs/agents.md","rawUrl":"https://raw.githubusercontent.com/Kuberwastaken/claurst/HEAD/docs/agents.md","title":"docs - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Agents and Multi-Agent Features\n\nClaurst has a named-agent system that lets you select a pre-configured persona with its own tool permissions, model, system prompt, and turn budget. For larger tasks the model can spawn sub-agents with the `Agent` tool, and `/managed-agents` configures a manager-executor split.\n\n---\n\n## Built-in Named Agents\n\nThree agents ship by default. Their definitions can be overridden per-user in `~/.claurst/settings.json`.\n\n### build\n\nFull tool access. Intended for implementing features and fixing bugs.\n\n| Property | Value |\n|---|---|\n| Access | `full` — all tools available |\n| Max turns | Unlimited (uses the global default) |\n| Display color | Cyan |\n\nDefault system prompt prefix:\n\n> You are the build agent. You have full access to read, write, and execute. Focus on implementing the requested changes completely and correctly.\n\n### plan\n\nRead-only analysis. Cannot write files or execute commands. Intended for understanding codebases and planning changes before committing to implementation.\n\n| Property | Value |\n|---|---|\n| Access | `read-only` — file reads, no writes or shell execution |\n| Max turns | 20 |\n| Display color | Yellow |\n\nDefault system prompt prefix:\n\n> You are the plan agent. You can read files and analyze code but cannot write files or execute commands. Focus on understanding the codebase and describing what changes should be made.\n\n### explore\n\nFast search-only exploration. Intended for quickly locating relevant code and answering questions about structure.\n\n| Property | Value |\n|---|---|\n| Access | `search-only` — search tools only |\n| Max turns | 15 |\n| Display color | Green |\n\nDefault system prompt prefix:\n\n> You are the explore agent. You can search and read files. Focus on quickly finding relevant code and answering questions about the codebase.\n\n---\n\n## Selecting an Agent with --agent\n\nPass `--agent <name>` to activate a named agent for a session:\n\n```\nclaurst --agent build \"implement the OAuth2 login flow\"\nclaurst --agent plan \"analyze the database schema and suggest improvements\"\nclaurst --agent explore \"find all usages of the deprecated config API\"\n```\n\nThe `--agent` flag can be combined with `--provider` and `--model`:\n\n```\nclaurst --agent plan --provider openai --model o3 \"review this architecture\"\n```\n\nAn unknown name prints a warning and runs without an agent. In the interactive TUI, pressing `Tab` on an empty prompt (while no response is streaming) toggles between the `build` and `plan` agents.\n\nAccess levels filter the tool list: `read-only` keeps tools whose permission level is read-only or none, plus `AskUserQuestion` (built-in tools only; `Agent` and MCP tools are removed); `search-only` keeps only `Grep`, `Glob`, `Read`, `WebSearch`, and `WebFetch`.\n\n---\n\n## The /agent and /agents Commands\n\nWithin an interactive session, `/agent` lists all available named agents (built-in and custom) and `/agent <name>` shows one agent's details:\n\n```\n/agent\n/agent plan\n```\n\nThe list shows the agent name, description, access level, and max turn limit. Agents with `visible: false` in their definition are hidden from this list. `/agent` does not switch agents; start Claurst with `--agent <name>` (or use `Tab`, above).\n\n`/agents` opens a separate TUI menu that browses and edits Markdown agent files in `~/.claurst/agents/` and `<project>/.claurst/agents/` (front-matter keys `name`, `description`, `model`, `tools`, `memory_scope`). These files are not the `settings.json` definitions below and are not selectable with `--agent`.\n\n---\n\n## Custom Agent Definitions\n\nDefine custom agents in `~/.claurst/settings.json` under the `agents` key. Custom definitions override built-in agents of the same name.\n\n```json\n{\n  \"agents\": {\n    \"review\": {\n      \"description\": \"Senior code reviewer focused on correctness and security\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.3,\n      \"prompt\": \"You are a senior software engineer performing code review. Focus on correctness, security vulnerabilities, performance issues, and maintainability. Be specific about problems and suggest concrete fixes.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"magenta\"\n    },\n    \"test-writer\": {\n      \"description\": \"Writes comprehensive unit and integration tests\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are a test engineer. Write thorough tests covering happy paths, edge cases, and error conditions. Use the project's existing test framework and conventions.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"blue\"\n    },\n    \"docs\": {\n      \"description\": \"Technical documentation writer\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"temperature\": 0.5,\n      \"prompt\": \"You are a technical writer. Write clear, accurate documentation for the code you are given. Use the project's existing documentation style.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 25,\n      \"color\": \"cyan\"\n    }\n  }\n}\n```\n\n### AgentDefinition Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `description` | string | Short description shown in `/agent` |\n| `model` | string | Model override in `provider/model` or bare `model` form. Omit to use the session default. |\n| `temperature` | number | Sampling temperature override (0.0–1.0). Omit to use the model default. |\n| `prompt` | string | System prompt prefix prepended before the main system prompt. |\n| `access` | string | Permission restriction: `\"full\"` (all tools), `\"read-only\"` (no writes/shell), `\"search-only\"` (search tools only). Default: `\"full\"`. |\n| `visible` | bool | Whether to show in `/agent` output. Default: `true`. |\n| `max_turns` | number or null | Maximum agentic turns. Null means unlimited. Overrides the global turn budget. |\n| `color` | string | ANSI terminal color for display: `\"cyan\"`, `\"magenta\"`, `\"green\"`, `\"yellow\"`, `\"blue\"`, etc. |\n\nUse the agent with the `--agent` flag:\n\n```\nclaurst --agent review \"check the authentication module for security issues\"\nclaurst --agent test-writer \"write tests for the payment processor\"\n```\n\n---\n\n## Sub-agents and Task Tools\n\nThe `Agent` tool lets the model spawn a sub-agent with its own prompt, optional tool list, model, turn cap (default 10), `isolation: \"worktree\"`, and `run_in_background`. `SendMessage`, `TeamCreate`, and `TeamDelete` are also in the standard tool set. See [Tools](tools.md) for each tool's parameters.\n\nThe task tools (`TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, `TaskStop`, `TaskOutput`) are part of the standard tool set in every session. `/tasks` (alias `/bashes`) asks the model to list current tasks with `TaskList`.\n\n### Coordinator mode (not wired)\n\n`CLAURST_COORDINATOR_MODE` is defined in `crates/query/src/coordinator.rs`, but nothing in the running agent loop reads it: no coordinator prompt is injected, no tools are withheld from workers, and resumed sessions are not mode-matched. Setting it has no effect. See [Local Models](local-models.md#is-claurst_coordinator_mode1-a-real-thing).\n\n---\n\n## Agent Definitions in settings.json: Complete Example\n\n```json\n{\n  \"provider\": \"anthropic\",\n  \"agents\": {\n    \"build\": {\n      \"description\": \"Full-access implementation agent\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are the build agent. Implement requested changes completely. Prefer targeted, minimal edits over rewrites.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"cyan\"\n    },\n    \"plan\": {\n      \"description\": \"Read-only analysis and planning agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.2,\n      \"prompt\": \"You are the plan agent. Analyse the codebase carefully before producing a detailed, step-by-step implementation plan. Do not write or execute anything.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 20,\n      \"color\": \"yellow\"\n    },\n    \"explore\": {\n      \"description\": \"Fast search-only exploration agent\",\n      \"model\": \"anthropic/claude-haiku-4-5-20251001\",\n      \"prompt\": \"You are the explore agent. Search and read files to answer questions quickly.\",\n      \"access\": \"search-only\",\n      \"visible\": true,\n      \"max_turns\": 15,\n      \"color\": \"green\"\n    },\n    \"security\": {\n      \"description\": \"Security-focused read-only audit agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.1,\n      \"prompt\": \"You are a security auditor. Look for authentication flaws, injection vulnerabilities, insecure dependencies, and data-exposure risks. Report findings with severity levels (critical, high, medium, low) and concrete remediation steps.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 40,\n      \"color\": \"magenta\"\n    },\n    \"architect\": {\n      \"description\": \"System design and architecture advisor\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.4,\n      \"prompt\": \"You are a software architect. Reason carefully about system design trade-offs, scalability, maintainability, and technical debt. Produce clear architectural recommendations with rationale.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"blue\"\n    }\n  }\n}\n```\n\n---\n\n## Managed Agents (Preview)\n\nManaged agents provide a **manager-executor** architecture: you configure separate models, turn budgets, concurrency limits, and budget splits for the manager and for executors. When enabled, the session runs on the manager model and gets orchestration instructions in its system prompt.\n\n### Enabling and configuring\n\n```\n/managed-agents presets                               — list presets\n/managed-agents preset <name>                         — apply a preset\n/managed-agents configure manager-model  anthropic/claude-opus-4-6\n/managed-agents configure executor-model anthropic/claude-sonnet-4-6\n/managed-agents configure concurrent     3\n/managed-agents budget 5.00\n/managed-agents enable\n```\n\nSee [Managed Agents](./advanced.md#managed-agents) in the advanced guide for the full configuration reference.\n","isInternal":false,"tokens":2448,"sizeBytes":10156}],"systemPromptSnippet":"<yakaai_skills repo=\"Kuberwastaken/claurst\">\n<!-- File: AGENTS.md (Tokens: ~2401 | Category: root-instruction) -->\n# Development Rules\n\nAgent-facing rules for working on Claurst. Mirrors and extends `src-rust/.claude/CLAUDE.md`; when the two disagree, the rule closer to the code wins.\n\n## Conversational Style\n\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n- When the user asks a question, answer it first before making edits or running implementation commands.\n\n## Code Quality\n\n- Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n- No `.unwrap()` / `.expect()` on fallible operations in production paths — propagate via `Result` or pattern-match. `unwrap` is acceptable in tests and in cases where the invariant is statically obvious and commented.\n- Avoid speculative `.clone()` — borrow first, clone only when ownership is actually needed. Same applies to `.to_string()` on `&str`.\n- No `unsafe` blocks without a `// SAFETY:` comment explaining the invariant.\n- Single-line helper functions with a single call site are forbidden; inline them instead.\n- Don't guess external API shapes. Read the crate source under `~/.cargo/registry/` or check `cargo doc --open`. For Anthropic / OpenAI / Google wire formats, the `crates/api/src/providers/<provider>.rs` files are the authoritative reference inside this repo.\n- **NEVER use type erasure to silence the compiler** — no `Box<dyn Any>`, no `serde_json::Value` shoved through a typed boundary just because the right type is annoying to derive. If a type is hard to express, ask the user.\n- NEVER remove or downgrade code to fix compiler errors from outdated dependencies; bump the dependency in `Cargo.toml` or `src-rust/Cargo.toml` workspace deps instead.\n- Always ask before removing functionality or code that appears to be intentional.\n- Do not preserve backward compatibility unless the user explicitly asks for it.\n- Never hardcode keybinding checks inline (e.g. `key == KeyCode::Char('s') && mods.ctrl()`). All keybindings must flow through the configurable keybinding system in `crates/core/src/keybindings.rs` — add a default there.\n- NEVER modify generated files directly. Generated artefacts in this repo:\n  - `src-rust/Cargo.lock` — regenerated by cargo; for version bumps use [`scripts/bump-version.py`](scripts/bump-version.py).\n  - `npm/package.json` `version` field — also stamped by `bump-version.py`.\n\n## Commands\n\nRun from `src-rust/` unless noted.\n\n- After Rust changes (not docs): `cargo check --workspace` — fix every error and warning before committing.\n- Clippy: `cargo clippy --workspace --all-targets -- -D warnings`. Fix lints; do not `#[allow(...)]` without justification.\n- Format: `cargo fmt --all`. Run before committing.\n- Tests: `cargo test --workspace` for everything, `cargo test --package claurst-<crate>` for a single crate, `cargo test --package claurst-<crate> -- <pattern>` for a specific test.\n- Avoid running `cargo build --release` or `cargo run --release` unless you specifically need optimised output — debug builds and `cargo check` are 10× faster.\n- If you create or modify a test, run it and iterate until it passes.\n- For TUI changes: validate by hand with `cargo run -- \"test prompt\"` (interactive) or `cargo run -- --print \"test\"` (headless). The `--print` mode is faster for verifying non-TUI logic.\n- Don't run blocking interactive commands you can't exit — the agent will hang. If you must, capture output with `--print` mode or pipe into `head`.\n\n### Testing the TUI in a controlled terminal\n\nThe ratatui frontend is sensitive to terminal size and key encoding. For repeatable manual tests use tmux:\n\n```bash\n# Build a debug binary once\ncargo build\n\n# 80×24 session\ntmux new-session -d -s claurst-test -x 80 -y 24\ntmux send-keys -t claurst-test \"./target/debug/claurst\" Enter\n\n# Give it time to redraw, then capture\nsleep 2 && tmux capture-pane -t claurst-test -p\n\n# Drive input\ntmux send-keys -t claurst-test \"your prompt here\" Enter\ntmux send-keys -t claurst-test Escape\ntmux send-keys -t claurst-test C-o   # ctrl+o\n\n# Cleanup\ntmux kill-session -t claurst-test\n```\n\nOn Windows hosts, prefer `cargo run -- --print \"...\"` against the headless path. The Windows console has known quirks with the kitty keyboard protocol — see `crates/tui` for the push/pop workaround.\n\n## Issues & PR Comments\n\nWhen posting issue/PR comments:\n\n- Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`.\n- Never pass multi-line markdown directly via `--body` in shell commands.\n- Preview the exact comment text before posting.\n- Post exactly one final comment unless the user explicitly asks for multiple comments.\n- If a comment is malformed, delete it immediately, then post one corrected comment.\n- Keep comments concise, technical, and in the user's tone.\n\nWhen creating issues, add labels that map to the relevant crate(s) — for example `crate:tui`, `crate:api`, `crate:tools`, `crate:mcp`, `crate:acp`. If an issue spans multiple crates, add all relevant labels.\n\nWhen closing issues via commit, include `fixes #<number>` or `closes #<number>` in the commit message — GitHub closes the issue automatically on merge to main.\n\n### 1. Provider identifier (`crates/core/src/provider_id.rs`)\n\nAdd a well-known constant on `ProviderId`, e.g. `pub const FOO: &'static str = \"foo\";`. Use the canonical name the provider publishes for its API.\n\n### 2. Provider implementation (`crates/api/src/providers/`)\n\n- OpenAI-compatible: add an entry to `openai_compat_providers.rs`. This is one line + an optional base-URL helper.\n- Custom wire format: create `crates/api/src/providers/<name>.rs` exposing a struct that implements `LlmProvider` (see `provider.rs`). Mirror the structure of `anthropic.rs` or `google.rs` — request shaping, response parsing, streaming SSE handling, tool conversion.\n- Add `pub mod <name>; pub use <name>::<Name>Provider;` to `providers/mod.rs`.\n\n### 3. Register the provider (`crates/api/src/registry.rs`)\n\nImport the new provider and add it to the registry construction. The registry hands back `Arc<dyn LlmProvider>` by id.\n\n### 4. Model registry (`crates/api/src/model_registry.rs`)\n\nAdd the canonical model IDs and capability metadata (context window, supports thinking, supports vision, etc.).\n\n### 5. Auth & env detection (`crates/core/src/auth_store.rs`, related)\n\nIf the provider uses an env var (e.g. `FOO_API_KEY`), wire it into the auth-store probe. For OAuth-style providers, see `codex_oauth.rs` and `device_code.rs` for the existing patterns.\n\n### 6. Tests\n\n- Add a smoke test in `crates/api/tests/` that exercises request shaping and response parsing against a mocked HTTP body. No live API calls — use the fixture pattern that the existing provider tests follow.\n- If the provider supports tool calls, add a tool-call round-trip fixture.\n- For OpenAI-compatible providers, the shared test in `crates/api/tests/openai_compat.rs` covers most paths; usually just adding a row to its provider matrix is enough.\n\n### 7. Documentation\n\n- `README.md`: add the provider to the \"Supported Providers\" list if it's user-visible.\n- `docs/providers.md`: setup instructions, env var, and `settings.json` shape.\n\n## Releasing\n\nClaurst uses a **single workspace version** stamped across every surface (Cargo workspace, Cargo.lock entries for the 12 `claurst*` crates, `npm/package.json`, README badge, docs, ACP registry template). Versioning is forward-only — the release workflow refuses to ship a tag less than or equal to the highest existing tag.\n\n## **CRITICAL** Git Rules for Parallel Agents\n\nThis repo runs parallel agents in worktrees under `.claude/worktrees/`. Multiple agents may be modifying different files in the same checkout simultaneously. You MUST follow these rules:\n\n### Committing\n\n- **ONLY commit files YOU changed in THIS session.** Never commit unless the user has explicitly asked you to commit (see `src-rust/.claude/CLAUDE.md` — the rule is \"NEVER EVER commit\").\n- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR.\n- NEVER use `git add -A` or `git add .` — these sweep up changes from other agents.\n- ALWAYS use `git add <specific-file-paths>` listing only files you modified.\n- Before committing, run `git status` and verify you are only staging YOUR files.\n- Track which files you created/modified/deleted during the session.\n- Cargo.lock counts as yours if and only if your edits to `Cargo.toml` caused it to change.\n\n### Forbidden Git Operations\n\nThese can destroy other agents' work:\n\n- `git reset --hard` — destroys uncommitted changes\n- `git checkout .` / `git restore .` — destroys uncommitted changes\n- `git clean -fd` — deletes untracked files\n- `git stash` — stashes ALL changes including other agents' work\n- `git add -A` / `git add .` — stages other agents' uncommitted work\n- `git commit --no-verify` — bypasses required checks; never allowed\n- Force-push to `main` — never allowed; the patch-release workflow is the only thing that may force-move tags, and it does so via the workflow runner, not from your shell\n\n### Safe Workflow\n\n```bash\n# 1. Check status\ngit status\n\n# 2. Stage only your files\ngit add src-rust/crates/api/src/providers/foo.rs\ngit add docs/providers.md\n\n# 3. Commit (only when the user has asked)\ngit commit -m \"feat(api): add foo provider\"\n\n# 4. Push (pull --rebase if needed, but NEVER reset/checkout)\ngit pull --rebase && git push\n```\n\n### If Rebase Conflicts Occur\n\n- Resolve conflicts in YOUR files only.\n- If a conflict touches a file you didn't modify, abort the rebase and ask the user.\n- NEVER force-push.\n\n### User Override\n\nIf the user's instructions conflict with the rules above, ask for confirmation that they want to override the rules. Only then execute their instructions.\n\n<!-- File: docs/agents.md (Tokens: ~2448 | Category: root-instruction) -->\n# Agents and Multi-Agent Features\n\nClaurst has a named-agent system that lets you select a pre-configured persona with its own tool permissions, model, system prompt, and turn budget. For larger tasks the model can spawn sub-agents with the `Agent` tool, and `/managed-agents` configures a manager-executor split.\n\n---\n\n## Built-in Named Agents\n\nThree agents ship by default. Their definitions can be overridden per-user in `~/.claurst/settings.json`.\n\n### build\n\nFull tool access. Intended for implementing features and fixing bugs.\n\n| Property | Value |\n|---|---|\n| Access | `full` — all tools available |\n| Max turns | Unlimited (uses the global default) |\n| Display color | Cyan |\n\nDefault system prompt prefix:\n\n> You are the build agent. You have full access to read, write, and execute. Focus on implementing the requested changes completely and correctly.\n\n### plan\n\nRead-only analysis. Cannot write files or execute commands. Intended for understanding codebases and planning changes before committing to implementation.\n\n| Property | Value |\n|---|---|\n| Access | `read-only` — file reads, no writes or shell execution |\n| Max turns | 20 |\n| Display color | Yellow |\n\nDefault system prompt prefix:\n\n> You are the plan agent. You can read files and analyze code but cannot write files or execute commands. Focus on understanding the codebase and describing what changes should be made.\n\n### explore\n\nFast search-only exploration. Intended for quickly locating relevant code and answering questions about structure.\n\n| Property | Value |\n|---|---|\n| Access | `search-only` — search tools only |\n| Max turns | 15 |\n| Display color | Green |\n\nDefault system prompt prefix:\n\n> You are the explore agent. You can search and read files. Focus on quickly finding relevant code and answering questions about the codebase.\n\n---\n\n## Selecting an Agent with --agent\n\nPass `--agent <name>` to activate a named agent for a session:\n\n```\nclaurst --agent build \"implement the OAuth2 login flow\"\nclaurst --agent plan \"analyze the database schema and suggest improvements\"\nclaurst --agent explore \"find all usages of the deprecated config API\"\n```\n\nThe `--agent` flag can be combined with `--provider` and `--model`:\n\n```\nclaurst --agent plan --provider openai --model o3 \"review this architecture\"\n```\n\nAn unknown name prints a warning and runs without an agent. In the interactive TUI, pressing `Tab` on an empty prompt (while no response is streaming) toggles between the `build` and `plan` agents.\n\nAccess levels filter the tool list: `read-only` keeps tools whose permission level is read-only or none, plus `AskUserQuestion` (built-in tools only; `Agent` and MCP tools are removed); `search-only` keeps only `Grep`, `Glob`, `Read`, `WebSearch`, and `WebFetch`.\n\n---\n\n## The /agent and /agents Commands\n\nWithin an interactive session, `/agent` lists all available named agents (built-in and custom) and `/agent <name>` shows one agent's details:\n\n```\n/agent\n/agent plan\n```\n\nThe list shows the agent name, description, access level, and max turn limit. Agents with `visible: false` in their definition are hidden from this list. `/agent` does not switch agents; start Claurst with `--agent <name>` (or use `Tab`, above).\n\n`/agents` opens a separate TUI menu that browses and edits Markdown agent files in `~/.claurst/agents/` and `<project>/.claurst/agents/` (front-matter keys `name`, `description`, `model`, `tools`, `memory_scope`). These files are not the `settings.json` definitions below and are not selectable with `--agent`.\n\n---\n\n## Custom Agent Definitions\n\nDefine custom agents in `~/.claurst/settings.json` under the `agents` key. Custom definitions override built-in agents of the same name.\n\n```json\n{\n  \"agents\": {\n    \"review\": {\n      \"description\": \"Senior code reviewer focused on correctness and security\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.3,\n      \"prompt\": \"You are a senior software engineer performing code review. Focus on correctness, security vulnerabilities, performance issues, and maintainability. Be specific about problems and suggest concrete fixes.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"magenta\"\n    },\n    \"test-writer\": {\n      \"description\": \"Writes comprehensive unit and integration tests\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are a test engineer. Write thorough tests covering happy paths, edge cases, and error conditions. Use the project's existing test framework and conventions.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"blue\"\n    },\n    \"docs\": {\n      \"description\": \"Technical documentation writer\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"temperature\": 0.5,\n      \"prompt\": \"You are a technical writer. Write clear, accurate documentation for the code you are given. Use the project's existing documentation style.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 25,\n      \"color\": \"cyan\"\n    }\n  }\n}\n```\n\n### AgentDefinition Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `description` | string | Short description shown in `/agent` |\n| `model` | string | Model override in `provider/model` or bare `model` form. Omit to use the session default. |\n| `temperature` | number | Sampling temperature override (0.0–1.0). Omit to use the model default. |\n| `prompt` | string | System prompt prefix prepended before the main system prompt. |\n| `access` | string | Permission restriction: `\"full\"` (all tools), `\"read-only\"` (no writes/shell), `\"search-only\"` (search tools only). Default: `\"full\"`. |\n| `visible` | bool | Whether to show in `/agent` output. Default: `true`. |\n| `max_turns` | number or null | Maximum agentic turns. Null means unlimited. Overrides the global turn budget. |\n| `color` | string | ANSI terminal color for display: `\"cyan\"`, `\"magenta\"`, `\"green\"`, `\"yellow\"`, `\"blue\"`, etc. |\n\nUse the agent with the `--agent` flag:\n\n```\nclaurst --agent review \"check the authentication module for security issues\"\nclaurst --agent test-writer \"write tests for the payment processor\"\n```\n\n---\n\n## Sub-agents and Task Tools\n\nThe `Agent` tool lets the model spawn a sub-agent with its own prompt, optional tool list, model, turn cap (default 10), `isolation: \"worktree\"`, and `run_in_background`. `SendMessage`, `TeamCreate`, and `TeamDelete` are also in the standard tool set. See [Tools](tools.md) for each tool's parameters.\n\nThe task tools (`TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, `TaskStop`, `TaskOutput`) are part of the standard tool set in every session. `/tasks` (alias `/bashes`) asks the model to list current tasks with `TaskList`.\n\n### Coordinator mode (not wired)\n\n`CLAURST_COORDINATOR_MODE` is defined in `crates/query/src/coordinator.rs`, but nothing in the running agent loop reads it: no coordinator prompt is injected, no tools are withheld from workers, and resumed sessions are not mode-matched. Setting it has no effect. See [Local Models](local-models.md#is-claurst_coordinator_mode1-a-real-thing).\n\n---\n\n## Agent Definitions in settings.json: Complete Example\n\n```json\n{\n  \"provider\": \"anthropic\",\n  \"agents\": {\n    \"build\": {\n      \"description\": \"Full-access implementation agent\",\n      \"model\": \"anthropic/claude-sonnet-4-6\",\n      \"prompt\": \"You are the build agent. Implement requested changes completely. Prefer targeted, minimal edits over rewrites.\",\n      \"access\": \"full\",\n      \"visible\": true,\n      \"max_turns\": null,\n      \"color\": \"cyan\"\n    },\n    \"plan\": {\n      \"description\": \"Read-only analysis and planning agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.2,\n      \"prompt\": \"You are the plan agent. Analyse the codebase carefully before producing a detailed, step-by-step implementation plan. Do not write or execute anything.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 20,\n      \"color\": \"yellow\"\n    },\n    \"explore\": {\n      \"description\": \"Fast search-only exploration agent\",\n      \"model\": \"anthropic/claude-haiku-4-5-20251001\",\n      \"prompt\": \"You are the explore agent. Search and read files to answer questions quickly.\",\n      \"access\": \"search-only\",\n      \"visible\": true,\n      \"max_turns\": 15,\n      \"color\": \"green\"\n    },\n    \"security\": {\n      \"description\": \"Security-focused read-only audit agent\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.1,\n      \"prompt\": \"You are a security auditor. Look for authentication flaws, injection vulnerabilities, insecure dependencies, and data-exposure risks. Report findings with severity levels (critical, high, medium, low) and concrete remediation steps.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 40,\n      \"color\": \"magenta\"\n    },\n    \"architect\": {\n      \"description\": \"System design and architecture advisor\",\n      \"model\": \"anthropic/claude-opus-4-6\",\n      \"temperature\": 0.4,\n      \"prompt\": \"You are a software architect. Reason carefully about system design trade-offs, scalability, maintainability, and technical debt. Produce clear architectural recommendations with rationale.\",\n      \"access\": \"read-only\",\n      \"visible\": true,\n      \"max_turns\": 30,\n      \"color\": \"blue\"\n    }\n  }\n}\n```\n\n---\n\n## Managed Agents (Preview)\n\nManaged agents provide a **manager-executor** architecture: you configure separate models, turn budgets, concurrency limits, and budget splits for the manager and for executors. When enabled, the session runs on the manager model and gets orchestration instructions in its system prompt.\n\n### Enabling and configuring\n\n```\n/managed-agents presets                               — list presets\n/managed-agents preset <name>                         — apply a preset\n/managed-agents configure manager-model  anthropic/claude-opus-4-6\n/managed-agents configure executor-model anthropic/claude-sonnet-4-6\n/managed-agents configure concurrent     3\n/managed-agents budget 5.00\n/managed-agents enable\n```\n\nSee [Managed Agents](./advanced.md#managed-agents) in the advanced guide for the full configuration reference.\n</yakaai_skills>"}