# Codebuff MAX, FAST, and FREE Modes: Agent Behavior and Performance Implications

> Explore Codebuff MAX FAST and FREE modes Understand how they impact agent behavior and performance Choose the right mode for complex tasks or quick edits to optimize your workflow

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: performance
- Published: 2026-03-09

---

**Codebuff's MAX, FAST (FREE), and DEFAULT modes control which AI models execute requests, how many reasoning steps agents can perform, and whether credits are consumed, with MAX enabling the most capable models for complex tasks while FREE provides zero-cost, limited-capability responses suitable for quick edits.**

Codebuff runs its AI agents—modular building blocks that handle searches, edits, and code reviews—through distinct operational modes defined in the open-source `CodebuffAI/codebuff` repository. These modes, selectable via CLI, web UI, or API parameters, fundamentally alter agent behavior by mapping to specific model tiers, cost accounting methods, and computational budgets in [`cli/src/utils/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/utils/constants.ts).

## How Codebuff Maps Modes to Agent Architectures

The mode selection flows through two critical mapping layers. First, `AGENT_MODE_TO_ID` translates user-facing mode names into internal agent identifiers. Second, `AGENT_MODE_TO_COST_MODE` determines the billing and resource allocation strategy.

| Mode | Agent ID | Cost Mode | Behavioral Impact |
|------|----------|-----------|-------------------|
| **DEFAULT** | `base2` | `normal` | Balanced capability using standard models with moderate step budgets and standard credit costs. |
| **MAX** | `base2-max` | `max` | Activates highest-capability models (e.g., GPT-5-Codex or Gemini Pro), removes per-step limits, and incurs premium credit costs. |
| **FREE** | `base2-free` | `free` | Restricts execution to whitelisted agents and models defined in `FREE_MODE_AGENT_MODELS`, uses lightweight flash models, and consumes zero credits. |
| **PLAN** | `base2-plan` | `normal` | Enterprise tier matching DEFAULT performance but unlocking additional UI features for subscribed users. |

### Model Selection Logic

The `costMode` parameter propagates through the LLM API layer in [`web/src/llm-api/helpers.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/llm-api/helpers.ts). In [`packages/agent-runtime/src/llm-api/gemini-with-fallbacks.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/llm-api/gemini-with-fallbacks.ts), a `max` cost mode forces selection of high-quality fallback models, while `free` mode restricts calls to models explicitly listed in [`common/src/constants/free-agents.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/free-agents.ts).

## Performance and Behavioral Implications

### Reasoning Depth and Step Budgets

Agents such as file pickers and research modules reference `MAX_AGENT_STEPS_DEFAULT` from [`common/src/constants/agents.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/agents.ts). When running in **MAX** mode, the step budget increases significantly, allowing deeper tool-chaining and exhaustive file-tree traversals. **FREE** mode enforces tighter step limits to ensure rapid completion.

### Credit Accounting and Cost Structure

The SDK layer in [`sdk/src/run.ts`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/run.ts) records the `costMode` and forwards it to the billing service. **FREE** mode maps to zero credit deduction for allow-listed agents, while **MAX** mode multiplies the per-token cost according to pricing matrices in [`common/src/constants/model-config.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/model-config.ts).

### Latency and Payload Management

**MAX** mode introduces higher latency due to larger model inference times and increased token generation. The system protects against runaway responses using `MAX_BUFFER_SIZE` defined in [`web/src/llm-api/openrouter.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/llm-api/openrouter.ts). Conversely, **FREE** mode—often referred to as "FAST" by users—completes quickest by utilizing minimal-capability flash models and constrained step limits.

## Implementing Mode Selection in Practice

### CLI Configuration

Set modes globally via the command line interface:

```bash

# Configure MAX mode for deep analysis

codebuff mode set MAX

# Verify current configuration

codebuff mode get

```

These commands write to local configuration files, with mode constants defined in [`cli/src/utils/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/utils/constants.ts).

### SDK Integration

Programmatically specify modes per request:

```typescript
import { sendMessage } from '@codebuff/sdk';

await sendMessage({
  content: 'Refactor the authentication module',
  agentMode: 'MAX', // 'FREE' or 'DEFAULT' also valid
});

```

The SDK injects `costMode: AGENT_MODE_TO_COST_MODE[agentMode]` before calling the LLM API, as implemented in [`cli/src/hooks/use-send-message.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/hooks/use-send-message.ts).

### Direct API Usage

Override modes via the REST API using the `codebuff_metadata` field:

```http
POST https://codebuff.com/api/v1/chat/completions
Content-Type: application/json

{
  "messages": [{ "role": "user", "content": "Explain the routing logic" }],
  "model": "gpt-4o-mini",
  "codebuff_metadata": {
    "cost_mode": "free"
  }
}

```

The server extracts `cost_mode` in [`web/src/llm-api/helpers.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/llm-api/helpers.ts) and validates against `isFreeModeAllowedAgentModel`.

### Validating Free Mode Eligibility

Check programmatically whether an agent-model combination qualifies for zero-cost execution:

```typescript
import { isFreeModeAllowedAgentModel } from '@codebuff/common/constants/free-agents';

const canRunFree = isFreeModeAllowedAgentModel(
  'codebuff/base2-free', 
  'minimax/minimax-m2.5'
);

```

Only combinations listed in `FREE_MODE_AGENT_MODELS` return `true`, enforcing the whitelist defined in [`common/src/constants/free-agents.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/free-agents.ts).

## Strategic Mode Selection

Choose modes based on task complexity and budget constraints:

- **FREE (FAST)**: Ideal for quick code reviews, syntax fixes, or tiny edits where instant response outweighs reasoning depth. Zero credit consumption but limited to simple agents.
- **DEFAULT**: The standard choice for daily development work, balancing cost, speed, and output quality using `base2` agents with `normal` cost mode.
- **MAX**: Essential for complex refactoring, multi-file architectural analysis, or research-heavy tasks requiring the capabilities of `base2-max` agents and premium models like those in [`agents-graveyard/thinker/gpt5-thinker.ts`](https://github.com/CodebuffAI/codebuff/blob/main/agents-graveyard/thinker/gpt5-thinker.ts).
- **PLAN**: Enterprise users requiring DEFAULT-level performance with additional feature unlocks and administrative controls.

## Summary

- **MAX mode** activates `base2-max` agents with premium models (GPT-5-Codex/Gemini Pro), unlimited step budgets, and multiplied credit costs, delivering deepest reasoning but highest latency.
- **FREE mode** (often called "fast") restricts execution to whitelisted agents in `FREE_MODE_AGENT_MODELS`, uses lightweight flash models, enforces strict step limits, and consumes zero credits for rapid, simple tasks.
- **DEFAULT mode** provides balanced performance through `base2` agents with standard models and moderate step budgets, serving as the optimal daily driver.
- Mode selection propagates through `AGENT_MODE_TO_COST_MODE` mappings in [`cli/src/utils/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/utils/constants.ts), affecting model selection in [`gemini-with-fallbacks.ts`](https://github.com/CodebuffAI/codebuff/blob/main/gemini-with-fallbacks.ts), credit accounting in [`sdk/src/run.ts`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/run.ts), and payload management in [`openrouter.ts`](https://github.com/CodebuffAI/codebuff/blob/main/openrouter.ts).

## Frequently Asked Questions

### What is the difference between FREE mode and FAST mode in Codebuff?

**FREE mode and FAST mode refer to the same zero-credit configuration.** Users often colloquially call it "fast" because it uses lightweight flash models and tight step limits to minimize latency. Technically, the system recognizes `base2-free` agents with `cost_mode: 'free'`, defined in [`cli/src/utils/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/utils/constants.ts) and validated through `isFreeModeAllowedAgentModel` in [`common/src/constants/free-agents.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/free-agents.ts).

### Does MAX mode always use GPT-5 or can it fall back to other models?

**MAX mode prioritizes the most capable available models but implements fallback logic.** According to [`packages/agent-runtime/src/llm-api/gemini-with-fallbacks.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/llm-api/gemini-with-fallbacks.ts), when `costMode` is set to `max`, the runtime attempts to use highest-quality models like GPT-5-Codex or Gemini Pro. However, the specific model depends on availability and the agent implementation—[`agents-graveyard/thinker/gpt5-thinker.ts`](https://github.com/CodebuffAI/codebuff/blob/main/agents-graveyard/thinker/gpt5-thinker.ts) represents the MAX-level thinker agent, while standard thinker implementations use default tiers.

### How does Codebuff prevent runaway costs in MAX mode?

**The system implements buffer limits and step constraints.** While MAX mode increases `MAX_AGENT_STEPS_DEFAULT` for deeper reasoning, it utilizes `MAX_BUFFER_SIZE` in [`web/src/llm-api/openrouter.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/llm-api/openrouter.ts) to prevent unbounded payload generation. Additionally, the credit multiplication factor in [`common/src/constants/model-config.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/model-config.ts) ensures costs scale predictably with token consumption.

### Can I switch modes mid-conversation or per individual request?

**Yes, modes can be set per request via SDK or API, or globally via CLI.** The `agentMode` parameter in `sendMessage` SDK calls (processed in [`sdk/src/run.ts`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/run.ts)) allows single-request overrides, while `codebuff mode set` persists preferences locally. The web UI and REST API accept `cost_mode` in `codebuff_metadata` for immediate session-specific changes without affecting global configuration.