transcript-archive

claude-code-research-transcript-hook

Archive Claude Code conversations with research-grade metadata using the IDW2025 reproducibility framework.

Features

• Research-grade metadata: Captures the Three Ps (Prompt/Process/Provenance) for reproducibility
• Rich statistics: Token counts, costs, tool usage, thinking blocks, artifacts
• Dual archive modes: Global (~/.claude/transcripts/) or per-project (./ai_transcripts/)
• CATALOG.json: Central index of all sessions with metadata completion status
• Plan file archiving: Automatically captures plan files from planning sessions
• Interactive /transcript command: Asks clarifying questions to capture context
• Silent auto-archive: Hook-based archiving with automatic metadata extraction
• HTML output: Browsable transcripts via claude-code-transcripts

Installation

As a Claude Code plugin (recommended)

/plugin marketplace add Denubis/claude-code-research-transcript-hook
/plugin install transcript-archive@transcript-archive-marketplace

This installs the /transcript command and the transcript archive skill automatically.

CLI tool only

# Global install (for hooks)
uv tool install git+https://github.com/Denubis/claude-code-research-transcript-hook

# Per-repo with uvx
uvx --from git+https://github.com/Denubis/claude-code-research-transcript-hook claude-research-transcript archive --local

# Using pipx
pipx install git+https://github.com/Denubis/claude-code-research-transcript-hook

# From source
git clone https://github.com/Denubis/claude-code-research-transcript-hook
cd claude-code-research-transcript-hook
uv tool install .

Setup

Enable auto-archive for a project (optional)

To automatically archive transcripts when Claude stops, copy the example hook to your project:

cp example-hooks/settings.local.json /path/to/your/project/.claude/

This archives to ./ai_transcripts/ in the project directory. Sessions archived via hooks are flagged as needs_review: true for later metadata completion.

Usage

Interactive archiving with /transcript

In any Claude Code session, run:

/transcript

Claude will:

1. Analyze the conversation and draft metadata
2. Ask clarifying questions about context that won't be obvious in 6 months
3. Present the Three Ps (Prompt/Process/Provenance) for your confirmation
4. Archive with complete metadata

Command-line options

claude-research-transcript <subcommand> [OPTIONS]

Subcommands:
  archive      Archive a single session (what Stop hooks call)
  init         Initialize transcript archiving for a repo
  status       Report archived / needs-review / unarchived counts
  bulk         Archive every unarchived session
  update       Edit metadata on an existing archive
  regenerate   Re-render HTML/PDF/markdown from the raw backup
  clean        Deduplicate, migrate legacy, repair indexes

Common `archive` options:
  --title TITLE    Title for the transcript
  --retitle        Force regenerate title/rename directory
  --force          Regenerate even if transcript unchanged
  --local          Archive to ./ai_transcripts/ instead of ~/.claude/transcripts/
  --output DIR     Custom output directory
  --quiet          Suppress error messages

Input: JSON payload on stdin with transcript_path and session_id
       (automatically provided by Claude Code Stop hooks)

Archive locations

• Global archive (default): ~/.claude/transcripts/{project-path}/
• Project archive (--local): ./ai_transcripts/
• Custom (--output): Any directory you specify

Archive Structure

~/.claude/transcripts/                          # Global archive
├── CATALOG.json                                # Central index
└── -home-user-my-project/                      # Project (CC path encoding)
    ├── CATALOG.json                            # Project index
    └── 2026-01-14-implementing-feature/
        ├── index.html                          # Browsable transcript
        ├── session.meta.json                   # Rich metadata
        ├── raw-transcript.jsonl                # Original transcript
        └── plans/                              # Plan files (if any)
            └── plan-file.md

Metadata Schema (session.meta.json)

Each archived session includes:

• Session info: ID, timestamps, duration
• Project info: Name, directory
• Model info: Provider, model ID
• Statistics: Turns, messages, tokens, costs, tool calls, thinking blocks
• Artifacts: Files created, modified, referenced
• Relationships: Session continuations, references
• Three Ps: Prompt summary, process summary, provenance summary
• Archive info: Timestamp, file hash, needs_review flag

The IDW2025 Framework

This tool implements the Three Ps framework for research reproducibility: