How to Use Bifrost CLI with Coding Agents like Claude Code

The Bifrost CLI wires up coding agents like Claude Code to your Bifrost AI gateway in a single command. Rather than hand-configuring base URLs, shuffling API keys between providers, and tweaking config files for each agent, you just run bifrost in your terminal, pick the agent, pick the model, and get to work. This walkthrough covers how to use the Bifrost CLI with Claude Code and the other supported coding agents, starting from gateway setup and moving into workflows like tabbed sessions, git worktrees, and automatic MCP attach.

Coding agents are now deeply embedded in how engineering teams ship. Anthropic notes that the majority of code at Anthropic is now written by Claude Code, with engineers spending more of their time on architecture, review, and agent orchestration. But as teams layer in multiple agents (Claude Code for heavy refactors, Codex CLI for quick edits, Gemini CLI for model-specific work), the per-agent configuration burden starts to stack up fast. The Bifrost CLI folds all of that into one launcher.

What the Bifrost CLI Actually Does

Think of the Bifrost CLI as an interactive terminal launcher for any supported coding agent, routed through your Bifrost gateway. It takes care of provider config, model selection, API key injection, and MCP auto-attach so you do not have to. Bifrost itself is the open-source AI gateway built by Maxim AI, exposing 20+ LLM providers behind a single OpenAI-compatible API with roughly 11 microseconds of overhead at 5,000 RPS.

Out of the box, the CLI supports four coding agents:

• Claude Code (binary: claude, provider path: /anthropic), including MCP auto-attach and git worktree support
• Codex CLI (binary: codex, provider path: /openai), with OPENAI_BASE_URL pointed at {base}/openai/v1 and model overrides via --model
• Gemini CLI (binary: gemini, provider path: /genai), with model overrides via --model
• Opencode (binary: opencode, provider path: /openai), with custom models wired through a generated Opencode runtime config

Per-agent specifics live in the CLI agents reference.

Why Route Coding Agents Through Bifrost at All

Pushing Claude Code and other coding agents through Bifrost unlocks three concrete wins for engineering teams: one unified model catalog, centralized governance across coding agent spend, and shared MCP tool configuration. Instead of every engineer wiring up API keys inside their personal agent setup, and every agent having its own tool list, Bifrost acts as a single control plane for all of it.

One catalog, every model

Claude Code ships configured for Claude Opus and Sonnet out of the box, but teams often want room to choose. Some tasks map better to GPT-4o, some to Gemini, some to a local model for speed or cost. When you launch Claude Code via the Bifrost CLI, it hits Bifrost's OpenAI-compatible API instead of Anthropic directly, which means any of Bifrost's 20+ supported providers (OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, Azure OpenAI, Gemini, Groq, Mistral, Cohere, Cerebras, Ollama, and more) can sit behind your coding agent. Bifrost's drop-in replacement design is what makes this seamless: the agent believes it is talking to OpenAI or Anthropic, and Bifrost silently handles routing.

Budgets, rate limits, and spend attribution

Coding agents eat tokens. A single multi-file refactor in Claude Code can chew through hundreds of thousands of tokens, and the cost scales linearly as your team grows. Bifrost governance treats virtual keys as the core governance primitive, so you can attach per-engineer or per-team budgets, rate limits, and model-access rules to them. Senior engineers might get the expensive reasoning models; juniors default to cost-efficient ones. Every request is attributed, every dollar is visible on the dashboard, and budgets are enforced at the virtual-key level. The enterprise governance resource page goes deeper on the full model for larger engineering orgs.

One MCP config, every agent

Coding agents get much more useful once they can hit MCP tools (filesystem, databases, GitHub, docs lookup, internal APIs). But configuring MCP servers one-by-one for each agent, across every engineer's machine, is genuinely miserable. Bifrost's MCP gateway centralizes the whole thing. When the Bifrost CLI fires up Claude Code, it auto-attaches Bifrost's MCP endpoint so every tool configured in Bifrost shows up inside the agent immediately, without any claude mcp add-json calls or hand-edited JSON. This matters a lot if you are standardizing on MCP for internal tooling. We dug into the token-cost side of this in our post on Bifrost MCP Gateway access control, cost governance, and 92% lower token costs at scale.

Prereq: a Running Bifrost Gateway

The Bifrost CLI needs a Bifrost gateway to talk to. If you do not already have one running, the gateway starts with zero config:

npx -y @maximhq/bifrost

Default gateway address is http://localhost:8080. Open that URL in your browser to add providers through the web UI, set up virtual keys, and flip on features like semantic caching or observability. Prefer Docker?

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

The -v $(pwd)/data:/app/data mount keeps your configuration alive across container restarts. If you need more control (custom ports, log levels, file-based configuration, PostgreSQL-backed persistence), the gateway setup guide documents every flag and mode.

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

Installing and Running the Bifrost CLI

Requirements: Node.js 18+. Install via npx:

npx -y @maximhq/bifrost-cli

After the first run, the bifrost binary is available on your PATH:

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 you through five steps:

1. Base URL: Enter your Bifrost gateway URL (usually http://localhost:8080 for local dev)
2. Virtual Key (optional): If virtual key authentication is on, drop in your key here. Virtual keys land in your OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service), never in plaintext on disk
3. Choose a Harness: Pick Claude Code from the list. The CLI shows install state and version, and if Claude Code is not installed, it offers to install it via npm for you
4. Select a Model: The CLI pulls available models from your gateway's /v1/models endpoint and shows a searchable list. Type to filter, arrow keys to navigate, or just type any model identifier manually (for example, anthropic/claude-sonnet-4-5-20250929)
5. Launch: Look over the configuration summary, hit Enter

The CLI sets every required environment variable, applies provider-specific configuration, and launches Claude Code in the same terminal. From there you are using Claude Code normally, with every request routed through Bifrost.

Automatic MCP attach for Claude Code

Launching Claude Code through the Bifrost CLI auto-registers Bifrost's MCP endpoint at /mcp, so every MCP tool you have configured in Bifrost is instantly available inside Claude Code. If a virtual key is set, the CLI also wires up authenticated MCP access with the right Authorization header. No manual claude mcp add-json commands. For the other harnesses (Codex CLI, Gemini CLI, Opencode), the CLI prints the MCP server URL so you can plug it into the agent's own settings.

Tabbed Session UI

Once you launch, the Bifrost CLI drops you into a tabbed terminal UI rather than exiting after your session ends. A tab bar at the bottom shows the CLI version, one tab per active or recent agent session, and a status badge per tab:

• 🧠 means the session is still changing (the agent is working)
• ✅ means the session looks idle and ready
• 🔔 means the session emitted a real terminal alert

Hit Ctrl+B any time to focus the tab bar. From tab mode:

• n opens a new tab and launches another agent session
• x closes the current tab
• h / l jump left and right across tabs
• 1-9 jump directly to a tab by number
• Esc / Enter / Ctrl+B drop you back into the active session

Super handy when you want Claude Code on one task and Gemini CLI on another, or multiple parallel Claude Code sessions against different branches.

Git Worktree Support for Claude Code

Worktree support is currently Claude Code only. It lets you run sessions in isolated git worktrees for parallel development:

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

You can also choose worktree mode from inside the TUI during setup. The CLI forwards the --worktree flag to Claude Code, which creates a fresh working directory on that branch. This is exactly what you want when you need two Claude Code agents running side by side, one on main and one on a feature branch, without stepping on each other.

Configuration and CLI Flags

The Bifrost CLI persists 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 stay in your OS keyring.

CLI flags worth knowing:

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

From the summary screen, shortcut keys let you tweak things without restarting:

• u changes the base URL
• v updates the virtual key
• h swaps 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

Swapping Between Coding Agents

This is where the Bifrost CLI earns its keep. When a Claude Code session ends, you land back on the summary screen with your previous config intact. Press h to swap Claude Code for Codex CLI, press m to try GPT-4o instead of Claude Sonnet, then hit Enter to re-launch. The CLI redoes everything (base URLs, API keys, model flags, agent-specific config) for you.

Opencode gets two extra behaviors: the CLI generates a provider-qualified model reference plus a runtime config so Opencode boots with the right model, and it preserves your existing theme from tui.json or falls back to the adaptive system theme if you have not set one.

Workflows You Actually See in the Wild

A few patterns that tend to show up on teams running coding agents via Bifrost:

• Head-to-head agent comparison: Open a tab, launch Claude Code on a task. Open another, launch Codex CLI on the same task. Compare outputs. Every request runs through Bifrost, so everything gets logged against the same virtual key
• Worktree-based parallel work: One engineer runs Claude Code on a bug fix in one worktree and Claude Code on a feature in another, with both sessions in view via the tabbed UI
• Model switching per task: Claude Opus for big architectural refactors, Gemini for documentation-heavy work, a local Ollama model for quick edits. No leaving the CLI, no reconfiguring anything
• Shared MCP tools across a team: Platform engineers configure MCP servers once in the Bifrost dashboard (filesystem, internal APIs, databases), and every engineer's Claude Code session picks those tools up automatically

Troubleshooting Cheat Sheet

A few common gotchas:

• "npm not found in path": The CLI uses npm to install missing harnesses. Confirm Node.js 18+ is installed and npm --version works
• Agent not found after install: Restart your terminal or add npm's global bin directory to your PATH with export PATH="$(npm config get prefix)/bin:$PATH"
• Models not loading: Check that your Bifrost gateway is reachable at the configured base URL, at least one provider is set up, and (if virtual keys are on) your key has permission to list models
• Virtual key not persisting: The CLI writes virtual keys to your OS keyring. On Linux, make sure gnome-keyring or kwallet is running. If keyring access fails, the CLI logs a warning and keeps going, but you will need to re-enter the key each session

Wrapping Up

The Bifrost CLI makes every coding agent a first-class citizen of your AI gateway. Engineers stop wrestling env vars and per-agent config files; platform teams get centralized governance, observability, and MCP tool management across every agent in play. Claude Code, Codex CLI, Gemini CLI, and Opencode all launch through one CLI, behind one set of credentials, with one dashboard watching them.

Ready to try it? Spin up a gateway with npx -y @maximhq/bifrost, grab the CLI with npx -y @maximhq/bifrost-cli, and walk through the setup. For teams thinking about production coding agent workflows at scale, book a demo with the Bifrost team to see how the MCP gateway, governance layer, and CLI all come together.