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 the Postgres database you configure (see Manual Setup or tapes local up).

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" \
  --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable"

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 your Postgres database.

Verify It's Working

Check that conversations are being captured:

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

You should see turn_count increase with each message:

{
  "session_count": 1,
  "turn_count": 4,
  "root_count": 1,
  "completed_count": 1,
  "total_cost": 0.0123,
  "input_tokens": 1820,
  "output_tokens": 540,
  "total_duration_ns": 8421000000,
  "tool_calls": 2
}

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 a Conversation Chain

Fetch the ancestry chain for a leaf hash (a "stem"):

curl http://localhost:8081/v1/stems/<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 Postgres 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: