claude-thread-publisher

Claude Thread Publisher

Publish Claude Code conversation threads as beautiful static HTML pages hosted on GitHub Gists, with shareable permalinks via gistpreview.github.io.

Instructions

When to Use This Skill

Use this skill when the user asks to:

• Publish, share, or export a Claude Code conversation
• Create a shareable link for the current thread
• Delete a previously published thread
• Update an existing published thread

High-Level Workflow

Publishing a Thread

When the user wants to publish the current thread:

1. Check for GitHub Token:

   • Look for existing token in ~/.claude/thread-publisher/config.json
   • If missing, guide the user to create a GitHub PAT with gist scope
   • Store the token locally for future use

2. Locate Current Session:

   • Use session_locator.py to find the current Claude Code session JSONL file
   • Handle cases where no session is found gracefully

3. Generate Content:

   • Use render_thread.py to convert JSONL to:
     • Beautiful static HTML (index.html)
     • Normalized thread JSON (thread.json)
     • Metadata (metadata.json)

4. Publish to Gist:

   • Use publish_to_gist.py to create/update GitHub Gist with the three files
   • Use secret gists by default for privacy
   • Store mapping of thread hash → gist ID in local index

5. Provide Result:

   • Return the gistpreview permalink (e.g., https://gistpreview.github.io/?abcdef1234...)
   • Also provide the raw Gist URL for reference
   • Include brief confirmation and reminder that the link is live

Deleting a Published Thread

When the user wants to delete a published thread:

1. Locate Current Thread:

   • Use session_locator.py + render_thread.py to compute the current thread's hash
   • Look up the thread hash in the local index (~/.claude/thread-publisher/index.json)

2. Verify and Delete:

   • If mapping exists, use delete_gist.py to delete the corresponding GitHub Gist
   • Remove the entry from the local index
   • Confirm successful deletion to the user

3. Handle Missing Threads:

   • If no mapping exists, inform the user that no published link was found
   • Offer to list all published threads if they want to check

Updating a Published Thread

When the user wants to update an existing published thread:

1. Detect Changes:

   • Compute current thread hash and compare with stored version
   • If hash differs, the thread has been updated since last publication

2. Update Strategy:

   • By default, update the existing Gist (replace contents)
   • This preserves the same permalink URL
   • Update the local index with new timestamp

3. Provide Updated Link:

   • Return the same permalink (URL unchanged)
   • Confirm that the content has been updated

Script Usage Patterns

Session Location

python ${CLAUDE_PLUGIN_ROOT}/skills/claude-thread-publisher/scripts/session_locator.py --mode current

Returns JSON with session file path and project information.

Thread Rendering

python ${CLAUDE_PLUGIN_ROOT}/skills/claude-thread-publisher/scripts/render_thread.py \
  --input /path/to/session.jsonl \
  --output-html /tmp/thread.html \
  --output-json /tmp/thread.json \
  --metadata /tmp/metadata.json \
  --project-path /current/project \
  --session-file /path/to/session.jsonl

Gist Publishing

python ${CLAUDE_PLUGIN_ROOT}/skills/claude-thread-publisher/scripts/publish_to_gist.py \
  --html /tmp/thread.html \
  --thread-json /tmp/thread.json \
  --metadata /tmp/metadata.json \
  --project-path /current/project \
  --session-file /path/to/session.jsonl

Gist Deletion

python ${CLAUDE_PLUGIN_ROOT}/skills/claude-thread-publisher/scripts/delete_gist.py \
  --thread-hash <hash>  # or --session-file /path/to/session.jsonl

Key Features

HTML Rendering

• Beautiful dark theme optimized for code display
• Responsive design that works on mobile and desktop
• Syntax highlighting for code blocks
• Clear separation between user, assistant, and system messages
• One-click "copy link" functionality
• Metadata display (thread hash, generation time, message count)

GitHub Integration

• Uses GitHub Personal Access Tokens with gist scope only
• Creates secret (private) gists by default for privacy
• Supports both creation and updates of gists
• Maintains local index for tracking published threads
• Graceful handling of authentication and API errors

Thread Management

• Content-based hashing to detect thread changes
• Supports re-publishing updated threads
• Comprehensive deletion capabilities
• Orphaned gist cleanup functionality

File Structure

claude-thread-publisher/
├── SKILL.md                    # This file
├── examples.md                 # Example prompts
├── scripts/
│   ├── session_locator.py      # Find current Claude Code session
│   ├── render_thread.py        # Convert JSONL to HTML/JSON
│   ├── publish_to_gist.py      # Create/update GitHub Gists
│   └── delete_gist.py          # Delete Gists and manage cleanup
└── templates/                  # (reserved for future HTML templates)

Configuration

The skill stores configuration in ~/.claude/thread-publisher/:

• config.json: GitHub token and preferences
• index.json: Mapping of thread hashes to Gist IDs

Example Configuration

{
  "github_token": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "gists_private_by_default": true
}

Example Index Entry

{
  "threads": {
    "a1b2c3d4e5f6...": {
      "gist_id": "abcdef1234567890...",
      "gist_url": "https://gist.github.com/abcdef1234567890...",
      "last_published_at": "2024-01-01T12:00:00Z",
      "project_path": "/home/user/my-project",
      "session_file": "/home/user/.claude/projects/abc/sessions/def.jsonl",
      "title": "Implement user authentication feature"
    }
  }
}

Security and Privacy

• Local Token Storage: GitHub PAT is stored locally on user's machine only
• Gist Privacy: Creates secret (private) gists by default
• Content Control: Only publishes the specific thread content user requests
• No External Services: Relies only on GitHub's official Gist API
• Token Scope: Requires only gist scope (minimal permission)

Error Handling

• Missing Session: Gracefully handles cases where no current session can be found
• Authentication Issues: Guides users through PAT setup when missing
• API Failures: Provides clear error messages for GitHub API issues
• File I/O Errors: Handles file permission and path issues gracefully
• Network Issues: Implements timeouts and retry logic where appropriate

Troubleshooting

Common Issues

1. "No session file found"

   • User may be in a directory without a Claude Code project
   • Check if ~/.claude/projects/ exists and contains relevant project
   • Try explicitly specifying session file path

2. "GitHub token required"

   • User needs to create a PAT at github.com/settings/tokens
   • Token must have gist scope
   • Token will be stored locally after first use

3. "Gist creation failed"

   • Check GitHub API status
   • Verify token has correct permissions
   • Check network connectivity

4. "Thread hash mismatch"

   • Thread content has changed since last publication
   • This is normal when updating threads
   • Skill will handle updating the gist

Examples

Basic Publishing

"Publish this Claude Code conversation as a shareable link."

Updating

"Update the published link for this thread with the new messages."

Deleting

"Delete the public link you created for this conversation."

Listing

"Show me all the threads I've published."

Dependencies

• Python 3.7+
• requests library for HTTP requests
• Standard library modules: json, pathlib, datetime, argparse, hashlib

Best Practices

• Always confirm with user before deleting published content
• Use descriptive thread titles based on first user message
• Keep gists private by default to respect user privacy
• Provide both gistpreview permalink and direct gist URL
• Maintain local index for thread management
• Handle API errors gracefully with user-friendly messages