claude-explore

Ephemeral workspace manager for exploring GitHub repositories with Claude Code.

Overview

claude-explore makes it easy to explore GitHub repositories with Claude Code without cluttering your workspace. It automatically:

• Clones repositories to a temporary workspace (~/.claude-explore/)
• Launches Claude Code in the right directory (including subdirectories)
• Tracks your exploration sessions
• Cleans up old workspaces automatically

Features

• Context-agnostic: Run from any terminal, no need to cd first
• Subdirectory support: Explore specific parts of a repository
• Session tracking: Resume previous explorations
• Auto-cleanup: Remove old workspaces based on age
• Disk usage monitoring: Track workspace sizes
• No manual setup: Works out of the box

Installation

# Install using uv (recommended)
uv tool install claude-explore

# Or using pip
pip install claude-explore

Quick Start

# Explore a repository
claude-explore explore https://github.com/user/repo
claude-explore explore --skip-permissions https://github.com/user/repo

# Explore a subdirectory
claude-explore explore https://github.com/user/repo/tree/main/src/core

# List active workspaces
claude-explore list

# Clean up old workspaces (older than 7 days)
claude-explore clean

# Get workspace info
claude-explore info

Usage

Explore a Repository

# Basic usage
claude-explore explore https://github.com/anthropics/anthropic-sdk-python

# Explore a specific subdirectory
claude-explore explore https://github.com/anthropics/anthropic-sdk-python/tree/main/src/anthropic

# Skip git pull if workspace exists
claude-explore explore --no-update https://github.com/user/repo

# Launch Claude with --dangerously-skip-permissions
claude-explore explore --skip-permissions https://github.com/user/repo

# Pass additional Claude arguments
claude-explore explore --claude-args "--debug --verbose" https://github.com/user/repo

# Combine multiple options
claude-explore explore --skip-permissions --no-update https://github.com/user/repo

Supported URL formats:

• https://github.com/user/repo
• https://github.com/user/repo.git
• git@github.com:user/repo.git
• https://github.com/user/repo/tree/branch/path/to/subdir

List Sessions

# List all exploration sessions
claude-explore list

# Show only recent sessions (last 7 days)
claude-explore list --days 7

Output example:

Found 3 session(s):

  a1b2c3d4
    Repository: user/awesome-repo
    URL: https://github.com/user/awesome-repo
    Subdirectory: src/core
    Last used: 2025-11-14T10:30:00
    Created: 2025-11-13T15:20:00

  e5f6g7h8
    Repository: org/another-repo
    URL: https://github.com/org/another-repo
    Last used: 2025-11-12T14:15:00
    Created: 2025-11-12T14:15:00

Resume a Session

# Resume a previous exploration (use ID from 'list' command)
claude-explore resume a1b2c3d4

# Resume with permissions skipped
claude-explore resume --skip-permissions a1b2c3d4

# Resume with additional Claude args
claude-explore resume --claude-args "--debug" a1b2c3d4

Clean Up Workspaces

# Remove workspaces not used in 7 days (default)
claude-explore clean

# Remove workspaces not used in 30 days
claude-explore clean --days 30

# Remove ALL workspaces (with confirmation)
claude-explore clean --all

Workspace Information

# Show workspace manager info and disk usage
claude-explore info

Output example:

Claude Explore Workspace Manager
========================================
Base directory: /home/user/.claude-explore
Workspaces directory: /home/user/.claude-explore/workspaces
Sessions file: /home/user/.claude-explore/sessions.json

Active workspaces: 3
Total disk usage: 450.5 MB

How It Works

Directory Structure

~/.claude-explore/
├── workspaces/
│   ├── a1b2c3d4/          # Hashed workspace ID (user/repo)
│   │   ├── .git/
│   │   ├── src/
│   │   └── ...
│   └── e5f6g7h8/
│       └── ...
└── sessions.json          # Session metadata and timestamps

Workspace IDs

Each repository gets a unique workspace ID based on user/repo:

• Same repository always gets the same workspace ID
• Different subdirectories of the same repo share the same workspace
• This avoids duplicate clones and saves disk space

Session Tracking

The sessions.json file tracks:

• Workspace ID
• Repository name and URL
• Subdirectory (if exploring a subdir)
• Created and last used timestamps

This enables:

• Resuming previous explorations
• Automatic cleanup of old workspaces
• Usage tracking and statistics

Command Reference

claude-explore explore <repo_url>

Explore a GitHub repository.

Arguments:

• repo_url: GitHub repository URL (HTTPS or SSH)

Options:

• --no-update: Skip git pull if workspace exists
• --workspace-dir PATH: Use custom workspace base directory
• --skip-permissions: Launch Claude with --dangerously-skip-permissions
• --claude-args TEXT: Additional arguments to pass to Claude (e.g., "--debug --verbose")

claude-explore list

List active exploration sessions.

Options:

• --days N: Show only sessions from last N days
• --workspace-dir PATH: Use custom workspace base directory

claude-explore resume <workspace_id>

Resume a previous exploration session.

Arguments:

• workspace_id: Workspace identifier (from list command)

Options:

• --workspace-dir PATH: Use custom workspace base directory
• --skip-permissions: Launch Claude with --dangerously-skip-permissions
• --claude-args TEXT: Additional arguments to pass to Claude (e.g., "--debug --verbose")

claude-explore clean

Clean up old workspaces.

Options:

• --days N: Remove workspaces not used in N days (default: 7)
• --all: Remove all workspaces (prompts for confirmation)
• --workspace-dir PATH: Use custom workspace base directory

claude-explore info

Show workspace manager information and disk usage.

Options:

• --workspace-dir PATH: Use custom workspace base directory

Advanced Usage

Shell Aliases

Create convenient aliases for your common workflows:

# Add to ~/.bashrc or ~/.zshrc

# Always skip permissions when exploring
alias cex='claude-explore explore'
alias cex-skip='claude-explore explore --skip-permissions'

# Explore with debug mode enabled
alias cex-debug='claude-explore explore --claude-args "--debug"'

# Explore without updating (faster for repeat visits)
alias cex-cached='claude-explore explore --no-update'

Usage:

# Use your alias
cex https://github.com/user/repo
cex-skip https://github.com/user/repo

# Expands to: claude-explore explore https://github.com/user/repo

Custom Workspace Directory

Use a different base directory for workspaces:

# Use custom directory
claude-explore explore --workspace-dir /mnt/data/claude-workspaces https://github.com/user/repo

# All commands support this option
claude-explore list --workspace-dir /mnt/data/claude-workspaces
claude-explore clean --workspace-dir /mnt/data/claude-workspaces

Workflow Examples

Quick repository exploration:

# One-liner to explore a repo you found
claude-explore explore https://github.com/user/interesting-repo
# Claude opens, ask your questions
# Exit when done

# With your alias (always skip permissions)
cex-skip https://github.com/user/interesting-repo

Regular cleanup routine:

# Weekly cleanup (cron job or manual)
claude-explore clean --days 14

Check disk usage:

# See how much space workspaces are using
claude-explore info

Comparison with Manual Workflow

Without claude-explore:

cd ~/temp
git clone https://github.com/user/repo
cd repo/src/core
claude
# Later: manually clean up ~/temp

With claude-explore:

claude-explore explore https://github.com/user/repo/tree/main/src/core
# Automatic cleanup after 7 days

Requirements

• Python 3.10+
• Git
• Claude Code (claude command must be available)

Development

# Clone the repository
git clone https://github.com/user/claude-explore
cd claude-explore

# Install in development mode
uv tool install -e .

# Run tests
pytest tests/

License

MIT

Related Tools

• llmd - Generate LLM context from repositories
• cc-conversation-search - Search Claude Code conversations

Tips

• Workspaces are shallow clones (--depth=1) to save disk space
• The same repository always uses the same workspace (no duplicates)
• Subdirectory explorations share the parent repo's workspace
• Use --no-update if you're working with a specific commit/state
• Set up a weekly cron job to run claude-explore clean