Claude Transcripts documentation
Self-hosted history for Claude Code sessions. A hook records every session to your own CouchDB and S3-compatible storage; a web API serves it back to a web UI, a CLI and agents. Nothing leaves your machine unless you point it at services elsewhere.
Work in progress, not tested as ready for use. Breaking changes land without notice, stored data may need discarding between versions, and there is no auth: it assumes one user on one trusted machine.
curl -fsSL https://raw.githubusercontent.com/vredchenko/claude-transcripts/main/install.sh | sh
| To... | Read |
|---|---|
| install it | Installation |
| change ports, stores, feature flags | Configuration |
| wire the hook by hand | Hook setup |
| use the CLI | CLI reference |
| back up, restore, mirror | Migrations, export and import, Mirrors |
| work on the code | Getting started (development) |
| understand how it fits together | Architecture, ADRs |
The same tree is published at vredchenko.github.io/claude-transcripts/docs and served by every instance at /docs.
Getting started
Install it, point it at your stores, and record your first session.
Development
Working on Claude Transcripts itself: setup, conventions, tests, automation.
Operations
Running and shipping it: releases, containers, migrations, logs.
Reference
Per-component and per-surface detail — the codebase as documented.
Design & specification
What the system is meant to be, and the reasoning behind it.
Decisions (ADRs)
One record per architectural decision, in the order they were taken.
- Architecture Decision Records
- 1. Record architecture decisions
- 2. Single combined container serves the API and the SPA
- 3. Vendor-neutral S3 via Bun's S3 client; drop MinIO and rclone
- 4. Bun workspace monorepo; the hook ships as a standalone plugin
- 5. Tag-driven image releases
- 6. Webui consumes shared workspace types directly; no OpenAPI client codegen
- 7. CouchDB as the primary store
- 8. Garage as the S3 object store
- 9. Meilisearch for search (Phase 2)
- 10. Claude-Code-specific scope (not a generic agent-session logger)
- 11. Read CouchDB attachments over HTTP, not nano's attachment.get
- 12. GitHub Actions + GHCR for releases
- 13. S3 is the transcript's durable home; the CouchDB attachment is opt-in
- 14. Transcripts live in S3 only — CouchDB attachment support removed
- 15. Tiered architecture (Tier 1 / 2 / 3)
- 16. The webapi is the sole I/O gateway and stability column
- 17. Hooks and actions are decoupled (many-to-many)
- 18. Application/operational logs go to CouchDB (separate database)
- 19. OpenAPI spec is the source of truth; clients are generated
- 20. Bundled backing services default to no auth
- 21. Self-built CouchDB migrations (up/down + views + export/import)
- 22. / serves a machine-readable app manifest (agent entrypoint)
- 23. Lockstep versioning; components built separately, then combined into one image
- 24. Mirror third-party backing-service images to the container registry
- 25. Claude Code compatibility is a generated, structured definition
- 26. A single main branch
- 27. Full-content chunks in CouchDB (per-turn content, not just byte ranges)
- 28. External vs bundled Meilisearch
- 29. The recall policy is config-driven and injected at session start
- 30. Kubernetes deploy, generated from the app model
- 31. Fossil as bundled infrastructure, built from source