Claude Code

Claude Code can use Bifrost through the Brokk agent plugin or through a manual MCP server entry. The plugin path is preferred because it registers the Bifrost MCP server, provides a launcher that resolves the Bifrost binary, and adds skills and subagents.

The plugin installs:

• the bifrost MCP server with the symbol|extended toolsets;
• four skills: bifrost-code-navigation, bifrost-code-reading, bifrost-codebase-search, and bifrost-policy-checking;
• eight subagents: architect-reviewer, devops-reviewer, dry-reviewer, issue-diagnostician, issue-enhancer, issue-planner, security-reviewer, and senior-dev-reviewer.

Packaged agent plugin describes each skill and subagent.

Authenticate Claude Code

Claude Code authentication is separate from the Claude desktop app. Before validating Bifrost, run:

claude auth login
claude auth status

The status must report loggedIn: true. If Claude’s OAuth page says that the current account cannot use Claude Code, use a supported subscription or an Anthropic API key. Selecting Haiku or Sonnet in a Free desktop-app session does not authenticate the Claude Code CLI.

Plugin Install

Add the Brokk marketplace from GitHub, then install Bifrost:

claude plugin marketplace add BrokkAi/bifrost --sparse .claude-plugin plugins
claude plugin install bifrost@brokk
claude plugin list
claude mcp list

Releases that used the legacy brokk@bifrost coordinate inverted the project and owner names. Migrate an existing installation once before using the commands above, preserving the scope used for the old install:

claude plugin uninstall brokk@bifrost --scope user
claude plugin marketplace remove bifrost

Start a fresh Claude Code session after installing the plugin so the MCP server configuration is loaded at startup.

To upgrade the user-scoped installation created above to the latest published Bifrost plugin, refresh its marketplace metadata and update the installed package:

claude plugin marketplace update brokk
claude plugin update bifrost@brokk --scope user
claude plugin list
claude mcp list

Then run /reload-plugins or exit and start a fresh Claude Code session. If the plugin was installed with another scope, pass that original scope to claude plugin update instead.

The plugin automatically registers its packaged MCP server, so do not add a duplicate manual MCP entry. Without an explicit BIFROST_WORKSPACE_ROOT or launcher --root, the MCP server requests the host-approved project directory through MCP roots and never uses the installed plugin directory as analyzer scope.

claude plugin list should show bifrost@brokk enabled. claude mcp list should show plugin:bifrost:bifrost connected. If it reports posix_spawn './bin/bifrost-launcher.mjs', an old cached copy of the plugin is installed. Run the upgrade commands above, then reload plugins or start a fresh session. Claude caches installed plugin contents by version, so refreshing the marketplace alone does not replace a cached copy.

Claude Code defers MCP tool schemas until it needs them. It initially uses Bifrost’s tool names and server instructions for discovery.

Bifrost keeps each instruction and tool description below Claude Code’s 2,000-character limit. Bifrost does not force any tool to load for every task.

Local Plugin Testing

From the repository root, build Bifrost and start Claude Code with this package directory:

cargo build --bin bifrost
BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" claude --plugin-dir plugins/bifrost-agent

Before spending a model turn, confirm that the local plugin resolves its launcher independently of the project working directory:

claude --plugin-dir plugins/bifrost-agent mcp list

The local plugin:bifrost:bifrost entry should report Connected.

Inspect /plugin to confirm the bifrost metadata loaded without errors, then inspect /mcp. The packaged MCP server uses symbol|extended, so it exposes both symbol navigation and query_code.

To test the repository as a local Claude Code marketplace, run:

claude plugin marketplace add "$(pwd)"
claude plugin install bifrost@brokk --scope local
BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" claude

Start a fresh Claude Code session after installing the plugin so the MCP server configuration is loaded at startup.

Before testing query behavior, apply the shared host-integration evidence contract: retain the /mcp tool event and structured result for a known workspace declaration, verify its project-relative source path, and reject ordinary file-reading fallbacks or paths under the installed plugin.

Validate the Setup

For strong exact-checkout evidence, add a temporary declaration whose name is unique to the smoke:

src/claude_bifrost_host_probe_4f6f2b7.rs

pub fn claude_bifrost_host_probe_4f6f2b7() {}

Start a fresh Claude Code session in that checkout and use:

Use only the Bifrost MCP server for this verification. Call search_symbols for claude_bifrost_host_probe_4f6f2b7, then call query_code with schema_version 1, languages ["rust"], match {"kind":"function","name":"claude_bifrost_host_probe_4f6f2b7"}, limit 10, and result_detail "full". Do not use terminal, file-reading, text-search, web, or any other tool. PASS only if both real structured results return src/claude_bifrost_host_probe_4f6f2b7.rs.

A valid pass shows real mcp__plugin_bifrost_bifrost__search_symbols and mcp__plugin_bifrost_bifrost__query_code events with the same project-relative path. Remove the temporary declaration after retaining the evidence.

Native LSP

The plugin does not register an LSP server. The language server is the separate bifrost-lsp program, and the Bifrost binary rejects --lsp with the LSP server has moved out of this repository. See LSP Server for the status of bifrost-lsp.

Bifrost MCP tools provide workspace search, summaries, structural queries, policies, and other operations that do not depend on an editor position. Position-based navigation such as definitions and references will come from bifrost-lsp once a release exists and the plugin can register it.

Can My Agent Run RQL?

Confirm that query_code appears in /mcp for the fresh session. Then ask Claude to call it once with the inline JSON fields {"match":{"kind":"declaration"},"limit":1}. To validate saved RQL, check a workspace file named bifrost-smoke.rql containing (limit 1 (declaration)), then ask Claude to call query_code with {"query_file":"bifrost-smoke.rql"}.

The inline call is canonical JSON, not RQL. MCP accepts RQL only from a workspace .rql file named by query_file. A successful get_summaries or search_symbols call proves symbol navigation but does not prove that query_code is enabled. See MCP query and RQL availability for the full surface matrix and Agent Result Safety before making completeness claims.

Manual MCP Entry

Use a manual MCP entry instead of the plugin-provided server when you want the raw command shape or a different toolset:

claude mcp add --scope user bifrost -- bifrost --root /path/to/project --mcp "symbol|extended"
claude mcp list

Use an absolute path to the Bifrost binary if bifrost is not intentionally installed on the host PATH.

Use --mcp core only when you intentionally want navigation without query_code.