Skip to content

brokkai/bifrost

v0.13.0Apache-2.0

Bifrost by Brokk: multi-language code intelligence and MCP workflows.

GitHubOpen Website

Bifrost Agent Plugin

This directory implements the Agent Plugins v1 package for Bifrost. Codex uses its package adapter, while the root package files remain the portable Agent Plugins v1 fallback. Pi, Claude Code, and Cursor also use this directory with their host adapters. Every host reuses the same launcher and pinned release metadata. The npm package @brokk/bifrost-agent contains the Pi extension.

None of these distributions bundles the Bifrost binary. The launcher resolves a released Bifrost binary and makes a multi-language code-analysis subset of the bifrost MCP tools discoverable through each host's plugin system.

The plugin name is bifrost across the portable package, Claude Code, Codex, and Cursor. Brokk owns the brokk marketplace namespace, so Claude/Codex marketplace installs read as bifrost@brokk where the host exposes namespace-qualified install names.

Claude Code starts ${CLAUDE_PLUGIN_ROOT}/bin/bifrost-launcher.mjs --mcp "symbol|extended" from the host-specific claude-mcp.json. Codex selects .codex-plugin/plugin.json, which points to .mcp.json and resolves the same launcher from the installed package root.

Portable Agent Plugins v1 Package

The package root contains the portable Agent Plugins v1 files:

  • plugin.json gives the shared package identity.
  • mcp.json gives the portable Bifrost stdio server.
  • skills/ contains portable skill directories.

Codex uses .codex-plugin/plugin.json and .mcp.json; the root files remain the portable fallback. Claude Code uses .claude-plugin/plugin.json and claude-mcp.json. Cursor uses .cursor-plugin/plugin.json and cursor-mcp.json because Cursor needs ${CURSOR_PLUGIN_ROOT} and timeout settings. Pi uses its TypeScript extension.

We tested package discovery with Codex CLI. We did not explicitly test the Agent Plugins v1 package with VS Code, GitHub Copilot, Kiro, or Cursor.

The launcher uses BIFROST_WORKSPACE_ROOT when set, then a host-provided --root or --workspace-root. Without either explicit override, Bifrost starts unbound and requests the host's approved workspace through standard MCP roots. On a rootless connection without advertised roots, it offers the codex/sandbox-state-meta extension; current Codex uses that capability to supply the active task. Bifrost never treats the installed plugin directory as the analyzer workspace. Claude Code uses ${CLAUDE_PLUGIN_ROOT} because its MCP commands otherwise resolve relative to the project directory, not the installed plugin. Cursor's plugin manifest explicitly selects cursor-mcp.json, which uses Cursor's documented type: "stdio" and ${CURSOR_PLUGIN_ROOT} placeholder. The root mcp.json remains portable. Both host-specific entries start Bifrost rootless. Builds containing the post-0.8.9 Cursor compatibility fix accept both standard file: root URIs and Cursor's native absolute-path form while keeping MCP roots authoritative; the published 0.8.9 binary requires an explicit fixed-project root. Amp uses a different direct server-map shape for mcp.json and --mcp-config.

Binary resolution order is:

  1. BIFROST_BINARY_PATH, when set to a compatible binary as an explicit override.
  2. The exact preferred Bifrost release in the launcher-managed cache.
  3. The newest compatible cached patch in the declared minor-series range.
  4. A compatible bifrost already on PATH, only when BIFROST_LAUNCHER_ALLOW_PATH=1 is set.
  5. A checksum-verified download of the exact preferred release.

The launcher rejects other major or minor versions and rejects prereleases unless release metadata explicitly allows them. It never downloads an unpinned compatible fallback. Every packaged host adapter uses this shared selection for MCP, and the Claude Code LSP adapter uses the same result. When compatibility mode starts a server and automatic installation is enabled, the launcher also starts a detached checksum-verified preparation of the exact preferred release. The current server continues using its selected compatible binary; the next fresh host task can select the prepared preferred binary. Set BIFROST_LAUNCHER_AUTO_INSTALL=0 to disable both foreground and background downloads.

Set BIFROST_LAUNCHER_AUTO_INSTALL=0 to disable downloads, or BIFROST_LAUNCHER_CACHE_DIR=/path/to/cache to choose the managed cache location. BIFROST_BINARY_PATH is the explicit local development override that bypasses ambient PATH lookup. Launcher diagnostics go to stderr so stdio MCP traffic stays on stdin/stdout.

Before a default MCP or LSP launch, the launcher asks the selected Bifrost binary for its pack-engine-profile and prepares the newest eligible public rules release together with its exact pinned semantic-pack release from Bifrost-packs, the home of open semantic packs and policies. Verified manifests, artifacts, and the extracted selection are cached under BIFROST_LAUNCHER_CACHE_DIR/open-pack-releases (or the platform cache directory when no launcher cache override is set). A warm verified cache is reused offline; disabling automatic installation also restricts packs to the verified cache. Set BIFROST_OPEN_PACKS_OFFLINE=1 to require offline lookup or BIFROST_OPEN_PACKS_REFRESH=1 to require fresh release discovery.

Manifest schema 2 selects by required schema versions and semantic capabilities; engine versions describe provenance. It requires verified integrity and behavior that has not failed, retaining pending or limited behavior in the selection receipt. Historical schema 1 releases retain their engine bounds and original qualification rules.

When an older binary does not support pack-engine-profile, or no eligible compatible set is available, the launcher reports a diagnostic on stderr and continues with the engine's embedded packs. Invalid release metadata, an invalid profile, or corrupt cached content stops launch so that verification failures cannot silently change the selected packs. A successfully prepared open selection supplies BIFROST_OPEN_SEMANTIC_PACK_BUNDLE, BIFROST_OPEN_POLICY_PACK_ROOT, and BIFROST_SEMANTIC_PACK_CACHE_ROOT to the engine, replacing embedded registration for those explicit pack roots.

The launcher also has commands that do not require a workspace. doctor reports the preferred and selected versions, source, and exact or compatibility mode without modifying the cache or downloading anything. Compatibility checks execute each selected candidate with --version, so use doctor only with binary locations you trust. prepare follows the normal resolution order and, when automatic installation is enabled, downloads and verifies the preferred pinned release without starting MCP. Both accept --json for stable machine-readable output:

plugins/bifrost-agent/bin/bifrost-launcher.mjs doctor
plugins/bifrost-agent/bin/bifrost-launcher.mjs prepare

After prepare succeeds, start a fresh host task so it negotiates the restored Bifrost tool surface. prepare respects BIFROST_LAUNCHER_AUTO_INSTALL=0; unset that variable before explicitly preparing a missing release.

For local development, build this checkout and point the launcher at the debug binary:

cargo build --bin bifrost
BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" node plugins/bifrost-agent/bin/bifrost-launcher.mjs --root . --mcp "symbol|extended"

Pi Install

Pi loads a native extension from this package. The extension resolves the same pinned, checksum-verified Bifrost binary as the other hosts, starts one stdio MCP child for the session's workspace, and closes the child on session shutdown or reload. Pi-visible tools use a bifrost_ namespace, so Bifrost's canonical MCP query_code tool appears as bifrost_query_code. The extension adds a short system-prompt note that explains this host-specific rendering. The extension adds no host-specific instruction files.

Install a local checkout after installing its package dependencies:

cd plugins/bifrost-agent
npm install
pi install "$(pwd)"

For development against this checkout's Rust binary:

cargo build --bin bifrost
cd plugins/bifrost-agent
npm install
BIFROST_BINARY_PATH="$(cd ../.. && pwd)/target/debug/bifrost" pi -e "$(pwd)"

To install from GitHub before an npm release, clone the repository and install the package directory as a local Pi package:

git clone https://github.com/BrokkAi/bifrost.git
cd bifrost/plugins/bifrost-agent
npm install
pi install "$(pwd)"

After @brokk/bifrost-agent is published to npm, install a pinned release with:

pi install npm:@brokk/bifrost-agent@0.13.0

Run /bifrost in Pi's interactive TUI to configure Bifrost for the current workspace. The default enables symbol navigation, structural queries, and file discovery/ranking. The settings list can also enable code-quality reports, Git history, raw text search, or JSON/XML transforms. It never offers Bifrost workspace-switching tools because Pi owns the session workspace. Selections are stored in separate canonical-workspace files under <Pi agent directory>/bifrost/workspaces/ (normally ~/.pi/agent/bifrost/workspaces/), so they survive new sessions without adding configuration to the repository or making concurrent workspaces rewrite the same settings document. If a settings file is malformed, interactive Pi reports the problem and starts with Bifrost disabled so /bifrost can repair the selection. Pi modes without a UI context report the failure through the extension error path and leave Bifrost unstarted instead of silently enabling defaults; Pi itself can continue without Bifrost.

Changing a capability may restart the Bifrost child when it requires another existing MCP server toolset. Tools discovered earlier remain registered with Pi but are removed from Pi's active tool set when disabled or rejected by Pi's command-line tool filters. The namespace note is omitted when Pi accepts no Bifrost tools. A failed change before connection retirement leaves the prior connection and saved selection active. If retiring that connection fails, the saved selection remains but Bifrost tools are disabled because cleanup could not be confirmed. In interactive Pi, startup, reconnect, and background connection failures use Pi's error notifications; in modes without a UI context, startup failures use Pi's extension error path. The extension does not write directly into the TUI with console.log or console.error.

Tool calls time out after 300 seconds; startup times out after 60 seconds. Cancellation stops the Pi request promptly, though the current Bifrost stdio server may finish analyzer work before it reads the MCP cancellation notification.

Bifrost results follow Pi's normal two-level output handling. The TUI shows a five-visual-line preview and expands the bounded result with Pi's tool-output shortcut (Ctrl+O by default). The model receives at most the first 2,000 lines or 50 KB. When complete text exceeds that limit, the result includes the path to a dedicated temporary overflow file containing the full output.

For a real-host smoke from the repository root, build Bifrost and ask Pi to exercise navigation plus both supported structural-query inputs:

cargo build --bin bifrost
BIFROST_BINARY_PATH="$PWD/target/debug/bifrost" \
BIFROST_LAUNCHER_AUTO_INSTALL=0 \
pi --no-session -e "$PWD/plugins/bifrost-agent" -p \
  'Use the Bifrost tools directly. First call bifrost_get_summaries for src/mcp_common.rs. Then call bifrost_query_code with inline canonical JSON fields match.kind=declaration and limit=1. Then call bifrost_query_code with only query_file="docs/fixtures/ten-minute-evaluation/queries/find-audit.rql". Report whether all three calls succeeded and include one repository-relative path from each result.'

Expect all three calls to succeed. The saved query should return docs/fixtures/ten-minute-evaluation/src/app.py; this also proves that query_file is resolved from Pi's explicit session workspace rather than from the installed package directory. Use Pi's JSON mode for protocol-level evidence when needed; Bifrost diagnostics remain on stderr and must not appear as JSON messages on stdout.

Package maintainers should keep package.json, package-lock.json, bifrost-release.json, and the Rust crate version aligned. Validate the package before publication:

cd plugins/bifrost-agent
npm ci
npm run check
npm test
npm run test:packed
npm pack --dry-run
npm publish --dry-run

A real publication requires npm credentials and an unused matching version; the repository does not imply that npm publishing is configured automatically.

Codex Install

Add the Brokk marketplace from GitHub, then install the Agent Plugins v1 package:

codex plugin marketplace add BrokkAi/bifrost --sparse .agents/plugins --sparse plugins
codex plugin add bifrost@brokk

The former brokk@bifrost coordinate inverted the project and owner names. Existing users must remove that installed plugin and its bifrost marketplace before adding this brokk marketplace and installing bifrost@brokk.

For local development from a checkout, add the repository root instead:

codex plugin marketplace add "$(pwd)"
codex plugin add bifrost@brokk

For a local checkout build, start Codex with this repository's debug binary selected explicitly:

BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" codex

Start a fresh Codex session after installing the package. The package-provided MCP server is registered automatically; do not add a second manual Bifrost MCP entry. It starts a separate stdio Bifrost process with:

bifrost --mcp "symbol|extended"

For that rootless process, Bifrost prefers standard MCP roots. When the client did not advertise roots, Bifrost offers the codex/sandbox-state-meta capability. A compatible client may then attach its active task directory to each analyzer tool call; current Codex does so. Bifrost binds that exact directory and revokes it when the per-call scope disappears or changes. BIFROST_WORKSPACE_ROOT remains an explicit compatibility override. Client-root and sandbox-metadata sessions keep analyzer and semantic cache writes under the exact approved root, including for linked worktrees.

The plugin gives Bifrost up to 180 seconds to download, verify, extract, and start a missing pinned release, and up to 300 seconds for individual analyzer tool calls. Large workspaces may need the tool-call budget because Bifrost can build its persisted analyzer on the first real tool call.

The default plugin toolset intentionally omits Bifrost's workspace and text MCP toolsets. That keeps local plugin installs focused on analyzer navigation and avoids giving prompts a built-in way to switch the active workspace or read arbitrary files through raw text tools. Users who explicitly want the full MCP surface can still add a manual codex mcp add entry for --mcp searchtools.

Once the session starts, verify the tools by calling a lightweight analyzer operation such as get_summaries or search_symbols against files in the active workspace.

Host Instructions

This package provides MCP configuration, the launcher, and specialist agents. It does not install instruction files into host-specific directories. Configure the host MCP entry, then start a new session and call a tool such as get_summaries or search_symbols.

Claude Code 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

The former brokk@bifrost coordinate inverted the project and owner names. Existing users must uninstall that plugin and remove its bifrost marketplace before adding this brokk marketplace and installing bifrost@brokk.

Start a fresh Claude Code session after installing the plugin so its MCP and native LSP server configurations are loaded at startup. The built-in LSP tool handles position-based definition, references, hover, and diagnostics; Bifrost's MCP tools provide workspace search, summaries, structural queries, and policies.

Claude Code Local Testing

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

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

Inspect /plugin to confirm the bifrost metadata and LSP server loaded, then inspect /mcp or ask Claude to call a lightweight analyzer operation such as get_summaries or search_symbols. Ask Claude to use only its built-in LSP tool on a unique declaration and reference in the active project, verifying definition, references, hover, and an automatic diagnostic after a temporary syntax error. Results must point into the active project, never the installed plugin directory.

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 and LSP server configurations are loaded at startup. If LSP startup fails, inspect the /plugin Errors tab, restart with claude --debug, and run plugins/bifrost-agent/bin/bifrost-launcher.mjs doctor to verify the pinned binary.

Cursor Local Testing

From the repository root, build Bifrost and open Cursor with the local binary selected:

cargo build --bin bifrost
BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" cursor .

In the dedicated Cursor Agents window, open Customize -> Plugins, choose Add -> From Local Repo, and select the repository root. Cursor reads .cursor-plugin/marketplace.json, finds the bifrost plugin at plugins/bifrost-agent, and offers it for installation. Do not select plugins/bifrost-agent directly: From Local Repo expects the repository marketplace manifest.

In the tested Cursor build, this route resolved plugin contents from the remote default branch, not from the selected feature-branch commit or dirty worktree. Use it only for a snapshot already reachable from that default branch. A local Rust binary can still be tested through BIFROST_BINARY_PATH; fully quit Cursor before running the command above so the new app process inherits the override.

After installing, open Customize -> MCPs in the Cursor Agents window, enable Bifrost, verify that it connects, and start a fresh agent. Then use a strict prompt that proves the result came through Bifrost instead of ordinary file or shell search:

Use only the installed Bifrost plugin MCP tools. First confirm query_code is in
the callable Bifrost MCP surface. Then call the Bifrost search_symbols MCP tool
with patterns ["reconcile_codex_sandbox_workspace"]. Do not use Shell,
terminal, rg, codebase search, file reading, or the bifrost CLI. Report the
exact MCP result, especially the returned path.

The published 0.8.9 binary does not accept Cursor's native-path roots/list response. For a fixed-project 0.8.9 smoke, fully quit Cursor and start it from the intended project with BIFROST_WORKSPACE_ROOT="$(pwd)" cursor .. The override is authoritative and must be changed when switching projects.

Cursor Agents 3.12.30 may return the base repository as its MCP root while an agent runs in a separate worktree. In that mode, verify a branch-only symbol or file instead of accepting a relative path that exists in both checkouts.

The cursor agent --plugin-dir CLI path is useful for checking plugin loading, but it has not proven reliable for plugin-provided MCP servers. Treat the desktop Customize/MCP path as the Cursor plugin MCP smoke.

To publish publicly, submit the repository URL at https://cursor.com/marketplace/publish. The repository root contains .cursor-plugin/marketplace.json, which points Cursor at this shared package.

Antigravity Install and Local Testing

Antigravity can load Bifrost through manual MCP configuration. The visible Add MCP flow is a curated marketplace, but Antigravity accepts the standard mcpServers shape in global ~/.gemini/config/mcp_config.json and workspace-local .agents/mcp_config.json files. See Antigravity's official MCP documentation for the host-side convention.

{
  "mcpServers": {
    "bifrost": {
      "command": "/absolute/path/to/bifrost/target/debug/bifrost",
      "args": [
        "--root",
        "/absolute/path/to/workspace",
        "--mcp",
        "symbol|extended"
      ]
    }
  }
}

This global entry is suitable only for one fixed workspace: it does not follow Antigravity's active Project or Git worktree. For worktrees, add a separate uncommitted .agents/mcp_config.json in each worktree. Set cwd to that worktree's absolute path and pass --root ., for example:

{
  "mcpServers": {
    "bifrost": {
      "command": "/absolute/path/to/bifrost",
      "cwd": "/absolute/path/to/this/worktree",
      "args": ["--root", ".", "--mcp", "symbol|extended"]
    }
  }
}

Bifrost requires that explicit binding because Antigravity does not currently provide a dynamic MCP workspace root. Do not use the installed plugin directory, the process CWD, or the selected Project as an inferred root. A per-worktree installer may derive the path with git rev-parse --show-toplevel, but it must merge only Bifrost's entry and leave every other MCP server intact.

Click Refresh in Settings -> Customizations after creating or changing the file. Refresh normally reloads the MCP connection without restarting the whole application; use a fresh conversation to validate its tool surface. If the app still displays an old root after Refresh, fully quit and reopen it.

Open the project-specific settings page in Antigravity. Validate with a prompt that requires a Bifrost MCP tool on source code:

Use the Bifrost MCP get_summaries tool on src/analyzer/usages for source context, and name the files summarized from the MCP result.

Amp Install and Local Testing

Configure Amp's direct MCP server map with the Bifrost launcher. For local testing, use the checked-out binary and an explicit workspace root.

{
  "bifrost": {
    "command": "/absolute/path/to/plugin/bin/bifrost-launcher.mjs",
    "cwd": "/absolute/path/to/workspace",
    "args": ["--root", ".", "--mcp", "symbol|extended"]
  }
}

Start a fresh Amp task after changing the MCP configuration. Validate with a prompt that requires an analyzer MCP tool on source code:

BIFROST_BINARY_PATH="$(pwd)/target/debug/bifrost" amp -x \
  'Use the Bifrost MCP get_summaries tool on src/analyzer/usages/rust_graph/*.rs and name three symbols from the MCP result.'

Difference From codex mcp add

codex mcp add, claude mcp add, a manual Cursor mcp.json entry, or amp mcp add registers one MCP server directly in a user's host configuration. This plugin packages a safer default server shape behind host plugin flows where available, so users can install or remove Bifrost without hand-editing MCP configuration. Amp uses its direct server-map configuration because it has no matching host plugin manifest here.

The MCP process created by this plugin is independent from the standalone language server used by the VS Code extension. Each host starts its own stdio process and checks its own engine pack profile.