
planpilot
Plan and track steps/goals with a local SQLite-backed CLI and Claude Code hooks. Use when the user asks to plan or break down work into steps/goals, track progress, manage plans, or mentions Planpilot/planpilot/plan pilot/计划/任务拆解/步骤/目标/进度.
- version
- 0.2.0
- GitHub stars
- 6
Install
/plugin install planpilot@canxin-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add canxin121/canxin-claude-plugins.
Contents
Discovered from sourceCommands 2
Planpilot Install
Install the Planpilot CLI from this plugin's source.
Command
!cargo install --path ${CLAUDE_PLUGIN_ROOT}
Notes
- If the command fails, explain the error and suggest installing Rust/Cargo.
- Remind the user that the binary is typically installed into
~/.cargo/binand should be on PATH.
Planpilot (Claude Code Plugin)
Binary CLI Tool Name
planpilot
Database location:
~/.claude/.planpilot/planpilot.db
Hierarchy
- Plan contains steps; step contains goals.
- Goals are the smallest units of work; steps group goals; plans group steps.
AI Workflow Guidelines
- Use Planpilot (this CLI + stop hook) for all planning, status, and progress tracking; do not use the built-in plan tool or any other method (including inspecting files, calling other MCP tools, or using other skills) to get plan/step/goal status.
- Do not use the built-in plan or todo tools (including TodoWrite/TodoRead). Always use Planpilot.
- If the CLI is missing (e.g.,
planpilot: command not found), ask the user whether to install it, and offer/planpilot-installif they agree. - Record implementation details using Planpilot comments (plan/step/goal
--commentorcommentcommands), and before starting a step or goal, think through what you are about to do next and capture that context in comments so the plan stays actionable. - Before starting a new plan, perform deep thinking, investigation, and analysis; then create the plan with clear steps and goals.
- When creating a plan or step, prefer
add-treeto define all steps/goals upfront and add everything in one pass. - Prefer assigning steps to
ai; only assignhumanfor truly critical/high-risk items or when passwords,sudoaccess, irreversible git history rewrites, or remote git changes are required. Ifhumansteps are necessary, batch them, make the step content explicit about what the human must do, and only ask the user for input when the next step is assigned tohuman(do not ask for preferences/reviews/approvals on basic items). - You may adjust plans/steps/goals while executing, but only when necessary; avoid frequent or arbitrary changes.
- Update status promptly as work completes; mark goals as done, and let steps/plans auto-refresh unless a step/plan has no children (then use
step done/plan done). - In each reply turn, complete at most one step; do not advance multiple steps in a single response.
Status Management
- Status values:
todo,done. - Goals are manual (
goal done); steps/plans auto-refresh from child status, and usestep done/plan doneonly when they have no children (step done --all-goalsmarks all goals done and then marks the step done). Auto status changes print asAuto status updates:with reasons. - Parent status auto-flips to
todoon incomplete child work and todonewhen all children are done. If a plan has 0 steps or a step has 0 goals, no auto-flip happens; useplan done/step doneas needed. - If the user completed a
humanstep, verify/mark each goal and clearly list what remains. - When a step becomes
doneand there is another pending step, the CLI will print the next-step instruction: forai, end the turn so Planpilot can surface it; forhuman, show the step detail and tell the user to complete the goals, then end the turn. When a plan becomesdone(automatic or manual), the CLI will prompt you to summarize completed results and end the turn.
Active Plan Management
- Use
plan activate/plan deactivateto manage, and no active plan means the plan is paused until reactivated. Plans auto-deactivate ondone(manual or automatic) or removal. - Each plan can be active in only one session at a time; use
plan activate --forceto take over. Default to no--force, and if activation fails due to another session, ask the user whether to take over. - Use
plan show-activeto know which plan is active and get its details.
Stop Hook Behavior
- Stop hooks run when Claude Code is about to finish a turn; they can approve completion or block it and inject a follow-up prompt into the same session.
- Planpilot's hook uses
approveto let the turn finish, andblockto re-prompt with the next AI step details. - It approves when there is no active plan, or the next todo step is not assigned to
ai. - It blocks when the next todo step is assigned to
ai, returning the step detail. The message always starts withPlanpilot (auto):on the first line. - If the AI receives a stop-hook message but lacks plan/step/goal context, it must use Planpilot commands (e.g.,
plan show-active,plan show,step show,goal list) to fetch the missing context before proceeding.
ID Notes
- Plan/step/goal IDs are database IDs and may be non-contiguous or not start at 1; always use the actual IDs shown by
list/show.
Commands
plan
- IMPORTANT: The AI must NOT pass
--cwdor--session-idmanually. These are auto-injected by the hook; passing them will conflict with the injected values. - Plan data is stored under Claude home:
~/.claude/.planpilot/(derived from the plugin directory). plan add <title> <content>: create a plan.- Output:
Created plan ID: <id>: <title>.
- Output:
plan add-tree <title> <content> --step <content> [--executor ai|human] [--goal <goal> ...] [--step <content> ...]: create a plan with steps/goals in one command.- Output:
Created plan ID: <id>: <title> (steps: <n>, goals: <n>). - Repeatable groups: you can repeat the
--step ... [--executor ...] [--goal ...]group multiple times. - Each
--executor/--goalapplies to the most recent--step. - Example:
planpilot plan add-tree "Release v1.2" "Plan description" \ --step "Cut release branch" --executor human --goal "Create branch" --goal "Tag base" \ --step "Build artifacts" --executor ai --goal "Build packages" - Another example (3 steps, some without goals/executor):
planpilot plan add-tree "Onboarding" "Setup plan" \ --step "Create accounts" --goal "GitHub" --goal "Slack" \ --step "Install tooling" --executor ai \ --step "Read handbook"
- Output:
plan list [--all] [--project]: list plans (defaults totodounless--allis set). Use--projectto limit to the current cwd project.- Output: prints a header line, then one line per plan with
ID STAT STEPS TITLE COMMENT(STEPSisdone/total); useplan showfor full details. - Output (empty):
No plans found.
- Output: prints a header line, then one line per plan with
plan search --search <term> [--search <term> ...] [--search-mode any|all] [--search-field plan|title|content|comment|steps|goals|all] [--match-case] [--all] [--project]: search plans. Use--projectto limit to the current cwd project.- Output: same format as
plan list. - Output (empty):
No plans found. - Scope flags:
--scope cwd: show plans whoselast_session_idbelongs to sessions for the current cwd (default).--scope session: show plans for the current session only.--scope all: show all plans across sessions.
- Advanced search:
--search <term>(repeatable): filter plans by text.--search-mode any|all: match any term or require all terms (default:all).--search-field plan|title|content|comment|steps|goals|all(default:plan).--match-case: make search case-sensitive.
- Output: same format as
plan show <id>: prints plan details and nested steps/goals (includes ids for plan/step/goal).- Output: plan header includes
Plan ID: <id>,Title,Status,Content,Created,Updated, andCommentwhen present. - Output: each step line includes step id and executor; progress (
goals done/total) is shown only when the step has goals. Each goal line includes goal id.
- Output: plan header includes
plan export <id> <path>: export plan details to a markdown file.- Output:
Exported plan ID: <id> to <path>.
- Output:
plan update <id> [--title <title>] [--content <content>] [--status todo|done] [--comment <comment>]: update fields;--status doneis allowed only when all steps are done or the plan has no steps.- Output:
Updated plan ID: <id>: <title>. - Errors: multi-line
Error: Invalid input:withcannot mark plan done; next pending step:on the next line, followed by the same step detail output asstep show.
- Output:
plan done <id>: mark plan done (same rule asplan update --status done).- Output:
Plan ID: <id> marked done. - Output (active plan):
Active plan deactivated because plan is done. - Errors: multi-line
Error: Invalid input:withcannot mark plan done; next pending step:on the next line, followed by the same step detail output asstep show.
- Output:
plan comment <id1> <comment1> [<id2> <comment2> ...]: add or replace comments for one or more plans.- Output (single):
Updated plan comment for plan ID: <id>. - Output (batch):
Updated plan comments for <n> plans. - Each plan comment uses an
<id> <comment>pair; you can provide multiple pairs in one call. - Example:
planpilot plan comment 12 "high priority" 15 "waiting on input"
- Output (single):
plan remove <id>: remove plan (and its steps/goals).- Output:
Plan ID: <id> removed.
- Output:
plan activate <id> [--force]: set the active plan.- Output:
Active plan set to <id>: <title>. --forcetakes over a plan already active in another session.- Errors:
Error: Invalid input: cannot activate plan; plan is done. - Errors:
Error: Invalid input: plan id <id> is already active in session <session_id> (use --force to take over).
- Output:
plan show-active: prints the active plan details (same format asplan show).- Output: the same plan detail format as
plan show. - Output (empty):
No active plan. - Output (missing):
Active plan ID: <id> not found.
- Output: the same plan detail format as
plan deactivate: unset the active plan (does not delete any plan).- Output:
Active plan deactivated.
- Output:
step
step add <plan_id> <content1> [<content2> ...] [--at <pos>] [--executor ai|human]: add steps.- Output (single):
Created step ID: <id> for plan ID: <plan_id>. - Output (batch):
Created <n> steps for plan ID: <plan_id>.
- Output (single):
step add-tree <plan_id> <content> [--executor ai|human] [--goal <goal> ...]: create one step with goals in one command.- Output:
Created step ID: <id> for plan ID: <plan_id> (goals: <n>). - Example:
planpilot step add-tree 1 "Draft summary" \ --executor ai --goal "Collect inputs" --goal "Write draft"
- Output:
step list <plan_id> [--all] [--status todo|done] [--executor ai|human] [--limit N] [--offset N] [--count] [--order order|id|created] [--desc]: list steps (defaults totodounless--allor--statusis set).- Output: prints a header line, then one line per step with
ID STAT EXEC GOALS CONTENT COMMENT(GOALSisdone/total); usestep showfor full details. - Output (count):
Total: <n>when--countis set (no list output). - Output (empty):
No steps found for plan ID: <plan_id>.
- Output: prints a header line, then one line per step with
step show <id>: prints a single step with full details and its nested goals (includes ids for step/goal).- Output: step header includes
Step ID: <id>,Plan ID,Status,Executor,Content,Created,Updated, andCommentwhen present. - Output: lists all goals with
[status]and goal id.
- Output: step header includes
step show-next: show the next pending step for the active plan (same format asstep show).- Output (empty):
No active plan.orNo pending step..
- Output (empty):
step update <id> [--content <content>] [--status todo|done] [--executor ai|human] [--comment <comment>]: update fields;--status doneis allowed only when all goals are done or the step has no goals.- Output:
Updated step ID: <id>.. - Errors:
Error: Invalid input: cannot mark step done; next pending goal: <content> (id <id>).
- Output:
step comment <id1> <comment1> [<id2> <comment2> ...]: add or replace comments for one or more steps.- Output (single):
Updated step comments for plan ID: <plan_id>. - Output (batch):
Updated step comments for <n> plans. - Each step comment uses an
<id> <comment>pair; you can provide multiple pairs in one call. - Example:
planpilot step comment 45 "blocked by API" 46 "ready to start"
- Output (single):
step done <id> [--all-goals]: mark step done (same rule asstep update --status done). Use--all-goalsto mark all goals in the step done first, then mark the step done.- Output:
Step ID: <id> marked done. - Errors:
Error: Invalid input: cannot mark step done; next pending goal: <content> (id <id>).
- Output:
step move <id> --to <pos>: reorder and print the same one-line list asstep list.- Output:
Reordered steps for plan ID: <plan_id>:+ list.
- Output:
step remove <id1> [<id2> ...]: remove step(s).- Output (single):
Step ID: <id> removed. - Output (batch):
Removed <n> steps. - Errors:
Error: Not found: step id(s) not found: <id1>[, <id2> ...].
- Output (single):
goal
goal add <step_id> <content1> [<content2> ...]: add goals to a step.- Output (single):
Created goal ID: <id> for step ID: <step_id>. - Output (batch):
Created <n> goals for step ID: <step_id>.
- Output (single):
goal list <step_id> [--all] [--status todo|done] [--limit N] [--offset N] [--count]: list goals (defaults totodounless--allor--statusis set).- Output: prints a header line, then one line per goal with
ID STAT CONTENT COMMENT. - Output (count):
Total: <n>when--countis set (no list output). - Output (empty):
No goals found for step ID: <step_id>.
- Output: prints a header line, then one line per goal with
goal update <id> [--content <content>] [--status todo|done] [--comment <comment>]: update fields.- Output:
Updated goal <id>.
- Output:
goal comment <id1> <comment1> [<id2> <comment2> ...]: add or replace comments for one or more goals.- Output (single):
Updated goal comments for plan ID: <plan_id>. - Output (batch):
Updated goal comments for <n> plans. - Each goal comment uses an
<id> <comment>pair; you can provide multiple pairs in one call. - Example:
planpilot goal comment 78 "done" 81 "needs review"
- Output (single):
goal done <id1> [<id2> ...]: mark one or more goals done.- Output (single):
Goal ID: <id> marked done. - Output (batch):
Goals marked done: <n>.
- Output (single):
goal remove <id1> [<id2> ...]: remove goal(s).- Output (single):
Goal ID: <id> removed. - Output (batch):
Removed <n> goals. - Errors:
Error: Not found: goal id(s) not found: <id1>[, <id2> ...].
- Output (single):
Hooks 2
Sponsors
Details
- Marketplace
- canxin121/canxin-claude-plugins
- Source
- plugins/planpilot
- Author
- canxin
- Category
- Productivity
- License
- MIT