session-zoo

English | 中文

Save and sync your AI development sessions to GitHub.

session-zoo automatically discovers sessions from AI coding tools (Claude Code, Codex, etc.), generates AI summaries, and syncs everything to a GitHub repo — raw data preserved for cross-device migration, plus readable Markdown for review.

Features

• Auto-discover sessions from ~/.claude/ (Claude Code adapter built-in)
• AI Summarize using existing Claude/Codex CLI (no API key needed) or Anthropic API
• Git Sync raw JSONL + metadata + Markdown summaries to GitHub
• Cross-device restore — clone on a new machine, restore sessions to ~/.claude/ for /resume
• Tag & Search sessions by project, tool, date, or custom tags
• Extensible adapter pattern — easy to add support for new AI tools

Quick Start

Install

pip install session-zoo

Or install from source:

git clone https://github.com/AndsGo/session-zoo.git
cd session-zoo
pip install -e .

Setup

# Initialize
zoo init

# Set your GitHub repo for syncing (create an empty repo first)
zoo config set repo git@github.com:yourname/my-sessions.git

Basic Workflow

# Import sessions from Claude Code
zoo import

# List all sessions
zoo list

# View session details
zoo show <session-id>
zoo show <session-id> --markdown

# Generate AI summary (uses installed claude/codex CLI automatically)
zoo summarize <session-id>

# Tag sessions for organization
zoo tag <session-id> bugfix security

# Set or reset a session title (overrides auto-derived title)
zoo title <session-id> "Fix the login bug"
zoo title <session-id> --reset

# Sync everything to GitHub
zoo sync

Cross-Device Restore

On a new machine:

zoo init
zoo config set repo git@github.com:yourname/my-sessions.git
zoo clone      # Clone the session repo
zoo reindex    # Rebuild local index from repo
zoo restore    # Restore .jsonl files to ~/.claude/ for /resume

Commands

Session Titles

zoo list shows a Title column (full summary remains in zoo show <id>). Titles are resolved with this priority:

1. manual — set via zoo title <id> "..."
2. summary — parsed from **Title:** in the AI-generated summary (zoo summarize)
3. ai-title — Claude Code's native aiTitle record from the jsonl, written automatically as you chat
4. first-message — first user message, truncated; mirrors /resume's fallback

zoo import, zoo summarize, and zoo title all respect the priority — automated processes never overwrite a manual title. After upgrading from a previous version, run zoo title --backfill once to populate titles for existing sessions.

Cache Stats

zoo stats shows per-model token usage and prompt cache hit rates, aggregated across sessions (filter with --project, --tool, --since) or for a single session via zoo stats <id>. Hit rate = cache_read / (input + cache_read + cache_creation); ? means no input tokens were recorded.

Usage data is collected on zoo import, written to meta.json on zoo sync, and restored by zoo reindex. After upgrading from a previous version, run zoo stats --backfill once to compute usage for existing sessions.

Note: this release also fixes token double-counting (multi-block assistant messages were counted once per block), so total_tokens shrinks for most sessions and the next zoo import will mark them for re-sync. One-time cost.

Summarization Providers

zoo summarize supports multiple providers, auto-detected by priority:

1. claude-code — Uses installed claude -p CLI (no API key needed)
2. codex — Uses installed codex -q CLI (no API key needed)
3. api — Uses Anthropic API directly (requires zoo config set ai-key <key>)

# Auto-detect (uses whatever is available)
zoo summarize <id>

# Force a specific provider
zoo summarize --provider claude-code <id>
zoo summarize --provider api <id>

GitHub Repo Structure

your-sessions-repo/
├── raw/claude-code/my-project/
│   ├── <session-id>.jsonl          # Raw session data (preserved as-is)
│   └── <session-id>.meta.json     # Metadata (tags, summary, cwd)
└── sessions/my-project/2026-03-10/claude-code/
    └── <session-id>.md            # Readable Markdown summary

Adding Adapters

session-zoo uses an adapter pattern to support different AI tools. Currently supported:

• Claude Code (~/.claude/projects/)

To add a new adapter, implement discover(), parse(), and get_restore_path(). See CONTRIBUTING.md for details.

Requirements

• Python 3.12+
• Git
• (Optional) claude or codex CLI for summarization without API key

License

MIT