Christopher Hotchkiss

Christopher Hotchkiss

Crafting Solutions, Shaping Products: From Concept to Code

claude-plan-bridge

Bridging Claude Code's per-session task list with a durable PLAN.md.

The problem

Claude Code's built-in TaskCreate / TaskList are per-session — they reset every time you start a new conversation. That's fine for short, self-contained work, but anything spanning a day or a multi-step refactor needs to live somewhere durable.

The natural fix is a PLAN.md checked into the repo: a tree of checkboxes that lives with the code, gets reviewed in PRs, and survives session boundaries. But now you have two task lists that want to be the source of truth. Without coordination, Claude ticks tasks but PLAN.md grows stale, or you hand-edit PLAN.md and Claude can't see what changed.

The bridge

claude-plan-bridge installs four Claude Code hooks that keep the two views aligned:

  • PostToolUse(TaskCreate) — every new task appends a [ ] line to PLAN.md (at a specific plan_path if Claude sets one, otherwise an auto-managed Inbox.0 phase).
  • PostToolUse(TaskUpdate) — completed flips [ ] → [x] at the right line; deleted on a still-pending leaf doesn't erase it — it defers to [>] backlog with a dated note, so nothing silently vanishes from the plan.
  • UserPromptSubmit — runs a reconcile pass on PLAN.md between turns and feeds any drift (renames, hand-ticks, new notes, missing entries) to Claude as additionalContext on the next message.
  • SessionStart — rehydrates a fresh session's task list from PLAN.md, re-emitting every open leaf so a new conversation picks up exactly where the last one stopped.

A small per-project state file (.claude/plan-bridge-state.json) holds the taskId ↔ plan_path map and last_synced_* baselines. An advisory file lock keeps concurrent writebacks from racing. There's also an MCP server mode if you'd rather drive plans through typed tool calls than markdown.

Workflow

cargo install claude-plan-bridge
cd your-project/
claude-plan-bridge init        # scaffolds PLAN.md, wires the four hooks

Restart Claude Code so it picks up the new settings.json. From there the bridge runs invisibly. When a top-level phase is fully [x]:

claude-plan-bridge archive     # sweep done phases to PLAN_ARCHIVE.md

History reads chronological-ascending, IDs are never renumbered, and 7.2a slots between 7.2 and 7.3 without breaking downstream references.

Scope honesty

Designed for small teams (1–5 contributors). Many parallel branches editing PLAN.md will produce merge conflicts the bridge doesn't resolve — at that scale you'd want a real ticketing system. The flip side: the bridge imposes a canonical PLAN.md format (dotted-decimal ids, four checkbox states — pending, done, won't-do, backlog — two-space indent) and the reconcile loop catches drift early — useful even just as a strict-format linter for plan docs.

Source

Cover Image from Guywelch2000, CC BY 4.0, via Wikimedia Commons