AI Gateway

How to Use Bifrost CLI with Coding Agents like Claude Code

Launch Claude Code, Codex CLI, Gemini CLI, and Opencode through a single Bifrost CLI command. Zero environment variables, automatic MCP integration, unified model access.

The Bifrost CLI connects coding agents like Claude Code to your Bifrost AI gateway with one command. Instead of manually configuring base URLs, juggling API keys across providers, and editing agent-specific config files, engineers run bifrost in their terminal, pick an agent, pick a model, and start working. This guide walks through how to use the Bifrost CLI with Claude Code and other coding agents, from initial gateway setup to advanced workflows like tabbed sessions, git worktrees, and automatic MCP integration.

Coding agents have become a core part of how engineering teams ship software. Anthropic states that the majority of code at Anthropic is now written by Claude Code, with engineers shifting their focus toward architecture, review, and orchestration. As more agents enter a team's workflow (Claude Code for deep refactors, Codex CLI for quick tasks, Gemini CLI for specific models), the configuration overhead compounds. The Bifrost CLI collapses that overhead into a single launcher.

What is the Bifrost CLI

The Bifrost CLI is an interactive terminal tool that launches any supported coding agent through your Bifrost gateway. It handles provider configuration, model selection, API key injection, and MCP auto-attach automatically. Bifrost is the open-source AI gateway by Maxim AI that unifies access to 20+ LLM providers through a single OpenAI-compatible API with only 11 microseconds of overhead at 5,000 requests per second.

The CLI currently supports four coding agents out of the box:

Claude Code (binary: claude, provider path: /anthropic), with automatic MCP attach and git worktree support
Codex CLI (binary: codex, provider path: /openai), with OPENAI_BASE_URL set to {base}/openai/v1 and model override via -model
Gemini CLI (binary: gemini, provider path: /genai), with model override via -model
Opencode (binary: opencode, provider path: /openai), with custom models configured through a generated Opencode runtime config

Full integration details for each agent are in the CLI agents documentation.

Why Route Coding Agents Through Bifrost

Routing Claude Code and other coding agents through Bifrost gives engineering teams three immediate benefits: unified model access across providers, centralized governance for coding agent spend, and shared MCP tool configuration. Instead of each engineer wiring their own API keys into their agent and each agent having its own tool setup, Bifrost becomes the single control plane.

Unified access to every model

Claude Code runs on Claude Opus and Sonnet by default, but teams often want flexibility. Some tasks are better suited to OpenAI's GPT-4o or Google's Gemini for specific languages, specific frameworks, or cost reasons. When you launch Claude Code through the Bifrost CLI, it uses Bifrost's OpenAI-compatible API, which means any of the 20+ providers Bifrost supports (OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, Azure OpenAI, Gemini, Groq, Mistral, Cohere, Cerebras, Ollama, and more) can back your coding agent. Bifrost's drop-in replacement architecture is what makes this possible: the agent thinks it is calling OpenAI or Anthropic directly, while Bifrost handles the routing underneath.

Governance and cost control

Coding agents consume serious token budgets. A single multi-file refactor in Claude Code can burn through hundreds of thousands of tokens, and usage scales linearly with team size. Bifrost governance uses virtual keys as the primary governance entity, letting you assign per-engineer or per-team budgets, rate limits, and model access permissions. A senior engineer can have access to expensive reasoning models, while a junior engineer is routed to cost-efficient models by default. All spend is attributed, visible in dashboards, and capped by virtual key budgets. The enterprise governance resource page covers the full governance model for large engineering organizations.

Shared MCP tool access

Every coding agent benefits from MCP tools (filesystem access, database queries, GitHub integration, documentation lookup, internal APIs), but configuring MCP servers per-agent per-engineer is painful. Bifrost's MCP gateway centralizes MCP server configuration. When the Bifrost CLI launches Claude Code, it auto-attaches Bifrost's MCP endpoint so every tool you have configured in Bifrost is immediately available inside the agent, without running claude mcp add-json commands or editing JSON config files. This is especially valuable for teams standardizing on MCP for internal tools and data access. For more on how this compounds into token savings, see our post on Bifrost MCP Gateway access control, cost governance, and 92% lower token costs.

Prerequisites: Running a Bifrost Gateway

The Bifrost CLI requires a running Bifrost gateway. If you do not have one, the gateway starts with zero configuration:

npx -y @maximhq/bifrost

The gateway starts at http://localhost:8080 by default. Open that URL in your browser to add providers through the web UI, configure virtual keys, and enable features like semantic caching or observability. Alternatively, run Bifrost in Docker:

docker pull maximhq/bifrost
docker run -p 8080:8080 -v $(pwd)/data:/app/data maximhq/bifrost

The -v $(pwd)/data:/app/data mount persists configuration across container restarts. For deeper setup options (custom ports, log levels, file-based configuration, PostgreSQL-backed persistence), the gateway setup guide walks through every flag and mode.

Once the gateway is running and at least one provider is configured, you can launch the CLI.

Installing and Running the Bifrost CLI

The Bifrost CLI requires Node.js 18+ and is installed via npx:

npx -y @maximhq/bifrost-cli

After the first run, the bifrost binary is available directly:

bifrost

To pin a specific CLI version:

npx -y @maximhq/bifrost-cli --cli-version v1.0.0

Launching Claude Code Through the Bifrost CLI

Running bifrost opens an interactive TUI that walks through five setup steps:

Base URL: Enter your Bifrost gateway URL (typically http://localhost:8080 for local development)
Virtual Key (optional): If your gateway has virtual key authentication enabled, enter your key. Virtual keys are stored in your OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service), never in plaintext on disk
Choose a Harness: Select Claude Code from the list. The CLI shows install status and version. If Claude Code is not installed, the CLI offers to install it via npm automatically
Select a Model: The CLI fetches available models from your gateway's /v1/models endpoint and presents a searchable list. You can type to filter, use arrow keys to navigate, or type any model identifier manually (for example, anthropic/claude-sonnet-4-5-20250929)
Launch: Review the configuration summary and press Enter

The CLI sets all required environment variables, applies provider-specific configuration, and launches Claude Code in the same terminal session. You are then working inside Claude Code as normal, with every request routed through Bifrost.

Automatic MCP attach for Claude Code

When Claude Code launches through the Bifrost CLI, the CLI automatically registers Bifrost's MCP endpoint at /mcp so all your configured MCP tools are available inside Claude Code. If a virtual key is configured, the CLI sets up authenticated MCP access with the correct Authorization header. No manual claude mcp add-json commands are required. For other harnesses (Codex CLI, Gemini CLI, Opencode), the CLI prints the MCP server URL so you can configure it manually in the agent's settings.

The Tabbed Session UI

After launch, the Bifrost CLI keeps you inside a tabbed terminal UI instead of exiting at the end of a session. A tab bar at the bottom shows the CLI version, one tab per running or recent agent session, and a status badge per tab:

🧠 indicates the session is actively changing (the agent is working)
✅ indicates the session is idle and ready
🔔 indicates the session emitted a real terminal alert

Press Ctrl+B at any time to focus the tab bar. From there:

n opens a new tab and launches another agent session
x closes the current tab
h / l move left or right across tabs
19 jump directly to a tab by number
Esc / Enter / Ctrl+B return to the active session

This is especially useful when switching between Claude Code for one task and Gemini CLI for another, or running parallel Claude Code sessions against different branches.

Git Worktree Support for Claude Code

Worktree support is available for Claude Code, letting you run sessions in isolated git worktrees for parallel development:

npx -y @maximhq/bifrost-cli -worktree feature-branch

You can also select worktree mode from the TUI during setup. The CLI passes the --worktree flag to Claude Code, which creates a new working directory with the specified branch. This enables workflows like running two Claude Code agents simultaneously, one on main and one on a feature branch, without conflicts.

Configuration and CLI Flags

The Bifrost CLI stores its configuration at ~/.bifrost/config.json, created on first run and updated through the TUI:

{
  "base_url": "<http://localhost:8080>",
  "default_harness": "claude",
  "default_model": "anthropic/claude-sonnet-4-5-20250929"
}

Virtual keys are never written to this file. They live in your OS keyring.

Available CLI flags:

config <path>: Path to a custom config.json file (useful for per-project gateway configurations)
no-resume: Skip resume flow and open fresh setup
worktree <n>: Create a git worktree for the session (Claude Code only)

Shortcut keys from the summary screen let you change settings without restarting:

u changes the base URL
v updates the virtual key
h switches to a different harness
m picks a different model
w sets a worktree name (Claude Code only)
d opens the Bifrost dashboard in your browser
l toggles harness exit logs

Switching Between Coding Agents

The real power of the Bifrost CLI is how quickly you can swap between agents. After a Claude Code session ends, you return to the summary screen with your previous configuration intact. Press h to switch from Claude Code to Codex CLI, press m to try GPT-4o instead of Claude Sonnet, and press Enter to re-launch. The CLI reconfigures everything (base URLs, API keys, model flags, agent-specific setup) automatically.

For Opencode specifically, the CLI applies two additional behaviors: it generates a provider-qualified model reference and a runtime config so Opencode launches with the correct model, and it preserves your existing theme from tui.json or supplies the adaptive system theme if none is defined.

Real-World Workflows

A few patterns that teams using the Bifrost CLI with coding agents adopt:

Multi-agent comparison: Engineer opens a new tab, launches Claude Code on a task, opens a second tab, launches Codex CLI on the same task, and compares outputs side by side. All traffic flows through Bifrost, so every request is logged and attributed to the same virtual key
Worktree-based parallel development: A single engineer runs Claude Code on a bug fix in one worktree and Claude Code on a feature in another, with both sessions visible in the tabbed UI
Model flexibility per task: Use Claude Opus for complex architectural refactors, switch to Gemini for documentation-heavy tasks, switch to a local Ollama model for quick edits. All without leaving the Bifrost CLI or reconfiguring anything
Shared MCP tools across a team: Platform engineers configure MCP servers once in the Bifrost dashboard (filesystem access, internal API access, database tools), and every engineer's Claude Code session inherits those tools automatically

Troubleshooting Common Issues

A few issues come up frequently:

"npm not found in path": The CLI uses npm to install missing harnesses. Ensure Node.js 18+ is installed and npm --version resolves
Agent not found after install: Restart your terminal or add npm's global bin directory to your PATH using export PATH="$(npm config get prefix)/bin:$PATH"
Models not loading: Verify your Bifrost gateway is reachable at the configured base URL, at least one provider is configured, and if virtual keys are enabled, your key has permission to list models
Virtual key not persisting: The CLI stores virtual keys in your OS keyring. On Linux, ensure gnome-keyring or kwallet is running. If keyring access fails, the CLI logs a warning and continues, but the key needs to be re-entered each session

Getting Started with Bifrost CLI for Coding Agents

The Bifrost CLI turns every coding agent into a first-class citizen of your AI gateway. Engineers stop fighting environment variables and per-agent configuration files; platform teams get centralized governance, observability, and MCP tool management across every agent their team uses. Claude Code, Codex CLI, Gemini CLI, and Opencode all run through one launcher, one set of credentials, and one dashboard.

To start using the Bifrost CLI with Claude Code or any other supported coding agent, spin up a gateway with npx -y @maximhq/bifrost, install the CLI with npx -y @maximhq/bifrost-cli, and walk through the setup. For teams evaluating Bifrost for production coding agent workflows, book a demo with the Bifrost team to see how the MCP gateway, governance, and CLI work together at scale.