Copied to clipboard

tapes

Claude Code Setup

Capture every Claude Code conversation automatically with zero code changes.

Quick Start

The simplest way to capture Claude Code conversations:

tapes start claude

This automatically:

  • Starts the tapes daemon with auto-selected ports
  • Configures Claude Code to route through the proxy
  • Tags all conversations with agent_name: claude
  • Shuts down cleanly when you exit Claude Code

Conversations are stored in ~/.tapes/tapes.sqlite by default.

Manual Setup

For more control over ports and configuration, use tapes serve:

1. Start tapes

tapes serve \
  --provider anthropic \
  --upstream "https://api.anthropic.com" \
  --proxy-listen "0.0.0.0:8080" \
  --sqlite "./tapes.sqlite"

The --provider anthropic flag is required. Default provider is ollama.

If :8081 is busy, add --api-listen "0.0.0.0:8082" or another free port.

2. Configure Claude Code

Add to your shell config (~/.zshrc or ~/.bashrc):

export ANTHROPIC_BASE_URL="http://localhost:8080"
Base URL Combinations

Match your --upstream and ANTHROPIC_BASE_URL to avoid path conflicts:

Upstream Base URL
https://api.anthropic.com http://localhost:8080
https://api.anthropic.com/v1 http://localhost:8080/v1

Mismatched paths cause 404 errors (e.g., upstream /v1 with base URL without /v1).

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

3. Use Claude Code

claude

All conversations are now captured in ./tapes.sqlite

Verify It's Working

Check that conversations are being captured:

curl http://localhost:8081/v1/stats

You should see counts increase with each message:

{
  "turn_count": 4,
  "root_count": 1,
  "session_count": 1
}

What You Get

  • Full conversation history - Every message, tool call, and response
  • Token usage tracking - Input/output tokens and cache hits per conversation
  • Cost analysis - Track API spending across sessions
  • Semantic search - Find past work by meaning (setup guide)

Query Your Data

List Sessions

curl http://localhost:8081/v1/sessions

View Specific Session

curl http://localhost:8081/v1/sessions/<hash>

After enabling semantic search:

curl "http://localhost:8081/v1/search?q=how%20did%20I%20fix%20the%20auth%20bug"

Stop Using tapes

Remove the environment variable from your shell config:

# export ANTHROPIC_BASE_URL="http://localhost:8080"  # Commented out

Reload your shell:

source ~/.zshrc

Claude Code now connects directly to Anthropic. Your captured data in ./tapes.sqlite is preserved.

Troubleshooting

Not Capturing Conversations

Verify the environment variable is set:

echo $ANTHROPIC_BASE_URL

Should output: http://localhost:8080

404 Errors

Check your base URL and upstream path combination. Both must match:

# Option 1: No /v1 suffix on either
--upstream "https://api.anthropic.com"
export ANTHROPIC_BASE_URL="http://localhost:8080"

# Option 2: /v1 suffix on both
--upstream "https://api.anthropic.com/v1"
export ANTHROPIC_BASE_URL="http://localhost:8080/v1"

Mismatched paths (e.g., upstream with /v1 and base URL without) cause 404s.

Wrong Provider Default

tapes defaults to ollama provider. For Claude Code, explicitly set:

tapes serve --provider anthropic ...

Port Already in Use

Kill the process using port 8080:

lsof -ti :8080 | xargs kill -9

API Server Port Conflict

If port 8081 is busy, tapes exits silently. Free the port or use a different one:

# Check what's using port 8081
lsof -ti :8081

# Or specify a different API port
tapes serve --api-listen ":8082" ...

Config Precedence

Local .tapes/ directory overrides ~/.tapes/ config. Check for a local config:

ls -la .tapes/

Delete or rename the local directory to use global config.

Verify tapes is Running

curl http://localhost:8081/ping

Should return: "pong"

Next Steps

Last updated: