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
- Session Storage: Claude Code stores session data in
~/.claude/projects/<project>/ as JSONL files
- Conversion: Threads converts the JSONL session data to readable markdown format
- Persistence: The markdown is saved as a GitHub Gist with the
[Claude Thread] prefix
- 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:
GitHub CLI (recommended):
gh auth login
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