tapes

tapes Overview

Today's agent tools are opaque. Once a session ends, all of that context is lost: the decisions, the errors, the lessons learned.

tapes records every request and response between your agent and model providers. It acts as a proxy server that captures and stores conversation history, allowing you to inspect, search, and verify what happened. Learn more on why transparent telemetry changes everything.

We are working to establish standards within Agent Trace, an open specification.

Install

# tapes is the server — it runs the services and owns the database
curl -fsSL https://download.tapes.dev/install | bash

# tapesctl is the client — it captures sessions and reads them back
curl -sSfL https://download.tapes.dev/tapesctl/install | bash

Run

# 1. Bring up Postgres (with pg_duckdb + pgvector) and Ollama.
#    This writes the connection settings into your tapes config.
tapes local up

# 2. Run the proxy, read API, private ingest API, and derive worker together.
tapes serve

# 3. Point the client at the read API once, so read commands need no flag.
tapesctl config set tapes-url http://localhost:8081

tapes local up writes storage.postgres_dsn (and the Ollama + embedding settings) into your .tapes config, so tapes serve picks them up with no flags. Defaults: proxy :8080, read API :8081, private ingest API :8082. Migrations run automatically, and serve embeds spans for tapesctl search by default (disable with --embed-spans=false).

Seed

Start with demo data so every command below has something to show — this path works end to end before you wire up a real agent:

tapesctl seed

Seeding asks the server to load its bundled demo sessions and derive them, so the read commands below have real data to show. Like every read command, seed addresses the read API — the tapes-url you set above.

Use

Explore the seeded sessions — list them, export the projection, or search them:

# List captured sessions and their ids
tapesctl sessions list

# Export a session as JSONL — the API projection verbatim
tapesctl export <session-id> -o session.jsonl

# Turn headers only, without the span trees
tapesctl export <session-id> --detail traces

# Search spans by meaning
tapesctl search "explain the retry logic"

The proxy forwards each request upstream and appends it to the raw turn log; the derive worker projects those turns into the sessions, traces, and spans these commands read. The <session-id> here is the tapes session id from sessions list.

Go real

Once the demo flow makes sense, capture your own agent. Wipe the demo data, then launch an agent under capture:

# Clear the demo (recreate the local database)
tapes local down --wipe && tapes local up

# Launch an agent under capture — completed turns ship to the ingest API
tapesctl start claude --tapes-url http://localhost:8082

# ...or point any LLM client at the proxy yourself
#   base URL: http://localhost:8080

Capture commands address the private ingest API on :8082; read commands address the read API on :8081. You can also send any OpenAI/Anthropic-compatible client through the proxy at http://localhost:8080. See the per-agent guides for Claude Code, Codex, and Ollama.

Agent-specific setup: Claude Code, Codex, Ollama, and more in the docs.

Save

Sessions persist in Postgres as soon as tapes serve is pointed at a database. For per-project config, initialize a .tapes/ directory:

tapes init

Creates .tapes/config.toml with project-local settings — pin a Postgres DSN, embedding model, or provider preset here. See Configuration.

Resources