Configuration

Put a .anvil.yaml file at the root of the repository. Anvil also reads .anvil.yml and .gitea/anvil.yaml, in that order, and uses the first one it finds.

For reviews and questions on a pull request, the file is read from the PR's base branch, not from the PR itself. A PR that edits .anvil.yaml (to turn reviews off, widen path filters or drop a check) is still reviewed under the rules already on the base branch, and its change applies to PRs opened after it merges. The walkthrough's "Review details" section says which file and branch were used. Every key is optional. If the file has an error (invalid YAML, or a value of the wrong type), the whole file is ignored, the defaults apply, and the walkthrough comment shows the error. @anvil configuration shows the settings in effect for a PR.

Example #

This is .anvil.example.yaml from the Anvil repository:

# Copy to .anvil.yaml at the root of a repository. Every key is optional.
profile: chill            # chill: bugs and real risks only · assertive: also maintainability, tests, docs, nits
language: en
instructions: |
  We use zod for all input validation. Server code lives in server/, never import it from app/.
request_changes_on_critical: false

path_filters:             # globs; "!" excludes. Lock files and build output are always excluded.
  - "!**/*.generated.ts"
path_instructions:
  - path: "migrations/**"
    instructions: "Every migration must be reversible and safe to run twice."
  - path: "**/*.test.ts"
    instructions: "Don't flag style in tests; check that assertions test behaviour."

auto_review:
  enabled: true
  incremental: true       # after a push, review only the new commits
  drafts: false
  base_branches: []       # e.g. ["main", "release/*"]; empty = all
  ignore_title_keywords: ["wip", "do not review"]
  ignore_authors: ["renovate"]

walkthrough:
  sequence_diagram: auto  # auto: only for a flow across components · true · false
  estimate_effort: true

checks:                   # judged on every review, reported in the walkthrough and the commit status
  - name: Description explains why
    instructions: "The PR description says why the change is needed, not only what changed."
    mode: warning         # off | warning | error (error fails the `Anvil` status)

ci:
  analyze_failures: true  # explain failed CI jobs on the PR

reviews:
  fail_commit_status: false   # true: a review that errors fails the `Anvil` status
  guideline_files: true       # load AGENTS.md, CLAUDE.md, .cursorrules, copilot instructions
  nitpicks: folded            # inline | folded | off (chill always drops nits)
  routing: auto               # auto: cheap model for docs/bot PRs, mid-tier for small diffs, strongest for big or risky ones · off
  bots: light                 # dependabot, renovate, *[bot]: light | review | skip
  risky_paths: ["src/payments/**"]   # always reviewed on the strongest model (on top of migrations, auth, CI, Dockerfiles…)
  trivial_paths: ["translations/**"] # count as trivial, like docs
  # models: { light: claude-haiku-5-5, standard: claude-sonnet-5-5, deep: claude-opus-5-5 }
  triage: auto                # big deep reviews: a cheap model rates each file first, only risky files get the full review
  prep:                       # work done before the model is called (no repository code is ever run)
    context_pack: true        # callers, callees, types, tests and config of each changed function, in the prompt
    context_tokens: 8000
    static_analysis: true     # secret scanner, dependency check, risky-sink hints
    osv: true                 # look new dependency versions up on osv.dev (sends package names and versions)
    memo: true                # don't re-review code that comes back unchanged after a rebase or force-push

merge_risk_instructions: "Anything touching migrations/ is at least high."
security_risk_instructions: "Changes under server/auth/ are at least moderate."

chat:
  auto_reply: true            # answer replies in Anvil's review threads without @anvil

max_budget_usd: 2         # per agent run; can't exceed the server's MAX_BUDGET_USD

Top-level keys #

enabled #

boolean, default true. Set to false to turn off reviews and CI diagnosis for the repository. Commands that start a review still run.

enabled: false

profile #

chill or assertive, default chill. chill reports bugs, security problems and real risks, and drops nits. assertive also comments on maintainability, naming, tests, docs and style.

profile: assertive

language #

string, default en. The language Anvil writes in, as a language code or name.

language: de

instructions #

string, default empty. House rules added to every review.

instructions: |
  We use zod for all input validation.
  Server code lives in server/; never import it from app/.

request_changes_on_critical #

boolean, default false. When true, a review with at least one critical finding is posted as Request changes instead of a comment.

request_changes_on_critical: true

path_filters #

list of globs, default []. Which changed files are reviewed. Patterns without ! are includes: when there's at least one, only matching files are reviewed. Patterns starting with ! exclude. Dotfiles match.

Lock files, minified files, source maps, dist/, build/, .next/, node_modules/, vendor/ and *.snap are always excluded.

path_filters:
  - "src/**"
  - "!src/**/*.generated.ts"

path_instructions #

list of { path, instructions }, default []. Extra instructions for files that match a glob. They're added to a review when at least one changed file matches.

path_instructions:
  - path: "migrations/**"
    instructions: "Every migration must be reversible and safe to run twice."

merge_risk_instructions #

string, default empty. Extra guidance for the merge risk rating, added to every review. Use it to say what counts as risky in this repository.

merge_risk_instructions: "Anything touching migrations/ or billing/ is at least high."

security_risk_instructions #

string, default empty. Extra guidance for the security risk rating, added to every review.

security_risk_instructions: "Changes under server/auth/ or to CORS settings are at least moderate."

See Merge and security risk for the five levels.

max_budget_usd #

positive number, optional. Lowers the cost cap for each agent run on this repository, in US dollars. It can't go above the server's ceiling ($3 on this server). Questions are always capped at $1 or this value, whichever is lower.

max_budget_usd: 1.5

model #

string, optional. One Anthropic model for everything on this repository: every review tier, questions and CI diagnosis. It turns model routing into a single model; to change one tier only, use reviews.models instead.

model: claude-sonnet-5-5

auto_review #

When reviews start on their own. None of these apply to @anvil review.

auto_review:
  base_branches: ["main", "release/*"]
  ignore_authors: ["renovate"]

walkthrough #

walkthrough:
  sequence_diagram: false

checks #

list, default []. Pre-merge checks written in plain language and judged on every review. See Pre-merge checks.

checks:
  - name: Migrations are reversible
    instructions: "Every new file in migrations/ has a working down migration."
    mode: error

ci #

ci:
  analyze_failures: false

reviews #

reviews:
  fail_commit_status: true
  nitpicks: inline

Model routing #

Every review is routed to one of three tiers before it starts. The tier, and why, is in the walkthrough footer, on the review page and in the run list.

Only files in scope count (lock files and build output are always filtered out). For an incremental review, the tier comes from the new commits only. The assertive profile keeps small diffs on the deep tier at medium effort. When a light or standard review fails (runs out of turns or budget, or returns unusable output), it is rerun once on the deep tier instead of failing; both runs show in the run list.

reviews:
  routing: auto
  bots: skip                      # don't review dependabot/renovate at all
  risky_paths: ["src/ledger/**"]
  models:
    standard: claude-opus-5-5     # small diffs on Opus too, at medium effort

Preparation #

Before the model is called, Anvil does the work that needs no model, with a parser and git grep over the checkout. It never runs code from the repository.

• Context pack. For every changed hunk: the enclosing function or class (parsed with tree-sitter for TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP, C# and C++; other files get a line-based outline), the places that call it, the functions and types the changed lines use, the tests that reference it and where the environment variables it reads are set. Ranked by relevance and cut to prep.context_tokens. The reviewer reads this instead of opening files one by one, so deep reviews get fewer turns (REVIEW_PACKED_TURNS, 24 by default); a review that needs more is rerun once with the full allowance.
• Collapsing. Files renamed without changes, blocks moved unchanged between files and the same identifier edit repeated across files (a rename) are shown as one line each. Anything with an extra change stays in full.
• Static analysis. A secret scanner (provider key formats: AWS, GitHub, GitLab, Slack, Stripe, Google, npm, private keys) and a dependency check (new or changed versions in package.json, requirements*.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, checked against OSV). A provider key outside test data and a dependency version with a published advisory are posted as findings directly. Generic password = "…" matches and risky sinks (SQL built from strings, eval, shell commands, raw HTML, unsafe deserialisation, TLS checks turned off) go to the model as hints to confirm or drop.
• Triage (see triage above).
• Template walkthrough. The changed-files table, the layers and the change summaries are built from the diff and the parser; the model writes the summary, risks and findings, plus a sentence for the changes that most need one.
• Memo. Each reviewed function's content hash is stored with its findings. After a rebase, a file whose changed functions were all reviewed before (same path, same code, same review settings) is left out and its findings are re-anchored to the new lines. @anvil full review ignores the memo.

The walkthrough's "Review details" section says what was prepared for each review.

chat #

chat:
  auto_reply: false

agents #

What Anvil's code-changing agents may do. Read from .anvil.yaml on the pull request's base branch, so a pull request can't change these for itself. See Let Anvil change code.

agents:
  push: pr_branch
  command: pnpm test
  autofix_ci: true
  recipes:
    - name: changelog
      prompt: Add an entry for this pull request to CHANGELOG.md under "Unreleased".

Unknown keys are kept and ignored, so a file written for a newer version of Anvil still works.