Configuration
Set up review agents, connect your own AI keys, pick models, and tell PURA exactly which work each agent should handle — all from the dashboard in a few clicks.
1. Review agents
A review agent is the core unit of configuration in PURA. You create and manage agents in the dashboard — give each one a name, set its Status to Active or Inactive, and set its required daily, weekly, and monthly budgets that keep spending predictable.
Only Active agents are used when PURA reviews a pull request. Inactive agents are saved but skipped, so you can pause an agent without deleting it.
You can have as many agents as you like — one per team, one per project type, or a single global one. PURA picks the best Active agent for each PR automatically.
Start simple. One Active agent with a working key is all you need to get reviews flowing. You can split into multiple agents later as your team grows.
2. Providers & your keys
Inside each agent you add one or more providers. PURA supports Claude, OpenAI, and Gemini — all run reviews; pick whichever you already use or prefer.
You bring your own API key. Paste it once in the dashboard — PURA encrypts it at rest and never shows it again. Every inference call goes straight through your key, so the cost lands on your provider account at their published rates. PURA never marks up inference.
Your key, your bill.PURA's subscription and your provider bill are completely separate — you always know exactly what you're spending with each.
3. Choosing models
For each provider in an agent you choose the model to use. If you list more than one, PURA reviews with the first model in the list — so put the one you want this agent to use at the top.
To get a different model depending on the change, create more than one agent and let routing pick between them per PR (see Routing with .pura/PURA.md):
- A premium agent for risky or complex changes — payments, auth, core infrastructure — for thorough analysis.
- A leaner agent for routine changes — docs, dependency bumps, small refactors — to keep costs in check.
This way each PR gets the right depth of review without always paying top-tier prices.
4. Provider fallback
Add more than one provider to an agent and you get a budget fallback chain. Before a review runs, PURA picks the first provider in the agent that still has budget headroom — so reviews keep flowing even when one provider's budget is used up.
For example, put Claude first for quality with OpenAI and Gemini as backups. If Claude's daily budget is exhausted, PURA uses the next provider and the PR still gets reviewed.
Budget-based, not health failover.The chain switches providers based on remaining budget. If a provider's API errors mid-review, PURA reports the error on the PR instead of retrying another provider — comment /pura review to try again.
5. Routing with .pura/PURA.md
Optionally commit a .pura/PURA.md file to a repository (in the .pura/ directory, read from the default branch) to tell PURA how different kinds of changes should be reviewed. Write it in plain English — this is intent, not config syntax.
# PURA Review Routing
- Payments or billing changes: use a top-tier model.
- Product and backend changes: a balanced model is fine.
- Docs, typos, and dependency bumps: a lean model is enough.PURA reads your .pura/PURA.mdwhen a PR comes in and uses it to decide how much model firepower the change deserves — then matches the PR to the best Active agent you've set up.
With no .pura/PURA.md, PURA picks any available model from your Active agents. The file is purely optional, but a few plain-English lines go a long way toward smarter, more cost-efficient reviews.
6. Review guidance (reviewer.md)
Where .pura/PURA.md decides which model reviews a PR, reviewer.md tells that model what to focus on. Commit an optional reviewer.md at the root of a repo with plain-English guidance — your conventions, the risks that matter, what to ignore.
It is always read from the repository's default branch, never the PR branch, so a pull request can never rewrite the reviewer's instructions from its own code. The guidance steers focus; it can't override PURA's rules.
An optional YAML frontmatter block adds two extras: pathInstructions for per-path guidance, and crossRepoAllowlist to let the reviewer read named owner/repo repositories beyond the PR's own (the PR repo is always allowed):
---
crossRepoAllowlist:
- acme/shared-lib
pathInstructions:
- path: src/payments/**
instructions: Focus on rounding and currency handling.
---
Review for correctness and security first. Match our
existing patterns; don't suggest large rewrites.Optional. With no reviewer.md, PURA reviews using its built-in guidance. Add the file only when you want reviews tailored to your codebase.
7. Scoping an agent
By default an agent applies to everything in your installed repos. In the dashboard you can scope it so it only kicks in for certain work — matching by simple glob patterns like * or acme/payments-*.
You can scope by any combination of:
- Team (owner) — the team that owns the repository
- Team (contributor) — the team the PR author belongs to
- Repository — one or more repos by name or pattern
- User — the individual who opened the PR
- Pull Request — a specific repo plus one or more PR labels
Each rule is either Allow or Deny. Deny rules are evaluated first; if none match, PURA works through the Allow rules and uses the first one that fits. Allow rules can also carry their own budgets and a routing weight so you can prioritise one agent over another.
Great for multi-team orgs.Give each team their own agent scoped to their repos, with budgets that match their usage — so no single team can eat everyone else's budget.