Skip to content

getting-started.md

Latest commit

 

History

History
139 lines (93 loc) · 2.91 KB

getting-started.md

File metadata and controls

139 lines (93 loc) · 2.91 KB

Getting Started

This guide walks you through installing ct and using it to browse your Claude Code transcripts.

Prerequisites

  • Go 1.21+ — Required for installation
  • Claude Code — You need existing session transcripts in ~/.claude/projects/

Installation

From Source (Recommended)

go install github.com/robertguss/claude-transcripts@latest

This installs the ct binary to your $GOPATH/bin (usually ~/go/bin). Make sure this directory is in your PATH.

Build Locally

git clone https://github.com/robertguss/claude-transcripts.git
cd claude-transcripts
go build -o ct .

Verify Installation

ct --version

First Use

1. Check Your Projects

List all Claude Code projects with transcripts:

ct list

Output shows projects by their directory names:

my-web-app          3 sessions   Modified: 2h ago
backend-api         12 sessions  Modified: 1d ago
side-project        1 session    Modified: 3d ago

2. List Sessions in a Project

ct list my-web-app

Shows all sessions with metadata:

abc12345  "Add authentication flow"   45 messages  2h ago
def67890  "Fix database connection"   23 messages  1d ago

3. Convert to Markdown

Export a project's transcripts to readable markdown:

ct convert my-web-app -o ./transcripts

Creates markdown files with YAML frontmatter:

./transcripts/
└── my-web-app/
    ├── abc12345-add-authentication-flow.md
    └── def67890-fix-database-connection.md

4. Sync All Transcripts

For ongoing use, sync all projects incrementally:

ct sync -o ./transcripts

This converts all projects at once, skipping files that already exist. Use --prune to remove orphaned files:

ct sync -o ./transcripts --prune

5. Backup Your Transcripts

Create a backup of all your raw transcript files:

ct backup -o ~/backups/claude

This copies the entire ~/.claude/projects/ directory, preserving the original structure. Useful before system updates or for portable storage.

6. Launch the TUI

Browse all your transcripts in a full-screen interface:

ct

Navigation:

  • j/k or ↑/↓ — Move up/down
  • h/l or ←/→ — Switch panels
  • Enter — Select item
  • f — Toggle fullscreen preview
  • e — Open in editor
  • / — Search
  • q — Quit

Where Claude Code Stores Transcripts

Claude Code saves session data in:

~/.claude/projects/<hashed-directory-name>/
├── sessions-index.json    # Metadata for all sessions
└── <session-id>.jsonl     # Individual conversation logs

Each .jsonl file contains the raw conversation as JSON lines. The ct tool reads these files and converts them to human-readable markdown.

Next Steps