Skip to main content
Get real-time observability for all your Claude Code AI coding sessions. Track costs, monitor performance, and debug issues in your AI-powered development workflow.

​
Overview

The Fallom proxy for Claude Code gives you:
  • Cost tracking - See exactly how much each coding session costs
  • Performance monitoring - Track latency and token usage
  • Session replay - Review conversations and decisions Claude made
  • Error detection - Catch and debug Claude Code issues

​
Quick Start

Set one environment variable to route all Claude Code requests through Fallom: 
export ANTHROPIC_BASE_URL=https://anthropic.fallom.com/YOUR_FALLOM_API_KEY
That’s it! All your Claude Code sessions will now appear in your Fallom dashboard.

​
Setup

​
1. Get your Fallom API Key

Get your API key from the Fallom dashboard. Your key will look like: flm_abc123xyz...

​
2. Set the base URL

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.): 
# Route Claude Code through Fallom for observability
export ANTHROPIC_BASE_URL=https://anthropic.fallom.com/flm_YOUR_KEY_HERE
Replace flm_YOUR_KEY_HERE with your actual Fallom API key from step 1.

​
3. Reload your shell

source ~/.zshrc  # or ~/.bashrc

​
4. Use Claude Code normally

claude "help me refactor this function"
All requests now flow through Fallom and appear in your dashboard at app.fallom.com/observability/traces.

​
How it works

┌──────────────┐
│ Claude Code  │
│  (your CLI)  │
└──────┬───────┘
       │
       │ Your Anthropic API key + Fallom tracking
       │
       ▼
┌──────────────────┐
│  Fallom Proxy    │  ← Logs traces
│  (transparent)   │
└──────┬───────────┘
       │
       │ Forwards to Anthropic
       │
       ▼
┌──────────────────┐
│  Anthropic API   │
└──────────────────┘
The proxy:
  1. Receives your Claude Code request
  2. Logs the trace to Fallom (async, non-blocking)
  3. Forwards to Anthropic API unchanged
  4. Streams the response back to you in real-time
  5. Logs the final trace with usage data
Zero latency impact - streaming is preserved and traces are logged asynchronously.

​
What you’ll see in Fallom

Each Claude Code session creates traces with:
FieldDescription
Session IDGroups all requests in the same coding session
ModelWhich Claude model was used (Sonnet, Haiku, etc.)
DurationHow long the request took
TokensInput and output token counts
CostCalculated cost based on token usage
MessagesFull conversation context
Tool callsWhich tools Claude used (file edits, bash commands, etc.)

​
Advanced Configuration

​
Custom metadata

Pass custom metadata via environment variables starting with X_FALLOM_: 
# Add Linear issue tracking
export X_FALLOM_LINEAR_ISSUE="LIN-123"

# Add git branch
export X_FALLOM_BRANCH=$(git branch --show-current)

# Add custom customer ID
export X_FALLOM_CUSTOMER_ID="customer-abc"
These will appear in your trace metadata and can be used for filtering.

​
Different environments

Use different Fallom keys for different environments: 
# ~/.zshrc or ~/.bashrc

# Development
alias claude-dev='ANTHROPIC_BASE_URL=https://anthropic.fallom.com/flm_dev_key claude'

# Production
alias claude-prod='ANTHROPIC_BASE_URL=https://anthropic.fallom.com/flm_prod_key claude'

# No tracking
alias claude-direct='unset ANTHROPIC_BASE_URL && claude'

​
Disable temporarily

To disable Fallom for a single command: 
ANTHROPIC_BASE_URL= claude "your prompt"
Or unset permanently: 
unset ANTHROPIC_BASE_URL

​
Pricing

The Fallom proxy is free to use. You only pay for:
  • Your Claude Code API usage (to Anthropic)
  • Your Fallom plan (for trace storage and analytics)
The proxy adds zero cost - it’s just pass-through observability.

​
Troubleshooting

​
Claude Code not sending traces

  1. Check the environment variable is set: 
    echo $ANTHROPIC_BASE_URL
# Should show: https://anthropic.fallom.com/flm_...
  2. Verify your Fallom API key:
  3. Check Railway logs:
    • The proxy logs all requests
    • Look for errors in the Railway dashboard

​
Requests failing

If Claude Code requests fail after setting the base URL:
  1. Remove the base URL temporarily: 
    unset ANTHROPIC_BASE_URL
claude "test"
    If this works, the issue is with the proxy.
  2. Check your Anthropic API key: 
    echo $ANTHROPIC_API_KEY
# Should be set
  3. Contact support:
    • Share the error message
    • Include your Fallom API key (first 8 characters only)

​
Traces not appearing in dashboard

Traces should appear within 1-2 seconds. If they don’t:
  1. Check the correct organization:
    • Ensure you’re viewing the right org in Fallom
  2. Verify API key permissions:
    • API key might not have trace write permissions
  3. Check filters:
    • Clear any filters in the traces view

​
Security

  • API keys never logged - Your Anthropic API key is never stored
  • TLS encryption - All traffic uses HTTPS
  • No data retention - Proxy doesn’t store any request/response data
  • Open source - Proxy code is auditable
The proxy only forwards requests and logs metadata - your code and conversations flow through but aren’t stored by the proxy.

​
Examples

​
Track costs per project

# Set project in metadata
export X_FALLOM_PROJECT="mobile-app"
claude "help me optimize this React Native component"

# Check costs in Fallom filtered by metadata.project = "mobile-app"

​
Debug a specific session

# Use custom session ID
export X_FALLOM_SESSION_ID="debug-auth-issue"
claude "why is authentication failing?"

# Find traces by session_id in Fallom

​
Monitor token usage

All traces include:
  • usage.input_tokens - Tokens in your prompt + context
  • usage.output_tokens - Tokens in Claude’s response
  • usage.cache_read_input_tokens - Tokens loaded from cache
  • usage.cache_creation_input_tokens - New tokens cached
Use these to optimize prompt sizes and reduce costs.

TypeScript SDK

Add tracing to your TypeScript app

Python SDK

Add tracing to your Python app

API Reference

Direct API usage

LangChain Integration

Use with LangChain