claudetree

Run multiple Claude Code sessions in parallel — each in its own isolated git worktree.

Tip: You can use ct as a shorthand for claudetree in all commands.

Why claudetree?

Claude Code is powerful, but it runs one session at a time in a single directory. What if you need to work on multiple issues simultaneously? Or delegate entire tasks to Claude without manual intervention?

claudetree solves this by combining git worktrees with automated Claude Code orchestration.

Key Benefits

Benefit	Description
Multi-session Management	Run multiple Claude sessions in parallel, each working on different issues
Isolated Workspaces	Each task gets its own git worktree — no branch conflicts, no context pollution
Fire and Forget	Just pass a GitHub issue URL and Claude handles the rest: read code, implement, test, commit, and create PR
Web Dashboard	Monitor all sessions in real-time with a visual UI — track progress, view logs, manage sessions
Automatic Workflow	Claude automatically commits changes and creates PRs when work is complete
Independent Context	Each Claude session maintains its own context, preventing cross-task interference

Use Cases

Parallel Bug Fixes: Work on multiple bug fixes simultaneously
Feature Development: Delegate feature implementation to Claude while you focus on architecture
Code Reviews: Let Claude implement changes while you review other PRs
Batch Processing: Queue up multiple issues and let Claude work through them

Important: Token Usage Warning

claudetree delegates entire sessions to Claude Code, which means:

High token consumption: Each session runs autonomously, making multiple API calls
Cost awareness: A single issue resolution can consume thousands of tokens
Recommended for: Teams with Claude Pro/Team plans or sufficient API credits
Monitor usage: Use ct status to track token usage and costs per session
Budget control: Use --max-cost to automatically stop sessions that exceed a cost limit

Consider using --no-session flag to create worktrees without starting Claude if you want manual control.

How It Works

Your Project (e.g., my-web-app/)
├── .claudetree/              ← Created by `ct init`
│   ├── config.json
│   ├── sessions.json
│   └── events/               ← Session logs
├── .worktrees/               ← Worktrees live here
│   ├── issue-42-fix-login/   ← Claude works here
│   └── issue-55-add-auth/    ← Another Claude works here
├── src/
└── ...

The workflow is simple:

You have a project with GitHub issues
Run ct start <issue-url> — claudetree creates a worktree and starts Claude
Claude reads the issue, implements the solution, runs tests, commits, and creates a PR
Monitor progress via CLI (ct status) or web dashboard (ct web)

Installation

npm install -g @claudetree/cli
# or
pnpm add -g @claudetree/cli

For development:

git clone https://github.com/wonjangcloud9/claude-tree.git
cd claude-tree
pnpm install && pnpm build
cd packages/cli && pnpm link --global

Quick Start

Step 1: Initialize in your project

cd ~/projects/my-web-app    # Go to YOUR project
ct init                     # Initialize claudetree

Step 2: Set up GitHub token

export GITHUB_TOKEN="ghp_your_token_here"

Step 3: Start working on an issue

# From GitHub issue URL — Claude starts automatically
ct start https://github.com/you/my-web-app/issues/42

# Claude will:
# 1. Create a worktree and branch
# 2. Read the issue description
# 3. Implement the solution
# 4. Run tests
# 5. Commit and create a PR

Step 4: Monitor progress

ct status           # CLI status view with progress bar & cost
ct status -w        # Watch mode (auto-refresh)
ct log abc123       # View session events
ct log abc123 -f    # Follow mode (live tailing)
ct stats            # Cost analytics and success rate
ct web              # Web dashboard at http://localhost:3000

Status output includes:

Session progress: ●─●─◉─○─○ Implementing
Token usage: 12,345 in / 3,456 out
Cost tracking: $0.1234

CLI Commands

Command	Description
`ct init`	Initialize claudetree in your project
`ct start <issue>`	Start a Claude session for a GitHub issue
`ct status`	Show all session statuses with progress & cost
`ct stats`	Session analytics: cost, tokens, success rate
`ct log <session>`	View session events (supports `-f` follow mode)
`ct stop [id]`	Stop a session
`ct resume <id>`	Resume a paused session
`ct list`	List all worktrees
`ct batch [issues]`	Process a list of issues in parallel
`ct auto`	Auto-fetch open issues with conflict detection
`ct chain [issues]`	Run issues sequentially (dependency order)
`ct config`	View or modify config (`ct config set github.owner myorg`)
`ct export`	Generate session report (`ct export -o report.md`)
`ct web`	Launch web dashboard at localhost:3000
`ct clean`	Remove finished worktrees
`ct doctor`	Verify setup: Node, Git, Claude CLI, GitHub
`ct inspect <id>`	Detailed session info (tokens, cost, progress, tags)
`ct cost`	Cost analytics with daily breakdown and budget monitoring
`ct tag <id> add/remove <tags>`	Add or remove tags from a session
`ct rerun <id>`	Rerun a failed/completed session
`ct cleanup`	Smart batch cleanup of finished sessions + worktrees

Start Options

ct start <issue> [options]

Options:
  -p, --prompt <prompt>      Custom prompt for Claude
  -s, --skill <skill>        Activate skill (tdd, review)
  -T, --template <template>  Session template (bugfix, feature, refactor, review)
  -b, --branch <branch>      Custom branch name
  -t, --token <token>        GitHub token
  --max-cost <cost>          Budget limit in USD (auto-stops if exceeded)
  --lint <command>           Run lint after session (e.g., "npm run lint")
  --gate                     Fail session if lint fails
  --no-session               Create worktree only (no Claude)

Examples

# Full automation — Claude does everything
ct start https://github.com/you/repo/issues/42

# Just create worktree, run Claude manually later
ct start 42 --no-session

# With TDD workflow (test first, then implement)
ct start 42 --skill tdd

# With budget limit ($0.50 max)
ct start 42 --max-cost 0.50

# With lint gate (fail if lint fails)
ct start 42 --lint "npm run lint" --gate

# Using a template
ct start 42 --template bugfix

# Full options
ct start 42 -s tdd --max-cost 1.00 --lint "npm run lint" --gate

Configuration

After ct init, edit .claudetree/config.json:

{
  "worktreeDir": ".worktrees",
  "github": {
    "owner": "your-username",
    "repo": "your-repo"
  }
}

Set GITHUB_TOKEN environment variable for GitHub API access.

Web Dashboard

Monitor all sessions in real-time from the web dashboard.

ct web    # http://localhost:3000

Features

Session List (Main Page)

All active sessions displayed as cards
Color-coded by status (running/pending/completed/failed)
Protected sessions (develop/main) cannot be deleted

Session Detail Page

Panel	Description
Terminal Output	Real-time Claude output streaming
Timeline	Work history (file changes, commits, tests)
Tool Approvals	Tools used by Claude (Read, Write, Bash, etc.)
Code Review	Change summary with approve/reject buttons

Real-time Updates

WebSocket server on port 3001
Auto-refresh on session state changes
Live streaming of Claude output

Statistics Dashboard (NEW)

Access session analytics at /stats:

ct web    # Go to http://localhost:3000/stats

Available Metrics:

Total sessions, success rate
Token usage (input/output)
Cost tracking with daily/weekly trends
Average session duration
Visual charts (line, bar)

Built-in Skills

TDD Workflow

ct start 42 --skill tdd

Enforces strict Test-Driven Development:

RED — Write failing test first (commit: test: ...)
GREEN — Minimal implementation to pass (commit: feat: ...)
REFACTOR — Clean up code (commit: refactor: ...)

Code Review

ct start 42 --skill review

Thorough code review with CRITICAL / WARNING / INFO levels

Batch Processing

Process multiple GitHub issues in parallel. Use ct auto (smart mode) or ct batch (manual mode):

# Auto: fetch all open issues with smart conflict detection
ct auto --label bug --parallel 3
ct auto --label high-priority --parallel 5

# Manual: specify exact issues
ct batch 101 102 103
ct batch --label bug --limit 10

Auto/Bustercall Options

Option	Description
`--label <label>`	Filter issues by GitHub label
`--parallel <n>`	Number of parallel sessions (default: 3)
`--max-cost <usd>`	Budget limit per session
`--dry-run`	Preview with smart complexity analysis (S/M/L/XL)
`--sort <strategy>`	Sort issues: `priority`, `newest`, `oldest`
`--resume <batchId>`	Retry only failed sessions from a previous batch
`-R, --review`	Auto-review after each session (Writer/Reviewer pattern)
`--retry <n>`	Auto-retry failed sessions (0-5)
`-S, --sequential`	Force all issues to run sequentially

Features

Batch ID Tracking: Every bustercall run gets a unique batch ID for session grouping
Smart Analysis: Dry-run shows complexity (S/M/L/XL), category, and estimated time
Conflict Detection: Automatically detects issues that modify shared files and runs them sequentially
Writer/Reviewer Pattern: --review auto-spawns a review session after each completion
Resume Mode: --resume <batchId> retries only failed sessions from a previous run
Priority Sorting: --sort priority processes high-priority issues first (critical > urgent > high > medium > low)
PR Filtering: Skips issues that already have open PRs
Progress Tracking: Real-time status updates with ETA for all sessions

# Smart analysis before running
ct auto --label bug --dry-run --sort priority

# Run with auto-review (Writer/Reviewer pattern)
ct auto --label feature --parallel 5 --review

# Resume failed sessions from a previous batch
ct auto --resume batch-abc12345

# View sessions from a specific batch
ct status --batch batch-abc12345

Dependency Chain (NEW)

Chain multiple issues together where each builds on the previous one's branch:

# Execute issues 10 → 11 → 12 sequentially
# Issue 11 starts from issue-10 branch, issue 12 starts from issue-11 branch
ct chain 10 11 12

# Preview the chain plan
ct chain 10 11 12 --dry-run

# Use a template for all issues
ct chain 10 11 12 --template feature

# Continue even if one fails
ct chain 10 11 12 --skip-failed

How It Works

Issue #10 (base: develop)
    ↓ completed
Issue #11 (base: issue-10)
    ↓ completed
Issue #12 (base: issue-11)
    ↓ completed

This is useful for:

Sequential features: DB schema → API → UI changes
Dependent fixes: Core fix → related fixes that depend on it
Progressive refactoring: Step-by-step improvements that build on each other

Chain Options

Option	Description
`--template <template>`	Session template for all issues
`--skip-failed`	Continue chain even if an issue fails
`--base-branch <branch>`	Base branch for first issue (default: develop)
`--dry-run`	Preview chain plan without executing

Session Templates

Templates provide pre-configured prompts for common tasks:

ct start 42 --template bugfix     # Focus on bug fixing
ct start 42 --template feature    # Feature implementation
ct start 42 --template refactor   # Code refactoring
ct start 42 --template review     # Code review
ct start 42 --template docs       # Documentation generation

Documentation Skill (NEW)

Generate comprehensive documentation automatically:

ct start 42 --skill docs
# or
ct start 42 --template docs

Claude will:

Analyze codebase structure
Identify public APIs and types
Generate README.md with installation, usage, API reference
Create docs/ folder for detailed documentation

Session Management

Inspect Sessions

Get a detailed one-stop view of any session:

ct inspect abc123    # By session ID prefix
ct inspect 42        # By issue number
ct inspect abc --json

Shows: status, tokens, cost, progress steps, tags, batch info, rerun history, worktree status, and actionable commands.

Cost Analytics

ct cost                      # Last 7 days summary
ct cost --days 30            # Last 30 days
ct cost --budget 5.00        # Daily budget with warnings
ct cost --batch batch-abc    # Filter by bustercall batch
ct cost --json               # Machine-readable output

Features: daily breakdown with bar chart, per-batch cost tracking, budget monitoring (EXCEEDED / approaching / within-budget).

Tag Management

ct tag abc123 add urgent feature    # Add tags
ct tag abc123 remove urgent         # Remove tags
ct status --tag urgent              # Filter by tag
ct status --state failed            # Filter by status
ct status --batch batch-abc         # Filter by batch

Rerun Sessions

ct rerun abc123                    # Rerun with same config
ct rerun abc123 --template refactor  # Override template
ct rerun abc123 --keep             # Keep original session

Smart Cleanup

ct cleanup                         # Remove completed + failed sessions
ct cleanup --dry-run               # Preview what would be removed
ct cleanup --status failed         # Only clean failed sessions
ct cleanup --older-than 7d         # Only clean old sessions
ct cleanup --batch batch-abc       # Clean specific batch

Architecture

packages/
├── cli/      # CLI commands (Commander.js)
├── core/     # Domain + Infrastructure
│   ├── application/  # SessionManager
│   ├── domain/       # Repository interfaces
│   └── infra/
│       ├── git/          # GitWorktreeAdapter
│       ├── claude/       # ClaudeSessionAdapter
│       ├── github/       # GitHubAdapter (Octokit)
│       ├── storage/      # File repositories
│       └── websocket/    # WebSocketBroadcaster
├── shared/   # TypeScript types
└── web/      # Next.js dashboard

Branch Strategy

main      ← stable releases (npm publish)
  ↑
develop   ← integration (PRs go here)
  ↑
feature/* ← your work (created by claudetree)

PRs are automatically created targeting the develop branch.

Comparison

Feature	Claude Code	claudetree
Parallel sessions	One at a time	Unlimited parallel
Issue-to-PR pipeline	Manual copy-paste	`ct start <url>`
Cost tracking	Current session only	Per-session + analytics (`ct stats`)
Batch processing	N/A	`ct batch` / `ct auto`
Dependency chains	N/A	`ct chain`
Session logs	Scroll terminal	`ct log` + web dashboard
Context isolation	Shared directory	Separate worktrees
Progress monitoring	Terminal only	CLI + web dashboard

Limitations

Token costs: Autonomous sessions consume significant tokens (use --max-cost to limit)
Claude availability: Requires Claude Code CLI installed (run ct doctor to check)
Git worktrees: Project must be a git repository
GitHub integration: Currently GitHub-only for issue fetching

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
.changeset		.changeset
.claude		.claude
.github		.github
packages		packages
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.ko.md		README.ko.md
README.md		README.md
README.zh.md		README.zh.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

claudetree

Why claudetree?

Key Benefits

Use Cases

Important: Token Usage Warning

How It Works

Installation

Quick Start

Step 1: Initialize in your project

Step 2: Set up GitHub token

Step 3: Start working on an issue

Step 4: Monitor progress

CLI Commands

Start Options

Examples

Configuration

Web Dashboard

Features

Real-time Updates

Statistics Dashboard (NEW)

Built-in Skills

TDD Workflow

Code Review

Batch Processing

Auto/Bustercall Options

Features

Dependency Chain (NEW)

How It Works

Chain Options

Session Templates

Documentation Skill (NEW)

Session Management

Inspect Sessions

Cost Analytics

Tag Management

Rerun Sessions

Smart Cleanup

Architecture

Branch Strategy

Comparison

Limitations

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages