Profiles¶

Profiles let you configure different reviewer behavior for different agents. A profile targeting coder subagents can use a different model, scrutiny level, and tool visibility than the profile targeting the main general agent.

Built-in reviewer profiles¶

The profile_id setting selects a built-in behavioral template that defines what the reviewer watches for. This is different from the settings profiles described in the rest of this page — a settings profile controls which model, tools, and scrutiny level an agent gets, while profile_id controls the reviewer's mandate.

`profile_id`	Description
`general`	Instruction compliance. The reviewer reads the agent's system prompt and blocks when the agent deviates from it — ignoring its stated rules, skipping required steps, or acting outside its mandate. Does not block opinions, preference questions, or summaries of established work. Default when no `profile_id` is set.
`code`	Production-grade code. Blocks changes that skip understanding (no visible investigation before editing), expand scope beyond the task, patch symptoms instead of root causes, ignore production constraints, or claim completion without verification. The reviewer sees Read, Grep, and Glob output to judge whether the agent earned its edits through actual research.
`research`	Evidence-backed advice. Blocks confident recommendations and factual claims not grounded in visible research — web searches, doc lookups, or source inspection. Passes conceptual reasoning, brainstorming, and answers that clearly label their uncertainty.
`prompt`	Lean prompt engineering. When the agent writes prompts for other AI models, blocks verbosity, vague generalities ("be thorough", "ensure quality"), unnecessary examples, incident archaeology, and redundant restatements. Every sentence must impose an actionable constraint or supply context the downstream model cannot infer.
`spec`	Implementable plans. Blocks specs, architecture proposals, and implementation plans that dodge key decisions, hide uncertainty behind confident prose, or ignore obviously affected surfaces. Passes plans that are grounded in the actual codebase and explicit about what remains uncertain.

To use a built-in profile, name your settings profile with the matching profile_id. A profile named code automatically activates the built-in code template. A profile with any other name (like my-code-review) won't match a built-in — it gets the default system prompt unless you provide a system_prompt of your own.

Set profile_id in defaults to choose the baseline for agents that don't match any named profile. You can layer your own rules on top of any built-in profile using system_prompt_mode: append. See Custom Prompts.

How profiles work¶

defaults and profiles accept the same configuration keys. Settings resolve in order: server defaults → defaults → first matching profile. Each layer deep-merges on top of the previous.

defaults:
  model: gpt-5.4
  profile_id: general

profiles:
  # Off the shelf — name matches a built-in profile, so the agent gets
  # the code review mandate with no extra configuration needed
  code:
    agents: [coder, web-dev]
    model: claude-sonnet-4-6

  # Off the shelf + append — name matches the built-in "code" profile,
  # then appends a project-specific guardrail on top of it
  # (only one profile can be named "code", so this uses "spec" as the base
  # and adds the specific constraint the user cares about)
  spec:
    agents: [planner]
    system_prompt: |
      Our API contracts are defined in api/schemas/. Block any plan that
      adds or changes an endpoint without referencing the corresponding
      schema file. If no schema exists yet, the plan must include creating
      one as an explicit step.
    system_prompt_mode: append

  # Fully custom — name doesn't match any built-in profile, so the
  # entire reviewer mandate comes from system_prompt
  data-ops:
    agents: [etl-runner]
    model: gemini-2.5-pro
    system_prompt: |
      This agent processes CSV and Parquet files through our ETL pipeline.
      Block any operation that writes directly to the production database.
      Block any file write outside of the data/staging/ directory.
      Block schema changes to existing tables without a migration file.

The three profiles show the main patterns: using a built-in profile by naming your settings profile to match, layering project-specific rules on top of a built-in, and writing a fully custom reviewer mandate from scratch.

The `agents` key¶

Each profile requires an agents list to activate. Without it, the profile does nothing.

The agents list contains agent names that this profile should match:

general – the main Claude Code agent (default name)
Any subagent name (e.g., coder, web-dev, research)
Any CLI agent name from claude --agent <name>

First match wins – if an agent matches multiple profiles, only the first one applies.

`agents` in defaults vs. profiles¶

The agents key behaves differently in defaults and profiles:

In defaults: Controls which agents get reviewed when no profile matches them. Omit it to review all agents. List specific names to only review those agents by default.

In profiles: Controls which agents this profile applies to. Required for the profile to activate.

An agent not listed in defaults.agents can still be reviewed if a profile targets it. The agents key in defaults is a routing decision, not a gate.

What profiles can override¶

A profile can set any key that defaults accepts:

Key	Effect
`model`	Different reviewer model
`api_key`	Different provider credentials (`${ENV_VAR}` reference)
`system_prompt`	Completely custom reviewer prompt
`system_prompt_mode`	`"replace"` (default) or `"append"`
`tools`	Different tool visibility and enforcement
`cycle`	Different context cycling thresholds
`include_claude_md`	Whether to forward CLAUDE.md to this reviewer
`web_search`	Whether this reviewer can use web search
`model_tuning`	Whether to apply provider-specific prompt adjustments

Deep merge behavior¶

For nested dicts like tools and cycle, the merge is key-by-key. A profile that sets tools.output_visible doesn't erase defaults.tools.pre_review.

Exception: system_prompt does not merge. A profile's system_prompt replaces the system prompt entirely – it does not inherit from defaults.system_prompt. The system_prompt_mode key controls whether it replaces or appends to the server profile's prompt, not the defaults prompt.

Example: full profile¶

profiles:
  code:
    agents: [file-processor]
    model: gemini-2.5-flash
    system_prompt: |
      This agent bulk-renames and reformats files. It should never modify
      file content beyond whitespace and naming conventions. Block any edit
      that changes logic, return values, function signatures, or import
      paths. Block any new file creation — this agent only modifies
      existing files.
    system_prompt_mode: append
    tools:
      review_exempt: [Read, Glob, Grep]
      pre_review: [Bash]
      write_review: [Edit, Write]
    cycle:
      threshold_pct: 0.15

This configures a tightly scoped reviewer for a bulk file-processing subagent: the code built-in profile as a base (activated by the profile name), fast model, low scrutiny, appended guardrails specific to the task, most read-only tools exempt from review, but shell commands and file writes still reviewed.