tapes

Browsing Session History

Every conversation captured through the proxy or ingest is derived into sessions, traces, and spans. This guide covers finding a past session, browsing its turns, and exporting its projection as JSONL.

Prerequisites

History Guide

Step 1: Start the API server

The API server reads from the same Postgres database the proxy writes to:

tapes serve --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable"

Run tapes init in a project directory to create a local .tapes/ folder for project-specific config (Postgres DSN, embedding model, provider preset).

Step 2: Browse sessions in Deck

Open the Deck TUI to see recent sessions with cost and token metrics, then drill into one to step through its turns:

tapes deck --since 720h

See the Deck guide for navigation and filtering.

Step 3: Find a session by meaning

Use semantic search to find the turn where something happened. Each hit carries its session context. See the Search guide for setup:

tapes search "logging configuration"

Add --quiet to print only the matching session IDs, one per line — handy for piping into tapes export or tapes skill generate.

Step 4: Inspect a session's turns

Fetch a session's turns as traces with their nested spans directly from the API:

curl http://localhost:8081/v1/sessions/<session-id>/traces

See the Inspect reference for the full read surface, including the per-span payload drill-in.

Step 5: Export a session

Export a captured session as JSONL — the API's session→traces→spans projection verbatim. tapes export is a thin client of the API, so it needs a running server:

# Whole session (traces with their full span trees)
tapes export <session-id> --api-target http://127.0.0.1:8081 -o session.jsonl

# Turn headers only, no spans
tapes export <session-id> --detail traces

See the tapes export reference for the detail levels and flags.

Common Workflows

Search, then export

Pipe a search hit straight into an export: tapes export $(tapes search "auth bug" --quiet --top 1) --api-target http://127.0.0.1:8081 -o auth.jsonl.

Reviewing a run

Open a session in Deck to review its turns, token spend, and tool calls before sharing or archiving the transcript.

Project-specific contexts

Use tapes init in different project directories to tag captured sessions per project, then filter by project in Deck or the API.

Next Steps

Combine history browsing with semantic search to find relevant sessions fast. See the Search guide to search your conversation history by meaning.