cc-plan-tree 🌳

Turn Claude Code's plan mode into a visual design tree — see every design decision (including the options you didn't take), verify the finished code still matches the design, and embed the tree right in your pull request.

flowchart TD
  root["Add JWT authentication"]
  root --> d{"Where to store the refresh token?"}
  d --> o1["HttpOnly cookie"]
  d -.-> o2["✗ localStorage"]
  o1 --> s1["✓ Set cookie flags (Secure, SameSite)"]
  root --> p["Backend"]
  p --> s2["✓ Auth middleware verifying JWT"]
  p --> s3["… POST /login and /refresh endpoints"]
  classDef rejected fill:#f1f5f9,stroke:#94a3b8,color:#64748b,stroke-dasharray: 4 3
  class o2 rejected

Why

Plan mode produces walls of text. The design decisions — "we considered localStorage but chose HttpOnly cookies because of XSS" — vanish the moment the session ends. cc-plan-tree keeps them:

• 🌳 Plans become trees. Phases, steps, and every clarifying question as a decision node with chosen/rejected options.
• 🔍 Design ⇄ code verification. Before your PR is ready, /plan-verify checks each step of the tree against the actual diff and reports what matches, diverges, or is missing.
• 📎 Lives in your PR. The tree is embedded in the PR body as Mermaid — GitHub renders it natively, reviewers see the design at a glance.
• 🖼️ PNG export for docs, Slack, and anywhere Mermaid doesn't render.

Install

# with uv (recommended)
uv tool install cc-plan-tree
cc-plan-tree init            # installs the slash commands into ~/.claude/commands

# or with pip
pip install cc-plan-tree && cc-plan-tree init

# or zero-install, one shot
uvx cc-plan-tree init

Use cc-plan-tree init --project to install into the current project's .claude/commands instead.

Upgrading

init copies the slash commands into .claude/commands, so after upgrading the package, re-run init to refresh them:

uv tool upgrade cc-plan-tree && cc-plan-tree init   # pip: pip install -U cc-plan-tree

From source:

git clone https://github.com/natsu0529/cc-plan-tree
cd cc-plan-tree && pip install -e . && cc-plan-tree init

Workflow

Inside Claude Code:

The CLI also works standalone:

cc-plan-tree render .cc-plan-tree/plan.json --format mermaid   # stdout
cc-plan-tree render --format html --out design.html            # interactive, self-contained
cc-plan-tree render --format svg --out design.svg
cc-plan-tree render --format png --out design.png

Plan file format

.cc-plan-tree/plan.json is a nested tree of nodes:

See examples/sample-plan.json for a full example.

Roadmap

• Adapters for other coding agents (Codex CLI, Gemini CLI) via the shared plan format
• Plan version diffing (what changed between plan v1 and what shipped)
• Interactive HTML view (--format html, v0.2)

Contributions welcome — the plan format is intentionally agent-agnostic, so adapters are a great first PR.

License

MIT