Skip to main content
The Bitfab Claude Code plugin brings the full evaluation workflow into Claude Code. It provides MCP tools for trace inspection and diagnostics, slash commands for authentication, and automatic notifications — so you never have to leave your editor.

​
Installation

Install the plugin from the Bitfab marketplace: 
> /plugin marketplace add Project-White-Rabbit/bitfab-claude-plugin
> /plugin install bitfab
> /exit
Then restart Claude Code: 
claude --continue
Once restarted, run the setup command to authenticate and instrument your codebase: 
> /bitfab:setup

​
What the Plugin Does

​
Automatic Setup

The /bitfab:setup command runs a multi-phase workflow:
  1. Login — Opens your browser for OAuth authentication, saves credentials securely
  2. Instrument — Reads your codebase, finds all AI workflows (LLM calls, agents, AI-driven decisions), and presents them as a numbered list. You choose which to instrument — it adds tracing with minimal diffs
  3. Replay — Creates replay scripts so you can regression-test your trace functions against production data with one command
You can run individual phases: 
> /bitfab:setup login        # Auth only
> /bitfab:setup instrument   # Trace instrumentation only
> /bitfab:setup replay       # Replay script creation only
The setup is interactive — it presents 2-5 concrete options per decision point with a recommended choice, so you stay in control throughout.

​
MCP Tools

The plugin registers MCP tools that Claude Code can call during conversations. These let you inspect traces, diagnose failures, and improve your code without leaving the editor.

​
setup_bitfab

Get a complete, language-specific SDK setup guide with install commands, initialization code, and instrumentation patterns. 
"Set up Bitfab tracing for my TypeScript project"

​
get_bitfab_api_key

Retrieve your API key for environment variable configuration.

​
list_trace_functions

List all traced functions in your organization with stats at a glance — what’s being traced and how it’s performing. 
"Show me all my traced functions"

​
get_trace_function_diagnostics

Deep-dive into failures for a specific trace function. Returns failure summaries, recent failures with trace IDs, and exact reasons why traces are failing. 
"Why is my order-processing function failing?"

​
search_traces

Search and filter traces with full-text search, date ranges, status filters, and regex matching. Supports drill-down to narrow results progressively. 
"Find all failed traces for order-processing from the last week"

​
read_traces

Read one or more traces by ID with full details — span summaries or complete input/output/reasoning/context/errors per span. 
"Show me the full details of trace abc-123"

​
Slash Commands

CommandDescription
/bitfab:setupFull setup workflow — authenticate, instrument, create replay scripts
/bitfab:setup loginAuth only
/bitfab:logoutRemove saved credentials
/bitfab:statusCheck auth status, plugin version, and available updates
/bitfab:updateUpdate the plugin to the latest version

​
Session Notifications

The plugin runs a hook on every session start and resume that checks:
  • Authentication: If you’re not logged in, it reminds you to run /bitfab:setup
  • Updates: If a new plugin version is available, it tells you how to update (or auto-updates if you’ve enabled it)

​
Example Workflows

​
Instrument a new project

> /bitfab:setup
The agent detects your project language, finds AI workflows, presents options, and instruments your chosen workflows — all interactively.

​
Diagnose and fix a failing function

Ask Claude Code naturally: 
"My order-processing traces are failing. What's going wrong and can you fix it?"
The plugin calls get_trace_function_diagnostics to analyze failures, then search_traces and read_traces to inspect specific failing traces — and suggests code fixes directly.

​
Replay after a code change

After updating a function, run your replay script to test against production data: 
npx tsx scripts/replay.ts extraction --limit 20
Or ask Claude Code to do it for you — it can run the script and interpret the results.

​
Configuration

​
Credentials

Credentials are stored in ~/.config/bitfab/credentials.json (created by /bitfab:setup login with owner-readable permissions).

​
Environment Variables

VariableDescription
BITFAB_API_KEYOverride the stored API key

​
Troubleshooting

​
Not authenticated

If you see “Not authenticated” on session start:
  1. Run /bitfab:setup login to authenticate via browser
  2. Check that ~/.config/bitfab/credentials.json exists and contains your API key
  3. If using an environment variable, verify BITFAB_API_KEY is set

​
MCP tools not available

If Claude Code can’t access the Bitfab tools:
  1. Run /bitfab:status to check connection status
  2. Try restarting Claude Code — the MCP server initializes on startup
  3. Verify the plugin is installed: check /plugin list

​
Stale session

The plugin automatically detects and recovers from stale MCP sessions. If tools stop working mid-conversation, they’ll reconnect on the next call.

​
Plugin updates

Run /bitfab:status to check for updates, then /bitfab:update to install the latest version. Restart Claude Code after updating.