Open Code Review Token Budget System: How to Configure max-tokens-budget

Open Code Review caps the total LLM tokens (input + output) consumed during a review via the max-tokens-budget parameter, halting further file processing when the limit is exceeded while preserving partial results and marking skipped files as failed(budget).

The token budget system in Alibaba's Open Code Review provides a hard cost constraint for AI-powered code reviews. By configuring the max-tokens-budget parameter, you can prevent runaway token consumption while ensuring you still receive review comments for files processed before reaching the limit.

What Is the Token Budget System?

The token budget system aggregates all LLM request tokens—both prompt (input) and completion (output)—across the entire review run. When the aggregate token budget is reached, the dispatch loop immediately halts. Any remaining files that would exceed the budget are skipped and recorded with the failure class budget (session.FailureBudget).

Key characteristics:

• Default value: 0 indicates unlimited budget (no enforcement)
• Exit behavior: Returns exit code 0 if at least one file was successfully reviewed; returns non-zero only if all selected items failed
• Partial results: Comments collected up to the budget limit are still published
• Visibility: The CLI prints warnings such as [ocr] token budget reached … when the limit is hit

How to Configure max-tokens-budget

You can set the token budget through three methods.

Command-Line Flag (--max-tokens-budget)

The --max-tokens-budget flag is available for both ocr review and ocr scan commands. Defined in cmd/opencodereview/shared_flags.go, it accepts a non-negative integer where 0 means unlimited:

// src: https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go#L44-L48
cmd.Flags().IntVar(maxTokensBudget,
    "max-tokens-budget", 0,
    "cap total token usage (input+output) for this review; dispatch stops once exceeded and skipped files are reported as failed(budget). Partial results are published and review exits 0; it exits non‑zero only if every selected item failed (0 = unlimited)")

Example usage:

# Limit review to 500,000 tokens

ocr review --max-tokens-budget 500000

# Scan with 1M token cap

ocr scan --max-tokens-budget 1000000

Template Configuration (MAX_TOKENS_BUDGET)

For template-based reviews, set the MAX_TOKENS_BUDGET field in your review template JSON. This field is defined in the Template struct in internal/config/template/template.go:

// src: https://github.com/alibaba/open-code-review/blob/main/internal/config/template/template.go#L40
MaxTokensBudget int64 `json:"MAX_TOKENS_BUDGET,omitempty"`

Programmatic API (Args Struct)

When using the Go library directly, assign the value to the MaxTokensBudget field in the Args struct:

// src: https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go#L134-L138
type Args struct {
    // …
    MaxTokensBudget int64 // 0 = unlimited
}

Example:

package main

import (
    "context"
    "github.com/alibaba/open-code-review/internal/agent"
)

func main() {
    args := &agent.Args{
        MaxTokensBudget: 300_000,
        // other fields omitted for brevity …
    }

    ag := agent.New(args)
    ag.Run(context.Background())
}

Validation Rules

Both the review and scan commands validate that the budget is non-negative. Negative values are rejected with an error message:

// src: https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go#L25-L27
if opts.maxTokensBudget < 0 {
    return fmt.Errorf("--max-tokens-budget must be a non‑negative integer (0 means unlimited)")
}

Implementation Details: Where the Budget Is Enforced

The token budget is enforced at multiple layers in the source code:

• cmd/opencodereview/shared_flags.go: Defines the CLI flag and validation logic
• internal/agent/agent.go: The core review driver prints the configured budget, compares estimates against the limit, and implements BudgetExceeded() to signal when processing should stop
• internal/scan/agent.go: Performs per-file token budget look-ahead, checking each file's estimated token cost before acquiring a semaphore and emitting warnings when the budget would be exceeded

Summary

• The token budget system caps total LLM token usage (input + output) across the entire review run in Open Code Review
• Set the budget via CLI flag (--max-tokens-budget), template JSON (MAX_TOKENS_BUDGET), or Go API (Args.MaxTokensBudget)
• When the budget is reached, remaining files are marked as failed(budget) and the review exits with code 0 if any files were successfully processed
• The default value of 0 means unlimited tokens; negative values are rejected by validation logic in shared_flags.go

Frequently Asked Questions

What happens when the token budget is exceeded during a review?

When the aggregate token count reaches the configured limit, Open Code Review immediately stops dispatching new file subtasks. Files that cannot be processed are skipped and marked with the failure class budget (session.FailureBudget). The review still publishes all comments collected up to that point and exits with status 0 (success) unless every selected item failed.

Can I set different token budgets for different review commands?

Yes. The --max-tokens-budget flag works independently for both ocr review and ocr scan commands. You can specify different values for each command invocation, or set a default via template configuration for consistent limits across runs.

Why does my review exit with code 0 even when the budget was exceeded?

Open Code Review treats a budget overrun as a controlled halt rather than a failure. As long as at least one file was successfully reviewed before hitting the limit, the exit code is 0 to indicate that partial results are available. The exit code becomes non-zero only when all selected items fail for any reason (including budget constraints).

Is there a way to estimate token usage before running the review?

The CLI prints the configured budget and emits a warning if the upfront estimate already exceeds the budget. Additionally, internal/scan/agent.go performs per-file token estimation before dispatching, allowing you to see warnings about potential budget overruns before files are processed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}