Agents

Overview

The Agent tool (aliased as Task for compatibility) lets the main model delegate a piece of work to a subagent instead of doing it inline. By default a subagent runs in an isolated context window — it only sees the prompt it was given, does its own tool calls, and returns a single report. The parent never sees the intermediate search results, browsing, or file reads that got the subagent there, which keeps the main session's context clean.

Subagents come in two flavors: a small set of built-in agents that ship with Claudin, and custom agents you define yourself as a markdown file with YAML frontmatter — the same shape Claude Code uses for its subagents, adapted to Claudin's directory layout and provider-agnostic model handling.

Built-in agents

These are always available as subagent_type values, no configuration required. A project or personal agent with the same name overrides a built-in of the same type — see Writing a custom agent.

The read-only agents (Explore, Plan) drop Agent, Edit, Write, NotebookEdit, and apply_patch from their tool set — they can search and read, not modify.

Writing a custom agent

A custom agent is a single markdown file: YAML frontmatter for its configuration, then the system prompt as the body.

The filename is free-form — what matters is the name field in the frontmatter, which becomes the subagent_type the Agent tool is called with. Drop a file whose name matches a built-in (for example .claudin/agents/WebResearcher.md) and it overrides that built-in for the project. Merge order, each source winning over the previous one: built-in → plugin → user settings → project settings.

See Permissions for how these modes work session-wide.

---
name: reviewer-perf
description: Reviews a diff for performance regressions only.
model: haiku
tools: Read, Grep, Glob, Bash
---

Review the change for performance regressions only. Be concrete — cite
file:line, and skip anything that isn't a measurable regression.

How agents are invoked

Model selection

An agent's default model is inherit — it reuses whatever model the parent session is running. Precedence, highest first: an explicit model passed on the Agent call, then the agent definition's own model frontmatter, then inherit.

On providers that aren't Claude-native — anything routed through the OpenAI-compatible shim, such as OpenRouter, Gemini, DeepSeek, Mistral, or LM Studio — a bare alias like haiku or opus falls back to inheriting the parent's model, since an equivalent tier may not exist on that provider. Fix it without editing the agent file, in ~/.claudin/settings.json:

{
  "agentModelOverrides": {
    "built-in:WebResearcher": "deepseek-chat"
  }
}

See Model configuration for the full provider/model setup story.

Tool permissions

• No tools field: the agent inherits everything available to the session, minus a small set of interactive-only tools it can't use in isolation (AskUserQuestion, EnterPlanMode/ExitPlanMode, and similar).
• tools: is an allowlist; disallowedTools: is a denylist applied on top of it.
• Agent(TypeA, TypeB) inside a tools: list restricts which subagent_types that agent may itself spawn. By default, custom agents can't spawn further sub-agents at all — only a few built-in orchestrators (like WebResearcherManager) can fan out to a declared list, which keeps recursion bounded.
• MCP tools (mcp__*) always pass through regardless of the allow/deny list.

Managing agents

• /agents inside the REPL — browse built-in, project, and personal agents; create or edit one with a guided wizard.
• claudin agents — CLI subcommand that lists every agent visible from the current directory. Takes --setting-sources to scope which of user, project, local to include.
• The /create skill can also author a new agent (alongside skills and rules) straight into the .claudin/ structure from a plain-language description.

Differences from Claude Code

The file format and most of the model — frontmatter fields, delegation by description, tool allow/deny lists — match Claude Code's subagents on purpose. A few things are Claudin-specific:

Try it

Drop a project agent and invoke it directly:

mkdir -p .claudin/agents
cat > .claudin/agents/reviewer-perf.md <<'EOF'
---
name: reviewer-perf
description: Reviews a diff for performance regressions only.
model: haiku
---
Review the change for performance regressions only. Be concrete.
EOF

Then, inside the Claudin REPL, ask for it by name — "review this diff with reviewer-perf" — or let the main model pick it up on its own once the description matches the task at hand.