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

curl -fsSL https://download.tapes.dev/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, API, and derive worker together.
tapes serve

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. serve runs the proxy, API, and derive worker together, and embeds spans for tapes search by default (disable with --embed-spans=false). Proxy :8080, API :8081, ingest :8082. Migrations run automatically.

Seed

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

tapes seed --demo

Seeding replays bundled capture corpora through the normal ingest path and derives them, so demo sessions are indistinguishable from live capture. Re-running is a no-op.

Use

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

# List captured sessions and their ids
tapes sessions

# Open the Deck TUI over recent sessions
tapes deck

# Export a session as JSONL — the API projection verbatim.
# Pass a session id or its short prefix; export needs a running API.
tapes export <session-id> --api-target http://127.0.0.1:8081 -o session.jsonl

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

# Search main-conversation spans by meaning
tapes 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.

Go real

Once the demo flow makes sense, capture your own agent. Wipe the demo data, then point a real agent at the proxy:

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

# Launch an agent through tapes — it points the agent at the proxy for you
tapes start claude

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

tapes start wires the agent to the proxy and tags the session; you can also send any OpenAI/Anthropic-compatible client at http://localhost:8080. See the per-agent guides for Claude Code, OpenCode, and others.

Agent-specific setup: Claude Code, OpenCode, Ollama, and more in Guides.

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 Config.

Resources