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

> Configure Open Code Review's max-tokens-budget to control LLM token consumption. Understand the token budget system and prevent exceeding limits for efficient code reviews.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go), it accepts a non-negative integer where `0` means unlimited:

```go
// 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:

```bash

# 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`](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/template.go):

```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:

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

```

Example:

```go
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:

```go
// 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`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go)**: Defines the CLI flag and validation logic
- **[`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/internal/scan/agent.go) performs per-file token estimation before dispatching, allowing you to see warnings about potential budget overruns before files are processed.