threads

Threads

Save and manage Claude Code sessions as GitHub Gists.

Threads is a Claude Code plugin that lets you persist your coding sessions to GitHub Gists, enabling you to save, list, and restore session context across different Claude Code sessions.

Installation

From Plugin Marketplace

/plugin marketplace add mpuig/threads
/plugin install threads

From Source (Development)

git clone https://github.com/mpuig/threads
cd threads
uv sync
uv run th --help

Usage

Save a Session

Save your current Claude Code session as a GitHub Gist:

th save --name "feature-auth" --description "JWT authentication implementation"

Options:

• --name, -n - Thread name (auto-generated if not provided)
• --description, -d - Description for the gist
• --public - Make the gist public (default: secret)

List Saved Threads

View all your saved thread sessions:

th list

Options:

• --limit, -l - Maximum number of threads to show (default: 10)
• --filter, -f - Filter threads by keyword
• --json - Output as JSON

Load a Thread

Restore a previous session's context:

th open <gist-id>
th open https://gist.github.com/user/abc123def

Context Injection

The th prime command is automatically run on session start to show available commands and recent threads:

th prime

How It Works

1. Session Storage: Claude Code stores session data in ~/.claude/projects/<project>/ as JSONL files
2. Conversion: Threads converts the JSONL session data to readable markdown format
3. Persistence: The markdown is saved as a GitHub Gist with the [Claude Thread] prefix
4. Restoration: When loading a thread, the markdown content is output for Claude to ingest

Requirements

• Python 3.10+
• GitHub CLI (gh) authenticated, or GITHUB_TOKEN environment variable

GitHub Authentication

Threads uses the GitHub API to manage gists. You can authenticate using either:

1. GitHub CLI (recommended):

   gh auth login
   

2. Environment variable:

   export GITHUB_TOKEN=your_token_here
   

Plugin Configuration

The plugin automatically configures a SessionStart hook to run th prime when starting a new Claude Code session.

Hook Configuration (.claude-plugin/plugin.json)

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "th prime"
          }
        ]
      }
    ]
  }
}

Local Storage

Threads stores local configuration in .threads/ directory:

• config.json - Local configuration
• threads.json - Index of saved threads for the project

Troubleshooting

"GitHub authentication required"

The gh CLI is not authenticated or GITHUB_TOKEN is not set.

# Option 1: Authenticate via gh CLI (recommended)
gh auth login

# Option 2: Set environment variable
export GITHUB_TOKEN=your_personal_access_token

To create a personal access token, visit GitHub Settings > Tokens and create a token with gist scope.

"No active session found"

This error occurs when Threads cannot find a Claude Code session for the current directory.

Causes:

• You're not in a directory where you've used Claude Code before
• Claude Code stores sessions in ~/.claude/projects/, and no matching project exists

Solution: Run th save from within a project directory where you have an active Claude Code session.

"No threads found" when running th list

You haven't saved any threads yet, or your gists don't have the [Claude Thread] prefix.

Solution: Save your first thread with th save --name "my-first-thread".

Thread not loading correctly with th open

Ensure you're using a valid gist ID. You can use either:

• Short ID: th open abc123def
• Full URL: th open https://gist.github.com/username/abc123def

Development

# Clone and install
git clone https://github.com/mpuig/threads
cd threads
uv sync

# Run tests
uv run pytest

# Run CLI
uv run th --help

See CONTRIBUTING.md for development guidelines.

License

MIT