ccplan

CLI tool to manage .claude/plans/*.md files generated by Claude Code's plan mode.

Track status (draft / active / done), list, filter, and clean up plan files — without modifying the files themselves.

Why

We believe plan documents in agent coding are ephemeral by nature. Once a task is complete, the valuable outcomes should be published to Issues, PRs, Wikis, or other durable artifacts — the plan files themselves have served their purpose.

In our view, a tool with a broad user base like Claude Code shouldn't impose an opinionated way to manage these generated files. Users should be free to choose the management approach that fits their workflow. ccplan is one such approach.

Accumulated plan files also appear in fuzzy finders (e.g. fzf, Ctrl-P in editors), polluting search results and degrading the navigation experience in your project.

Since humans ultimately judge whether work is complete, we find that fully automating a plan's lifecycle is difficult. ccplan aims to give humans a simple way to manage plans in the batches and cadences that make sense to them.

Future direction: We are exploring Agent Skills integration so that agents can assist with plan lifecycle management on behalf of the user.

Install

# npm
npm install -g ccplan

# Bun
bun add -g ccplan

# Single binary (GitHub Releases)
curl -L https://github.com/sorafujitani/ccplan/releases/latest/download/ccplan-darwin-arm64 -o ccplan
chmod +x ccplan

Usage

Commands that target a plan file (status, open) will show an interactive selector with fuzzy search when no file is specified — no shell configuration needed. Just start typing to filter by filename.

• status: multi-select (checkbox) with search — change multiple plans at once
• open: single-select with search

ccplan list

List plans with status and last updated date.

ccplan list                    # all plans
ccplan list -s active          # filter by status
ccplan list --json             # JSON output

ccplan status [file] <status>

Change a plan's status.

ccplan status done             # interactive multi-select
ccplan status my-plan.md done
ccplan status --latest active  # target most recently modified plan

Valid statuses: draft, active, done

ccplan open [file]

Open a plan file in $EDITOR (defaults to vi).

ccplan open                    # interactive select
ccplan open my-plan.md
ccplan open --latest

ccplan clean

Delete plans matching a filter.

# Batch mode (filter by status + age)
ccplan clean                          # done + 7 days old (default)
ccplan clean --days 14                # done + 14 days old
ccplan clean -s draft                 # draft + 7 days old
ccplan clean -s draft --all           # all drafts regardless of age
ccplan clean --dry-run                # preview without deleting

# Single file mode (ignores status/age filters)
ccplan clean my-plan.md
ccplan clean --latest
ccplan clean my-plan.md --force       # skip confirmation

Option	Description
-s, --status <status>	Filter by status (default: done)
-d, --days <n>	Minimum days since updated (default: 7)
--all	Remove day limit (cannot combine with --days)
-l, --latest	Target most recently modified plan
--dry-run	Preview without changes
-f, --force	Skip confirmation

Metadata Store

Plan metadata is stored in .claude/plans/.ccplan-meta.json — plan files are never modified.

{
  "version": 1,
  "plans": {
    "my-plan.md": {
      "status": "active",
      "created": "2026-01-15T10:00:00.000Z",
      "updated": "2026-02-20T12:00:00.000Z"
    }
  }
}

Plans without metadata are automatically registered as active on first scan.

Development

bun install
bun run test
bun run typecheck
bun run lint
bun run build        # dist/index.js (npm package)
bun run build:bin    # ./ccplan (single binary)

Acknowledgements

The name ccplan (cc = Claude Code) is inspired by ccusage.

License

MIT