Configuration

The .ocra/config.json file and environment variables.

ocra reads .ocra/config.json from the root of the reviewed repository. Every key is optional; unknown keys are rejected, so typos fail loudly.

ocra review --config <file> reads a file of your own instead, from anywhere. Since you trust it, it applies with --no-repo-config too: that is how reviews of untrusted code (the evaluation harness, for example) get declared model endpoints and limits. Plugins it names resolve from its own directory. With --pr and --mr it replaces the base branch's file; plugins still do not load there.

{
  "$schema": "https://raw.githubusercontent.com/jma49/Open-CR-Agent/main/docs/schema/config.v1.json",
  "models": {
    "top": "google/gemini-3.1-pro-preview",
    "standard": ["google/gemini-3.5-flash", "google/gemini-flash-lite-latest"],
    "light": "google/gemini-flash-lite-latest"
  },
  "concurrency": 4,
  "taskTimeoutMinutes": 10,
  "runTimeoutMinutes": 25,
  "verify": true,
  "judge": true,
  "maxCostUsd": 1,
  "include": [],
  "exclude": ["legacy/**"],
  "runtime": "opencode",
  "plugins": [],
  "reviewers": {},
  "pluginSettings": {}
}

$schema points editors at the file's JSON Schema (draft 2020-12, generated from the code and tested against it) for completion and validation; ocra ignores it.

Models

Models are written as provider/model, using OpenCode's provider IDs (for example google, anthropic, openai). Each tier takes one model or a failback chain:

TierUsed for
standardReviewer agents
lightHelper calls such as grouping changed files
topThe judge

When a model is overloaded or rejects a request, the task retries on the next model in the chain. A rate limit with a stated wait of up to 90 seconds pauses that model for every task, then retries; one without a stated wait pauses it for 15 seconds, then 30, then 60. Limits that arrive during a pause, as when tasks running at once are refused together, count as that pause. A daily limit, a longer wait, or a limit after three pauses in a row drops the model for the run. Each model has a circuit breaker: after two failures in a row it is skipped for a minute, then probed with one request; success restores it, failure doubles the pause (up to ten minutes). Credential errors stop at once, since the provider's other models would fail too.

Environment variables override the file, comma-separated for chains:

export OCRA_MODEL_STANDARD="google/gemini-3.5-flash,google/gemini-flash-lite-latest"
export OCRA_MODEL_LIGHT="google/gemini-flash-lite-latest"
export OCRA_MODEL_TOP="google/gemini-3.1-pro-preview"

Models per agent

reviewers.<id>.models gives one reviewer its own model or chain (review tasks and plan call); roles.<role>.models does the same for the verifier, the judge or the helper calls (grouping files, relocating quotes). Same forms as a tier. Without one, an agent uses its tier's chain; the verifier and judge never take a reviewer's, so checking stays independent.

{
  "models": { "standard": "google/gemini-3.5-flash", "top": "google/gemini-3.1-pro-preview" },
  "reviewers": { "security": { "models": ["anthropic/claude-sonnet-5-5", "google/gemini-3.5-flash"] } },
  "roles": { "helper": { "models": "google/gemini-flash-lite-latest" } }
}

Failback, rate-limit pauses and the circuit breaker work per model, so a model in two chains shares one circuit. The pre-review checks cover these chains: the provider's key must be set, a declared provider's model must be priced there, and ocra-<provider>/ models go through ocra Cloud. A plugin runtime that ignores an agent's chain uses the tier's. provenance.agents in the JSON report records each resolved chain, --plan shows each task's, and the configuration hash covers them.

Effort

How much a model reasons before answering: effort sets it per tier, reviewers.<id>.effort per reviewer (review tasks and plan call), roles.<role>.effort for the verifier, judge or helper calls. Levels: none, minimal, low, medium, high. An agent takes its own effort, else its tier's (reviewers by their tier, verifier standard, judge top, helpers light); the verifier and judge never take a reviewer's. Unset sends nothing: the provider's default applies.

{
  "effort": { "standard": "medium", "top": "high" },
  "reviewers": { "security": { "effort": "high" } },
  "roles": { "helper": { "effort": "minimal" } }
}

OCRA_EFFORT_TOP, OCRA_EFFORT_STANDARD and OCRA_EFFORT_LIGHT override a tier's effort.

  • direct sends reasoning_effort, or reasoning: { effort } for a provider declared with "effort": "openrouter" (Model providers); none is sent as none. A call with any other level omits temperature and seed, which reasoning models refuse or override. If the endpoint answers HTTP 400 naming the parameter, the call is retried once without it (not counted as a failure), that model's later calls omit it, and the run warns.
  • opencode sets the level in the model's provider options: reasoningEffort for OpenAI reasoning models (GPT-5, o-series), a thinking budget for Claude 4+ and Gemini 2.5, thinkingLevel for Gemini 3; OpenRouter models and declared providers as their effort says. A thinking budget is a share of the model's output limit in OpenCode's catalog (minimal 1/32, low 1/16, medium 1/4, high 1/2; at least 1,024 tokens for Claude, within Gemini's bounds), or of 32,000 tokens without a limit; none turns thinking off (Claude: no thinking; Gemini 2.5 Flash: budget 0). Each model and level is its own OpenCode variant, so agents sharing a model can differ. Any level but none drops the configured temperature, as on direct. Other providers (Azure, Bedrock, Groq and the like) get no effort.
  • Which levels a model takes comes from a table in ocra (effortCapability in @open-cr-agent/core) that can lag new models: on opencode, a level it does not list for a model (such as minimal for o3 or medium for Gemini 3), or an unknown model, gets no effort, and the run warns once per agent. A review never fails over it. If OpenCode's model catalog cannot be read at start, no level is sent, and the warning gives the cause.
  • provenance.agents in the JSON report lists each agent's tier, effort, applied and notApplied; --plan shows each task's effort; the configuration hash covers it.

Provider keys

Keys come from the environment only, in the variable OpenCode expects (ANTHROPIC_API_KEY, OPENAI_API_KEY; for Google, GEMINI_API_KEY, GOOGLE_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY). Each provider's variables are on Model providers, with how to declare your own endpoint under providers.

The agent runtime receives only PATH, HOME, locale, proxy and CA settings, and the credentials of the providers in your chains (for a provider ocra does not know, every variable starting with its uppercased id, such as GROQ_). Cloud credentials, GITHUB_TOKEN and the rest stay out; list any other variable a provider needs in OCRA_RUNTIME_ENV, comma-separated.

For providers that always need a key (Google, Anthropic, OpenAI, OpenRouter, Groq, Mistral, DeepSeek, xAI, Azure), ocra checks before starting and names a missing variable.

Execution

KeyDefaultMeaning
concurrency4Review tasks running at once (1–32)
taskTimeoutMinutes10Limit for one review task, at most 35791 (about 24.8 days, the longest a timer keeps)
runTimeoutMinutes25Limit for the whole run, at most 35791
maxCostUsdnoneSpend limit for the run: review tasks use up to 80% of it, verification and judging the rest (see --max-cost-usd)
maxTasks60Most review tasks one run starts. Past it, --ultra's second passes go first, then later reviewers, so every file keeps its first reviewer as long as possible; skipped files are reported as not reviewed (exit code 3)
judgetrueMerge, filter and recalibrate findings across reviewers (one top-tier call per run with findings)
verifytrueFact-check findings before reporting them (one standard-tier call per file with findings)
samplingnone{ "temperature": 0–2, "seed": n } for every model call, each optional (unset: the provider's default); --temperature and --seed override it. direct sends both. opencode passes the temperature only to models its catalog says accept one (declared models do) and reports a seed as not applied. provenance.sampling says what was applied. A seed makes runs repeatable only where the provider honors it

A task that fails or times out never fails the run; its files are reported as failed.

git, and what it starts (ssh, credential helpers, proxies), gets only part of ocra's environment, never its model keys or platform tokens: every GIT_* and SSH_* variable, PATH, HOME, XDG_CONFIG_HOME, TMPDIR, the proxy variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY), SSL_CERT_FILE, SSL_CERT_DIR, CURL_CA_BUNDLE, and on Windows the system variables git needs (PATHEXT, SYSTEMROOT, TEMP, USERPROFILE, APPDATA and the like). A fetch also gets what credential helpers read: GH_*, GLAB_*, GITLAB_*, GCM_*, GITHUB_TOKEN and GITHUB_ENTERPRISE_TOKEN. A setup that needs another variable for git (Kerberos, a Nix certificate bundle) can pass it through git's own configuration, such as GIT_SSH_COMMAND or GIT_CONFIG_*.

File selection

ocra skips binary files, likely secrets (.env, keys, certificates, cloud and registry credentials, Terraform variables and state), deleted files, media and archives, lock files, vendored and generated code, and very large diffs. Files over 1 MB are diffed as binary and skipped. A file whose name says text (.ts, .py, …) but that was skipped as binary gets a warning. Range, commit and pull request reviews read .gitattributes from the base commit (git 2.41 or later), so the reviewed change cannot mark its own files binary. Database migrations are never treated as generated code.

  • exclude: globs to skip in addition.
  • include: globs to review even if they would be skipped as generated or by extension. Secrets can never be included.

Reviewers

reviewers.<id> turns a reviewer off, sets the risk tier it starts at, or sets its models or effort. Risk tiers, from lowest: trivial (≤10 changed lines), lite (≤100), full (larger changes, more than 20 files, or a sensitive path: CI workflows, or a directory or file name with a word such as auth, oauth, jwt, password, credential, secret, login, permission, acl, identity, crypto or security).

{ "reviewers": { "correctness": { "minTier": "lite" }, "security": { "enabled": false } } }

Pairs the matrix skips are listed under skipped in the JSON report; a file no reviewer covers shows up as unreviewed in coverage.

Shared configuration

Repositories can extend an organization's common settings:

{ "extends": "https://config.example.com/ocra.json#sha256=<hex>" }

The shared file may set models, concurrency, the timeouts, verify, judge, maxCostUsd, maxTasks, include, exclude, effort, reviewers, roles, github, providers (only when pinned) and rules (shaped like .ocra/rules.json entries). It cannot list plugins or choose a runtime, since it must not run code. The repository's values win; include, exclude and rules combine, and models, effort, reviewers, roles, github and providers merge key by key.

Only https URLs, without redirects, up to 256 KB. #sha256= pins the exact content; a file declaring providers must be pinned, since a provider decides where your code goes (Model providers). If the file cannot be loaded or is invalid, ocra warns and uses the repository's settings alone, so limits set only there (such as maxCostUsd) do not apply; set must-hold limits in the repository too.

Account settings

Signed in to ocra Cloud, ocra review layers your account's settings under the configuration. Highest first: command-line flags, the configuration (the repository's file or --config, what it extends, OCRA_* variables), account settings, ocra's defaults.

Account keyHow it applies
runtime (opencode or direct), models.<tier>, effort.<tier>, reviewers.<id>, roles.<role>Only where the configuration leaves it out; a reviewer's or role's entry in the configuration wins whole
concurrency, taskTimeoutMinutes, runTimeoutMinutes, maxCostUsd, maxTasks, verify, judge, samplingOnly when the configuration does not set it (sampling as one setting): the account can bound an unbounded run, never loosen a limit
includeCombined: the configuration's patterns, then the account's
excludeOnly when the configuration sets none: a file the account excludes is neither reviewed nor counted as unreviewed, so an exclude in the configuration, even [], keeps the account's out
rulesAdded after the repository's and the shared ones: at most 50, each like an .ocra/rules.json entry with a rule of at most 2,000 characters, embedded in the prompt the same way

Each key is checked against this file's schema; one that fails, or that this version does not know, is ignored with a warning naming it, and the rest apply. Models must be ocra-<provider>/<model>, which go through ocra Cloud with the keys stored there. The account can never set providers, extends, github (botLogin decides whose comments are trusted) or plugins: ocra ignores them with a warning.

Account settings apply to --pr and --mr runs too, under the base commit's configuration; they never come from the reviewed tree. What they filled in is printed (From your ocra Cloud settings: …), --plan lists every setting's source, and provenance.accountSettings.version names the version used. The configuration hash covers them and the account's rules, so a signed-out run keeps its hash. If ocra Cloud is unreachable, a warning says so and the configuration applies alone.

Plugins

runtime picks the registered runtime: opencode (default) or direct (Choosing the runtime). plugins lists extra plugins by package name or path; pluginSettings.<plugin-name> holds each one's settings. See Plugins.

Edit on GitHub

On this page