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

```bash
/plugin marketplace add mpuig/threads
/plugin install threads
```

### From Source (Development)

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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)**:
   ```bash
   gh auth login
   ```

2. **Environment variable**:
   ```bash
   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`)

```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.

```bash
# 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](https://github.com/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

```bash
# 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](CONTRIBUTING.md) for development guidelines.

## License

MIT