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 tapes 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 tapes 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.
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:
tapes seed --demo
List captured sessions and their ids:
tapes sessions
Browse sessions and drill into a single session in the deck TUI:
tapes deck
Export a captured session as JSONL — the API's session→traces→spans projection
verbatim. tapes export is a thin client of GET /v1/sessions/{id}/export, so
it needs a running API (pass --api-target, or start one with tapes serve).
The full span tree is included by default; pass --detail traces for turn
headers only. Pass a full session id or its short prefix:
tapes export <session-id> --api-target http://127.0.0.1:8081 -o session.jsonl
tapes 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:
tapes 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
tapes start claude # or send any client at http://localhost:8080
tapes start launches the agent wired to the proxy and tags the session. 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. |
|
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
|
|
|
tapes
command
|
|
|
cmd
|
|
|
gen-openapi
command
Command gen-openapi converts the swaggo-generated Swagger 2.0 document (docs/swagger.json) into a clean OpenAPI 3.0.3 document written to api/openapi.yaml.
|
Command gen-openapi converts the swaggo-generated Swagger 2.0 document (docs/swagger.json) into a clean OpenAPI 3.0.3 document written to api/openapi.yaml. |
|
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/deck
Package deckcmder provides the deck command for session ROI dashboards.
|
Package deckcmder provides the deck command for session ROI dashboards. |
|
tapes/export
Package exportcmd provides the export subcommand: it downloads a captured session as JSONL from the running tapes API and writes it to stdout or a file.
|
Package exportcmd provides the export subcommand: it downloads a captured session as JSONL from the running tapes API and writes it to stdout or a file. |
|
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/inprocessapi
Package inprocessapi provides a shared helper for CLI subcommands that want to talk to the tapes API server over HTTP without requiring an external server.
|
Package inprocessapi provides a shared helper for CLI subcommands that want to talk to the tapes API server over HTTP without requiring an external server. |
|
tapes/search
Package searchcmder provides the search command for semantic search over sessions.
|
Package searchcmder provides the search command for semantic search over sessions. |
|
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/sessions
Package sessionscmder provides the `tapes sessions` command: a quick list of captured sessions and their ids, so other commands (export, search) have something to point at.
|
Package sessionscmder provides the `tapes sessions` command: a quick list of captured sessions and their ids, so other commands (export, search) have something to point at. |
|
tapes/skill
Package skillcmder provides the `tapes skill` CLI commands for generating, listing, and syncing agent skills from session data.
|
Package skillcmder provides the `tapes skill` CLI commands for generating, listing, and syncing agent skills from session data. |
|
tapes/start
Package startcmder provides the start command for launching tapes and agents.
|
Package startcmder provides the start command for launching tapes and agents. |
|
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 |
|
Package docs Code generated by swaggo/swag.
|
Package docs Code generated by swaggo/swag. |
|
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. |
|
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. |
|
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 |
|
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 |
|
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. |