README
¶
tapes
Transparent agentic telemetry and instrumentation for content-addressable LLM interactions.
About
·
Download
·
Documentation
·
Contributing
tapes is an Agentic telemetry system for content-addressable LLM interactions.
It provides durable storage of agent sessions, plug-and-play OpenTelemetry instrumentation,
and a derived sessions/traces/spans model for querying and exporting past agent work.
About
Capture is append-only: every intercepted LLM interaction is persisted to an
immutable raw_turns log. A pure, idempotent deriver projects that log into
the read model — sessions → traces → spans (with span links) — and re-running
the deriver simply reproduces the same projection (re-derive prunes anything no
longer present down to 0). Derived IDs are deterministic, so the same raw input
always yields the same sessions, traces, and spans.
Reads happen over that derived surface: list and inspect sessions
(/v1/sessions, cursor-paginated, with model/token/cost/turn-count folds),
browse traces and spans (/v1/traces, /v1/sessions/{id}/traces), aggregate at
span grain (/v1/stats), and run span-grain semantic search (/v1/search/spans).
The original capture is always available verbatim via
/v1/sessions/{id}/raw_turns.
Content addressing (the merkle node layer) is retained internally for provenance and dedup; it is not a user-facing browsing surface.
📼 Quickstart
Install tapes:
curl -fsSL https://download.tapes.dev/install | bash
tapes stores sessions in PostgreSQL (with the pgvector extension) and uses an
embedding provider to power tapesctl search. The quickest way to get a local
Postgres — plus Ollama for embeddings — is the bundled Docker bootstrap (requires Docker):
tapes local up
tapes local up pulls the default embeddinggemma model and writes the
Postgres + Ollama connection settings into your .tapes config, so the
commands below need no connection flags.
Then start Tapes. tapes serve runs the whole local pipeline together — the
proxy (capture), the API, and the derive worker (which projects captured turns
into sessions/traces/spans) — so anything you capture becomes browsable
automatically. It also embeds spans for tapesctl search by default (disable with
--embed-spans=false):
tapes serve
Prefer OpenAI embeddings? Store an API key and switch the embedding provider
(tapes local up still provides the required Postgres; Ollama just goes unused):
tapes auth openai
tapes config set embedding.provider openai
tapes serve
You can also provide the key with OPENAI_API_KEY instead of tapes auth openai.
When OpenAI is selected without a key, Tapes fails at startup with an authentication
configuration error from the OpenAI embedder.
Capturing and reading: tapesctl
tapes is the server. Capturing a session and reading one back are client
concerns, and they live in tapesctl:
curl -sSfL https://download.tapes.dev/tapesctl/install | bash
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 --tapes-url http://localhost:8081
List captured sessions and their ids:
tapesctl sessions list --tapes-url http://localhost:8081
Browse sessions and drill into a single session in the deck TUI:
Export a captured session as JSONL — the API's session→traces→spans projection
verbatim. tapesctl export is a thin client of GET /v1/sessions/{id}/export,
so it needs a running API. The full span tree is included by default; pass
--detail traces for turn headers only:
tapesctl export <session-id> --tapes-url http://localhost:8081 -o session.jsonl
tapesctl export <session-id> --detail traces
Search across captured spans (individual main-conversation LLM spans, with
their trace and turn context). tapes serve embeds spans by default, so this
works out of the box:
tapesctl search "explain the retry logic"
Ready for the real thing? Clear the demo data and point your own agent at the proxy:
tapes local down --wipe && tapes local up # recreate the DB, clearing the demo
tapesctl start claude --tapes-url http://localhost:8081
tapesctl start launches the agent under a just-in-time capture proxy and ships
the turns to this server. See the agent guides for
Claude Code, OpenCode, and more.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api provides an HTTP API server over the derived sessions/traces/spans read model.
|
Package api provides an HTTP API server over the derived sessions/traces/spans read model. |
|
cassetterunner
Package cassetterunner resolves and serves the cassettes an API server publishes.
|
Package cassetterunner resolves and serves the cassettes an API server publishes. |
|
mcp
Package mcp provides an MCP (Model Context Protocol) server for the Tapes system.
|
Package mcp provides an MCP (Model Context Protocol) server for the Tapes system. |
|
cli
|
|
|
extproc-replay-server
command
replay-server reads paperd wire-trace bundles and serves the captured upstream responses back over HTTP, so extproc can be exercised against real upstream streaming bytes inside a cluster instead of against synthetic curls.
|
replay-server reads paperd wire-trace bundles and serves the captured upstream responses back over HTTP, so extproc can be exercised against real upstream streaming bytes inside a cluster instead of against synthetic curls. |
|
tapes
command
|
|
|
tapes-extproc
command
|
|
|
cmd
|
|
|
tapes
Package tapescmder
|
Package tapescmder |
|
tapes/auth
Package authcmder provides the auth command for storing API credentials.
|
Package authcmder provides the auth command for storing API credentials. |
|
tapes/backfill
Package backfillcmder exposes offline backfills into a running tapes deployment.
|
Package backfillcmder exposes offline backfills into a running tapes deployment. |
|
tapes/config
Package configcmder provides the config command for managing persistent tapes configuration stored in the .tapes/ directory.
|
Package configcmder provides the config command for managing persistent tapes configuration stored in the .tapes/ directory. |
|
tapes/init
Package initcmder provides the init command for initializing a local .tapes directory in the current working directory.
|
Package initcmder provides the init command for initializing a local .tapes directory in the current working directory. |
|
tapes/raw
Package rawcmder holds the operator tooling for the verbatim-capture layer.
|
Package rawcmder holds the operator tooling for the verbatim-capture layer. |
|
tapes/serve
Package servecmder provides the serve command with subcommands for running services.
|
Package servecmder provides the serve command with subcommands for running services. |
|
tapes/serve/api
Package apicmder provides the API tapes server cobra command.
|
Package apicmder provides the API tapes server cobra command. |
|
tapes/serve/deriveworker
Package deriveworkercmder provides the derive-worker cobra command.
|
Package deriveworkercmder provides the derive-worker cobra command. |
|
tapes/serve/embedworker
Package embedworkercmder provides the embed-worker cobra command.
|
Package embedworkercmder provides the embed-worker cobra command. |
|
tapes/serve/ingest
Package ingestcmder provides the ingest server cobra command.
|
Package ingestcmder provides the ingest server cobra command. |
|
tapes/serve/proxy
Package proxycmder provides the proxy server command.
|
Package proxycmder provides the proxy server command. |
|
tapes/status
Package statuscmder provides the status command: a quick readout of the local tapes setup — which .tapes/ directory and configuration are in use, and whether the configured API target is reachable.
|
Package statuscmder provides the status command: a quick readout of the local tapes setup — which .tapes/ directory and configuration are in use, and whether the configured API target is reachable. |
|
tapes/version
Package versioncmder
|
Package versioncmder |
|
headers
Package headers names the HTTP / ext_proc header values that tapes-extproc reads from the upstream traffic Envoy hands it.
|
Package headers names the HTTP / ext_proc header values that tapes-extproc reads from the upstream traffic Envoy hands it. |
|
Package ingest provides an HTTP server that accepts completed LLM conversation turns and appends them to the immutable raw-turn capture log.
|
Package ingest provides an HTTP server that accepts completed LLM conversation turns and appends them to the immutable raw-turn capture log. |
|
internal
|
|
|
openapicheck
Package openapicheck compares a server's registered routes against the OpenAPI contract it publishes.
|
Package openapicheck compares a server's registered routes against the OpenAPI contract it publishes. |
|
testdb
Package testdb coordinates suites that share the Postgres service provided by the Dagger Test check.
|
Package testdb coordinates suites that share the Postgres service provided by the Dagger Test check. |
|
pkg
|
|
|
capture
Package capture holds the shared streaming-reduction library consumed by both the local tapes proxy and the cloud tapes-extproc sidecar.
|
Package capture holds the shared streaming-reduction library consumed by both the local tapes proxy and the cloud tapes-extproc sidecar. |
|
capture/fixtures
Package fixtures exposes the capture reducer test fixtures as an embed.FS so every consumer exercises the SAME bytes instead of hand-copied inline duplicates.
|
Package fixtures exposes the capture reducer test fixtures as an embed.FS so every consumer exercises the SAME bytes instead of hand-copied inline duplicates. |
|
cassette
Package cassette defines schema-independent cassette contracts shared by versioned cassette manifest packages.
|
Package cassette defines schema-independent cassette contracts shared by versioned cassette manifest packages. |
|
cassette/manifest
Package manifest decodes a cassette manifest of any supported schema version into the schema-independent cassette.Manifest contract.
|
Package manifest decodes a cassette manifest of any supported schema version into the schema-independent cassette.Manifest contract. |
|
cassette/v1alpha1
Package v1alpha1 defines the versioned cassette metadata embedded in an OpenAPI document, including strict parsing, validation, and pure derivations.
|
Package v1alpha1 defines the versioned cassette metadata embedded in an OpenAPI document, including strict parsing, validation, and pure derivations. |
|
cliui
Package cliui provides reusable terminal UI helpers (spinners, step indicators, markdown rendering) for tapes CLI commands.
|
Package cliui provides reusable terminal UI helpers (spinners, step indicators, markdown rendering) for tapes CLI commands. |
|
derive
Package derive turns immutable raw captures into the derived layer: content-addressed node chains today; semantic typing (node_kind), fork edges, and offshoot classification as the reconciled conversation tree lands (design/agent-session-reconciliation.md).
|
Package derive turns immutable raw captures into the derived layer: content-addressed node chains today; semantic typing (node_kind), fork edges, and offshoot classification as the reconciled conversation tree lands (design/agent-session-reconciliation.md). |
|
derive/worker
Package worker is the production derive loop: it polls the dirty- session queue ingest feeds (see storage.DeriveQueue), debounces bursts, and re-derives one session at a time under a per-session advisory lock.
|
Package worker is the production derive loop: it polls the dirty- session queue ingest feeds (see storage.DeriveQueue), debounces bursts, and re-derives one session at a time under a per-session advisory lock. |
|
dotdir
Package dotdir manages the .tapes/ and ~/.tapes directories that hold local configuration, credentials, and other tapes state.
|
Package dotdir manages the .tapes/ and ~/.tapes directories that hold local configuration, credentials, and other tapes state. |
|
embeddings
Package embeddings
|
Package embeddings |
|
embeddings/ollama
Package ollama implements pkg/embedding's Embedder client for Ollama's embedding APIs
|
Package ollama implements pkg/embedding's Embedder client for Ollama's embedding APIs |
|
embeddings/openai
Package openai implements pkg/embeddings's Embedder client for OpenAI's embeddings API.
|
Package openai implements pkg/embeddings's Embedder client for OpenAI's embeddings API. |
|
embeddings/utils
Package embeddingutils is the embeddings utility package
|
Package embeddingutils is the embeddings utility package |
|
embedworker
Package embedworker is the production span-embedding loop: it runs the bounded span-embedding pass (see pkg/spanembed) on its own interval, in its own process (`tapes serve embed-worker`) — split out of the derive worker so that embedding NEVER blocks derivation.
|
Package embedworker is the production span-embedding loop: it runs the bounded span-embedding pass (see pkg/spanembed) on its own interval, in its own process (`tapes serve embed-worker`) — split out of the derive worker so that embedding NEVER blocks derivation. |
|
git
Package git provides utilities for detecting git repository information.
|
Package git provides utilities for detecting git repository information. |
|
llm
Package llm provides a internal representations of LLM inference API requests and responses which are then further mutated and handled.
|
Package llm provides a internal representations of LLM inference API requests and responses which are then further mutated and handled. |
|
llm/provider/anthropic
Package anthropic
|
Package anthropic |
|
llm/provider/ollama
Package ollama
|
Package ollama |
|
llm/provider/openai
Package openai
|
Package openai |
|
logger
Package logger provides opinionated logging capabilities for the tapes system.
|
Package logger provides opinionated logging capabilities for the tapes system. |
|
merkle
Package merkle is an implementation of a Merkel DAG
|
Package merkle is an implementation of a Merkel DAG |
|
rawequiv
Package rawequiv proves that re-reducing a captured turn's stored verbatim bytes reproduces the reduction the capture adapter computed live.
|
Package rawequiv proves that re-reducing a captured turn's stored verbatim bytes reproduces the reduction the capture adapter computed live. |
|
seed
Package seed seeds demo data by replaying bundled capture corpora through the normal ingest write path.
|
Package seed seeds demo data by replaying bundled capture corpora through the normal ingest write path. |
|
sessions
Package sessions provides the shared types and logic for building a per-session summary from a chain of merkle nodes.
|
Package sessions provides the shared types and logic for building a per-session summary from a chain of merkle nodes. |
|
skill
Package skill provides LLM-powered extraction of reusable patterns from tapes sessions, outputting Claude Code SKILL.md files.
|
Package skill provides LLM-powered extraction of reusable patterns from tapes sessions, outputting Claude Code SKILL.md files. |
|
spanembed
Package spanembed embeds the span projection for semantic search.
|
Package spanembed embeds the span projection for semantic search. |
|
sse
Package sse provides a minimal, purpose-built SSE (Server-Sent Events) tee-reader for use in the tapes proxy.
|
Package sse provides a minimal, purpose-built SSE (Server-Sent Events) tee-reader for use in the tapes proxy. |
|
storage
Package storage
|
Package storage |
|
storage/postgres
Package postgres
|
Package postgres |
|
tapesoapi
Package tapesoapi parses, aggregates, and compiles OpenAPI v3 documents.
|
Package tapesoapi parses, aggregates, and compiles OpenAPI v3 documents. |
|
tapesoapi/gosource
Package gosource reads doc comments out of Go source so reflected schemas can carry prose.
|
Package gosource reads doc comments out of Go source so reflected schemas can carry prose. |
|
tapesoapi/oasfiber
Package oasfiber populates a tapesoapi parser as Fiber routes are registered.
|
Package oasfiber populates a tapesoapi parser as Fiber routes are registered. |
|
tapesoapi/v3.0
Package v30 holds the OpenAPI 3.0 reference documents this module is tested against.
|
Package v30 holds the OpenAPI 3.0 reference documents this module is tested against. |
|
tapesoapi/v3.1
Package v31 holds the OpenAPI 3.1 reference documents this module is tested against.
|
Package v31 holds the OpenAPI 3.1 reference documents this module is tested against. |
|
telemetry
Package telemetry provides anonymous usage tracking for the tapes CLI using PostHog.
|
Package telemetry provides anonymous usage tracking for the tapes CLI using PostHog. |
|
update
Package update provides a best-effort mechanism for checking whether a newer version of tapes is available.
|
Package update provides a best-effort mechanism for checking whether a newer version of tapes is available. |
|
utils
Package utils provides bespoke, one off utils that don't make sense to be their own package
|
Package utils provides bespoke, one off utils that don't make sense to be their own package |
|
Package proxy provides an LLM inference proxy that captures conversations to the immutable raw_turns log.
|
Package proxy provides an LLM inference proxy that captures conversations to the immutable raw_turns log. |
|
header
Package header provides header filtering for the tapes proxy.
|
Package header provides header filtering for the tapes proxy. |
|
worker
Package worker provides an asynchronous worker pool and utils for persisting conversation turns using the provided storage.Driver.
|
Package worker provides an asynchronous worker pool and utils for persisting conversation turns using the provided storage.Driver. |