Metadata-Version: 2.4
Name: cc-plan-tree
Version: 0.1.0
Summary: Turn Claude Code plan mode into a visual design tree - verify it against your code and embed it in PRs.
Author: natsu0529
License: MIT
Project-URL: Homepage, https://github.com/natsu0529/cc-plan-tree
Project-URL: Issues, https://github.com/natsu0529/cc-plan-tree/issues
Keywords: claude-code,planning,visualization,mermaid,ai-agents,design-tree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10.0
Dynamic: license-file

# 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.

<!-- TODO: demo GIF here -->

```mermaid
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

```bash
pip install cc-plan-tree     # or: uv tool install cc-plan-tree
cc-plan-tree init            # installs the slash commands into ~/.claude/commands
```

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

From source:

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

## Workflow

Inside Claude Code:

| Command | What it does |
|---|---|
| `/plan-tree <task>` | Plans the task. Clarifying questions become **decision nodes** (rejected options stay visible, greyed out). The plan is saved to `.cc-plan-tree/plan.json` and shown as a Mermaid tree. Approve it and implementation starts; step statuses update as work completes. |
| `/plan-verify` | Diffs the branch against the design tree. Reports ✅ matches / ⚠️ diverges / ❌ missing per node. On divergence you choose: fix the code, or fix the tree. When consistent, it offers to embed the tree into the PR body via `gh` (with your confirmation). |
| `/plan-export [path]` | Renders the tree to PNG (default `./plan-tree.png`). No headless browser — pure Pillow. |

The CLI also works standalone:

```bash
cc-plan-tree render .cc-plan-tree/plan.json --format mermaid   # stdout
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:

| type | meaning |
|---|---|
| `goal` | The root: what is being built |
| `phase` | A group of steps |
| `step` | Concrete work item, carries `status`: `pending` / `in_progress` / `done` |
| `decision` | A design question that was asked |
| `option` | An answer to a decision; `chosen: true/false`, rejected ones keep a `reason` |
| `note` | Free-form annotation |

See [examples/sample-plan.json](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

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

## License

MIT
