| name | bifrost-debug |
| description | Diagnose why a Bifrost gateway, memory injection, or skill discovery isn't working in Claude Code. Triggers on 'bifrost not working', 'mcp not connecting', 'memory not injecting', 'skill_search failing', '401/403 from bifrost', 'bifrost debug', 'gateway unreachable'. |
Bifrost Diagnostics
Work through this decision tree to isolate and fix the problem.
1. Check BIFROST_URL and BIFROST_VK are set
echo "URL set: ${BIFROST_URL:+yes}${BIFROST_URL:-NO — missing}"
echo "VK set: ${BIFROST_VK:+yes}${BIFROST_VK:-NO — missing}"
If missing: export BIFROST_URL=https://<your-gateway-host>/mcp and
export BIFROST_VK=vk_<your-key> (add both to ~/.zshrc or ~/.bashrc).
Symptom if the VK is wrong/missing: 401 or 403 from every bifrost tool call.
2. Check bifrost is in ~/.claude/mcp.json
node -e "const m=require(require('os').homedir()+'/.claude/mcp.json'); console.log(m.mcpServers?.bifrost ? 'bifrost: OK' : 'bifrost: MISSING')"
If missing: run /bifrost-mcp-setup for manual wiring instructions.
Then restart Claude Code for CC to pick up the change.
3. Check gateway reachability
curl -s -o /dev/null -w "%{http_code}" \
-H "x-bf-vk: ${BIFROST_VK}" \
"${BIFROST_URL}"
Expected: 200 or 405 (OPTIONS probe). 401 → bad VK. Timeout / connection refused → gateway down or BIFROST_URL wrong (contact the gateway operator).
4. Check the gateway's memory MCP tools (for agent-driven memory)
Run /mcp and look for a memory server under bifrost. If present, test it:
mcp__bifrost__<memory-server>-search("test connection")
If the tool is not found, the gateway exposes no memory server — memory calls will
simply not be available. This does not affect skill discovery or gateway connectivity.
5. Check the plugin is installed and enabled
The hooks ship inside the plugin (via hooks/hooks.json), so they are managed by
the CC plugin subsystem — they do NOT appear in ~/.claude/settings.json. Verify
the plugin itself instead:
find ~/.claude/plugins -maxdepth 4 -type d -name 'bifrost-plugin*' 2>/dev/null
node -e "
const fs=require('fs'), os=require('os');
let cfg={};
try { cfg=JSON.parse(fs.readFileSync(os.homedir()+'/.claude.json','utf8')); } catch {}
const ep=JSON.stringify(cfg.enabledPlugins||cfg.plugins||{});
console.log('bifrost-plugin enabled:', ep.includes('bifrost-plugin') ? 'yes' : 'no / unknown');
"
If the plugin is missing or disabled: re-install / re-enable it via /plugin
(or /plugin install bifrost-plugin), then restart Claude Code so the hooks load.
6. Test skill_search directly
If your gateway exposes a skill server, inside Claude Code call:
mcp__bifrost__<skills-server>-skill_search("test connection")
- Returns results → MCP and skill routing are working.
- Tool not found → bifrost MCP server not loaded in this session (restart CC), or your gateway has no skill server.
- 401/403 → re-check VK (step 1).
Symptom → cause map
| Symptom | Cause | Fix |
|---|
| 401 on every bifrost call | BIFROST_VK wrong or missing | Set env var, restart CC |
| 403 | Key valid but no permission | Contact gateway operator |
skill_search tool not found | bifrost MCP not loaded or no skill server | Check ~/.claude/mcp.json; restart CC |
| Memory tool not found | Gateway exposes no memory server | Check with gateway operator; memory is optional |
| Gateway timeout | Gateway offline or wrong URL | Check BIFROST_URL; contact gateway operator |
For manual MCP wiring: /bifrost-mcp-setup.
For fresh onboarding: /bifrost-onboard.
