Claude Plan Tracker (cpt)

Track and persist implementation plans across Claude Code sessions.

Features

• Automatic Plan Persistence: Plans are automatically saved when sessions end
• Context Restoration: Plans are restored when new sessions start on the same branch
• Commit Tracking: Git commits made during sessions are tracked in plan metadata
• Branch-Based Organization: Each git branch gets its own plan file
• Zero Runtime Dependencies: Single static binary with no external dependencies

Installation

From GitHub Releases

Download the latest release for your platform from Releases.

From Source

go install github.com/jansmrcka/cpt@latest

Build from Source

git clone https://github.com/jansmrcka/cpt
cd cpt
make build

Usage

Initialize in a Project

cd your-project
cpt init

This creates the necessary hooks in .claude/settings.json.

View Current Plan Status

cpt status

Shows the plan for the current branch, including tracked commits.

List All Plans

cpt list

Lists all tracked plans in the repository.

Manual Sync

cpt sync

Manually sync a plan from Claude's session storage. Use --force to overwrite an existing plan.

How It Works

cpt uses Claude Code hooks to:

1. SessionStart: Load the existing plan for the current branch and inject it as context
2. SessionEnd: Extract the plan from the session transcript and save it
3. PostToolUse (Bash): Track git commits made during the session

Plans are stored in .claude/plans/ in your repository with YAML frontmatter containing metadata.

Plan File Format

---
branch: feature/my-feature
source: claude-session
last_updated: 2024-01-15T10:00:00Z
commits:
  - abc123
  - def456
---

## Plan

1. Implement feature X
2. Add tests
3. Update documentation

Plugin Installation

cpt can be installed as a Claude Code plugin. Run these commands inside a Claude Code session:

Option 1: Install from GitHub (Recommended)

/plugin marketplace add jansmrcka/cpt
/plugin install cpt@jansmrcka-cpt

Option 2: Install from Local Clone

If you cloned the repository locally:

/plugin marketplace add /path/to/cpt
/plugin install cpt@cpt

Option 3: Manual Setup with cpt init

If you prefer not to use the plugin system, you can set up hooks manually:

# Install the binary first (see Installation section above)
cd your-project
cpt init

This adds the necessary hooks directly to .claude/settings.json in your project.

Commands

Command	Description
cpt init	Initialize hooks in the current project
cpt status	Show plan status for current branch
cpt list	List all tracked plans
cpt sync	Sync plan from Claude session storage
cpt --version	Show version

Configuration

cpt stores plans in .claude/plans/ in your repository root. This directory is created automatically when you run cpt init.

gitignore

You may want to add .claude/plans/ to your .gitignore if you don't want to commit plans:

# Claude Plan Tracker plans
.claude/plans/

Or commit them if you want to share plans with your team.

Development

# Build
make build

# Run tests
make test

# Run linter
make lint

# Build for all platforms
make build-all

License

MIT