> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fallom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Integration

> Get observability for your Claude Code AI coding sessions

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:

```bash theme={null}
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](https://app.fallom.com/settings/api-keys).

Your key will look like: `flm_abc123xyz...`

### 2. Set the base URL

Add this to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

```bash theme={null}
# Route Claude Code through Fallom for observability
export ANTHROPIC_BASE_URL=https://anthropic.fallom.com/flm_YOUR_KEY_HERE
```

<Note>
  Replace `flm_YOUR_KEY_HERE` with your actual Fallom API key from step 1.
</Note>

### 3. Reload your shell

```bash theme={null}
source ~/.zshrc  # or ~/.bashrc
```

### 4. Use Claude Code normally

```bash theme={null}
claude "help me refactor this function"
```

All requests now flow through Fallom and appear in your dashboard at [app.fallom.com/observability/traces](https://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:

| Field          | Description                                               |
| -------------- | --------------------------------------------------------- |
| **Session ID** | Groups all requests in the same coding session            |
| **Model**      | Which Claude model was used (Sonnet, Haiku, etc.)         |
| **Duration**   | How long the request took                                 |
| **Tokens**     | Input and output token counts                             |
| **Cost**       | Calculated cost based on token usage                      |
| **Messages**   | Full conversation context                                 |
| **Tool calls** | Which tools Claude used (file edits, bash commands, etc.) |

## Advanced Configuration

### Custom metadata

Pass custom metadata via environment variables starting with `X_FALLOM_`:

```bash theme={null}
# 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:

```bash theme={null}
# ~/.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:

```bash theme={null}
ANTHROPIC_BASE_URL= claude "your prompt"
```

Or unset permanently:

```bash theme={null}
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:**
   ```bash theme={null}
   echo $ANTHROPIC_BASE_URL
   # Should show: https://anthropic.fallom.com/flm_...
   ```

2. **Verify your Fallom API key:**
   * Go to [app.fallom.com/settings/api-keys](https://app.fallom.com/settings/api-keys)
   * Check that your key is active

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:**

   ```bash theme={null}
   unset ANTHROPIC_BASE_URL
   claude "test"
   ```

   If this works, the issue is with the proxy.

2. **Check your Anthropic API key:**
   ```bash theme={null}
   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

```bash theme={null}
# 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

```bash theme={null}
# 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.

## Related

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="js" href="/integrations/typescript/tracing">
    Add tracing to your TypeScript app
  </Card>

  <Card title="Python SDK" icon="python" href="/integrations/python/tracing">
    Add tracing to your Python app
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/traces/create">
    Direct API usage
  </Card>

  <Card title="LangChain Integration" icon="link" href="/integrations/langchain">
    Use with LangChain
  </Card>
</CardGroup>