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

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.

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. In 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.

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. 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 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.

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

# 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.

SDK Integration

Programmatically specify modes per request:

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.

Direct API Usage

Override modes via the REST API using the codebuff_metadata field:

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 and validates against isFreeModeAllowedAgentModel.

Validating Free Mode Eligibility

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

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.

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.
• 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, affecting model selection in gemini-with-fallbacks.ts, credit accounting in sdk/src/run.ts, and payload management in 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 and validated through isFreeModeAllowedAgentModel in 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, 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 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 to prevent unbounded payload generation. Additionally, the credit multiplication factor in 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) 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.

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