KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

tapes

★ 268 Open GitHub ↗

Transparent telemetry collector for hi-fidelity agent traces

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>

 <img width="1280" height="640" alt="Tapes logo" src="https://github.com/user-attachments/assets/133642d6-88e6-4f96-be7a-e6e109a59e5d" />
 <code>tapes</code>
</h1>

Transparent agentic telemetry and instrumentation for content-addressable LLM interactions.
 
 <a href="#about">About</a>
 ·
 <a href="https://tapes.dev/">Download</a>
 ·
 <a href="https://tapes.dev/docs/">Documentation</a>
 ·
 <a href="CONTRIBUTING.md">Contributing</a>

·
 <a target="_blank" href="https://github.com/papercomputeco/tapes/releases/latest">
 <img src="https://img.shields.io/github/v/release/papercomputeco/tapes?style=flat-square">
 </a>
 ·
 <a target="_blank" href="https://github.com/papercomputeco/tapes/actions/workflows/ci.yaml">
 <img src="https://img.shields.io/github/actions/workflow/status/papercomputeco/tapes/ci.yaml?style=flat-square">
 </a>

`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`:

```bash
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):

```bash
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`):

```bash
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):

```bash
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`](https://github.com/papercomputeco/tapesctl):

```bash
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:

```bash
tapesctl seed --tapes-url http://localhost:8081
```

List captured sessions and their ids:

```bash
tapesctl sessions list --tapes-url http://localhost:8081
```

Browse sessions and drill into a single session in the deck TUI:

```bash
```

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:

```bash
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:

```bash
tapesctl search "explain the retry logic"
```

**Ready for the real thing?** Clear the demo data and point your own agent at
the proxy:

```bash
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](https://tapes.dev/docs/) for
Claude Code, OpenCode, and more.

tapes

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README