Agent Plan

Agent Plan is a local, project-scoped planning platform for AI coding agents.

It gives a project a structured planning workspace in .planner/, then exposes that workspace through multiple surfaces:

a core TypeScript library (@agent-plan/core);
a local HTTP/WebSocket server and React dashboard;
a Pi adapter with a grouped /planner ... command;
a Claude Code MCP server with planner-* tools;
a Claude Code /planner ... slash command router;
a CLI (agent-plan) for setup, MCP startup, and project initialization.

The goal is to make planning durable, inspectable, and shared across agents without coupling the core planning model to any one harness.

Status

This project is under active development.

Current focus:

Pi integration is available through a grouped /planner command.
Claude Code Phase 1 is available through MCP and a generated /planner slash command.
The canonical project data directory is .planner/.
Agent Plan intentionally does not read, migrate, or use .plan/; that directory belongs to other tools such as GSD/get-shit-done.

Core concepts

`.planner/` is the source of truth

Agent Plan stores structured planning data in the target project:

my-project/
  .planner/
    manifest.json
    project.json
    features.json
    requirements.json
    phases/
      <phase-id>.json
    resume.json
    HANDOFF.md
    generated/
      PLAN.md
      features/
      phases/

JSON files are the source of truth. Markdown files under .planner/generated/ are generated views for humans and agents.

Hierarchy

The public planning hierarchy is:

project → features → phases → tasks

Requirements currently exist as internal/project seed data and are not exposed as public Claude Code commands in Phase 1.

Harness-agnostic core

The core planning model lives outside Pi, Claude Code, or any other harness. Adapters should call shared planning logic rather than owning business rules.

Recommended Claude Code setup

1. Install once

After publication, the intended installation is:

npm install -g agent-plan

Then configure Claude Code once at user scope:

agent-plan setup claude-code --user

This does three things:

registers the Agent Plan MCP server in Claude Code user scope;
writes the Claude Code slash command router:

~/.claude/commands/planner.md

installs a Claude Code PreToolUse task guard hook in:

~/.claude/settings.json

After this, /planner ... is available from Claude Code projects and implementation tools are guarded when a project has an active .planner/.

2. Initialize a project only when needed

Open a project with Claude Code:

cd my-project
claude

Then initialize planning explicitly:

/planner init

This creates:

my-project/.planner/

If a project is not initialized, Agent Plan tools should report that .planner/ is missing and suggest /planner init.

User commands — Claude Code

Claude Code supports a slash command /planner ... that routes natural command text to the underlying MCP tools.

Core

/planner init — Initialize planner
/planner show — Show planner overview
/planner repair — Repair planner integrity
/planner load — Re-enable planner
/planner disable — Disable planner for this session

Project

/planner project discuss — Run project discovery
/planner project language — Set persistent language preferences

Features

/planner feature list — List features
/planner feature add <name> — Create a feature
/planner feature show <id> — Show a feature
/planner feature update <id> — Update a feature
/planner feature delete <id> — Delete a feature

Phases

/planner phase add <title> — Add a phase
/planner phase show <id> — Show a phase
/planner phase discuss <id> — Discuss a phase
/planner phase update <id> — Update a phase
/planner phase delete <id> — Delete a phase

Tasks

/planner task add <title> — Add a task
/planner task show <id> — Show a task
/planner task discuss <id> — Discuss a task
/planner task update <id> — Update a task
/planner task delete <id> — Delete a task
/planner task start <id> — Mark a task in-progress
/planner task complete <id> — Mark a task done

Handoff

/planner handoff prepare — Tell the agent to create/update the handoff
/planner handoff show — Show the current handoff
/planner handoff write — Write handoff from planner data
/planner handoff clear — Delete the current handoff

Export & Web

/planner export — Export plan summary as Markdown
/planner export-full — Export full detailed plan as Markdown
/planner web start|stop|status — Manage the web UI

Guard bypass

/planner bypass — Authorize edit/write without a task (15 min)
/planner clear-bypass — Revoke the bypass

Agent tools (MCP)

The MCP server exposes public tools using the planner-* namespace. These tools are called by AI agents (Claude Code, Codex, Zed), not by humans. Human users should use the /planner ... slash commands instead.

Current Phase 1 tools include:

Core

planner-init
planner-show
planner-repair
planner-load
planner-disable
planner-web
planner-export

Project

planner-project-discuss
planner-project-language

Features

planner-feature-list
planner-feature-add
planner-feature-show
planner-feature-update
planner-feature-delete

Phases

planner-phase-add
planner-phase-show
planner-phase-discuss
planner-phase-update
planner-phase-delete

Tasks

planner-task-add
planner-task-show
planner-task-discuss
planner-task-update
planner-task-delete
planner-task-start
planner-task-complete

Handoff

planner-handoff-prepare
planner-handoff-show
planner-handoff-write
planner-handoff-clear

Export

planner-export (with optional full boolean for detailed hierarchical output)

Guard bypass

planner-authorize-bypass (temporary bypass so Edit/Write work without a task in-progress)
planner-clear-bypass

Requirements are intentionally not exposed as planner-requirement-* in Phase 1.

The current Phase 1 count is 32 public planner-* tools.

Claude Code setup modes

User-scope setup, recommended

Use this once per machine/user:

agent-plan setup claude-code --user

This keeps the MCP server and slash command available across projects.

It does not create .planner/ in any project.

Project-local setup

Use this when you want a repository-local Claude Code configuration, for example for a team, a pinned version, or local development:

agent-plan setup claude-code --project

This creates or updates:

.mcp.json
.claude/commands/planner.md
.claude/settings.json

The settings file contains a Claude Code PreToolUse hook for Edit|Write and the shared guard-bypass flow.

Example .mcp.json:

{
  "mcpServers": {
    "agent-plan": {
      "command": "npx",
      "args": ["agent-plan", "mcp"]
    }
  }
}

Project-local setup also does not initialize .planner/. Run /planner init when you want planning enabled in that repo.

Local development setup

Before npm publication, use the built local CLI:

pnpm --filter @agent-plan/mcp build
pnpm --filter agent-plan build

Project-local local setup:

node /Users/antonio/projects/agent-plan/packages/agent-plan/dist/index.js setup claude-code --project --local

User-scope local setup:

node /Users/antonio/projects/agent-plan/packages/agent-plan/dist/index.js setup claude-code --user --local

CLI

The CLI package is agent-plan.

agent-plan help
agent-plan mcp
agent-plan init
agent-plan export [--full]
agent-plan setup claude-code --user
agent-plan setup claude-code --project

`agent-plan mcp`

Starts the stdio MCP server.

This is what Claude Code launches after setup.

`agent-plan init`

Initializes .planner/ in the current working directory.

cd my-project
agent-plan init

This is equivalent in intent to running /planner init from an agent UI.

`agent-plan export`

Generates a Markdown export of the plan and writes it to .planner/EXPORT.md.

agent-plan export          # summary report
agent-plan export --full   # full hierarchical detail (features → phases → tasks)

In Pi and Claude Code the same report is available via:

/planner export
/planner export-full

The web UI also exposes an Export dropdown with Summary and Full options that download the generated Markdown file.

`agent-plan setup claude-code`

Configures Claude Code integration.

Useful options:

--user      install at Claude Code user scope
--project   install in the current project; this is the default
--local     point config to the local built CLI instead of npx/global package
--force     overwrite an existing agent-plan MCP entry

User commands — Pi

Pi exposes Agent Plan as one grouped command:

/planner

Core

/planner init — Initialize planner in this project
/planner show — Show planner overview
/planner repair — Repair planner integrity
/planner load — Re-enable planner and start web UI
/planner disable — Reset planner preferences and disable for this session

Project

/planner project discuss — Run project discovery
/planner project language — Set persistent language preferences

Features

/planner feature list — List features
/planner feature add — Create a feature
/planner feature show — Show a feature
/planner feature update — Update a feature
/planner feature delete — Delete a feature

Phases

/planner phase add — Add a phase
/planner phase show — Show a phase
/planner phase discuss — Discuss a phase
/planner phase update — Update a phase
/planner phase delete — Delete a phase

Tasks

/planner task add — Add a task
/planner task show — Show a task
/planner task discuss — Discuss a task
/planner task update — Update a task
/planner task delete — Delete a task
/planner task start — Mark a task in-progress
/planner task complete — Mark a task done

Handoff

/planner handoff prepare — Tell the agent to create/update the handoff
/planner handoff show — Show the current handoff
/planner handoff write — Write handoff directly from planner data
/planner handoff clear — Delete the current handoff

Web

/planner web start — Start the web UI
/planner web stop — Stop the web UI
/planner web status — Show web UI status

Export

/planner export — Export plan summary as Markdown
/planner export-full — Export full detailed plan as Markdown

Guard bypass

/planner bypass — Authorize edit/write without a task in-progress (15 min)
/planner clear-bypass — Revoke the guard bypass

Pi session prompts and startup resume

When Pi detects an existing planner in the project, it can ask whether to enable the planner extension and whether to start the web UI.

Prompt keys are intentionally short:

y = yes for this session
n = no for this session
a = always for this project
e = never ask again for this project

Why this exists:

Pi sessions should be quick to resume;
repeated setup prompts are noisy in established projects;
project-level preferences should persist without forcing planning into unrelated repos.

When the planner web server is active, the startup resume summary includes the dashboard URL.

If no feature/phase/task is actually in-progress, the resume summary must not invent a current focus from the handoff. In that case, the handoff is treated as a previous-session hint to validate against the current plan state, ordering, and dependencies.

Stable planning order and visible numbering

Agent Plan now persists explicit planning order for:

features → feature.number
phases → phase.number
tasks → task.number

This order is displayed as stable human-friendly labels:

F001, F002, ...
P001, P002, ...
T001, T002, ...

Why this exists:

UUIDs are stable but hard to reason about visually;
resume, handoff, export, and Work Tree must agree on the same ordering;
teams need a clear sense of sequence and priority, not just identity.

For older projects, the numbering is normalized automatically from the current planner structure and persisted back into .planner/.

Older flat slash commands such as planner-task-start were removed from Pi's global command registration to avoid autocomplete noise. Pi users should use the grouped /planner ... form.

Web UI

Agent Plan includes a local web UI served by plan-server and used by the Pi adapter.

The web UI visualizes:

project summary;
features;
phases;
tasks;
status rollups;
accepted decisions;
handoff state.

In MCP Phase 1, planner-web is exposed as a guidance/no-op tool. Full web lifecycle management from Claude Code is not finalized yet; use Pi or the server CLI for now.

Planner housekeeping

Agent Plan now creates a project-local ignore file at:

.planner/.gitignore

It ignores transient planner artifacts such as:

*.bak
*.tmp.*

Why this exists:

PlanStore uses atomic writes and backup files for safety;
backup/temp artifacts should not pollute git status;
planner recovery should stay safe without requiring manual cleanup.

At Pi session start, orphan .bak and *.tmp.* files are also cleaned up asynchronously in the background. This is automatic; there is no manual command to run.

Handoff workflow

Agent Plan supports a canonical session handoff file:

.planner/HANDOFF.md

Claude Code tools:

/planner handoff prepare
/planner handoff show
/planner handoff clear

MCP tools:

planner-handoff-prepare
planner-handoff-show
planner-handoff-write
planner-handoff-clear

The handoff should describe current focus, work in progress, resume steps, files touched, blockers, next steps, and recent decisions.

Task status discipline

Agent Plan relies on explicit task lifecycle transitions.

Before implementation work:

/planner task start <task-id>

After completed work:

/planner task complete <task-id>

Phase and feature statuses are derived from child task/phase state. Agents should not directly mutate parent status unless there is a specific reason.

Why this matters:

the dashboard header and Work Tree use active task state;
feature/phase rollups are derived from child tasks;
resume focus and handoff quality depend on correct task lifecycle transitions;
if an agent edits code without moving a task to in-progress/done, the whole planner tree becomes stale.

For this reason, Agent Plan provides dedicated lifecycle tools and blocks the wrong path:

use task_start / planner-task-start / /planner task start to begin work;
use task_complete / planner-task-complete / /planner task complete to finish work;
do not use task_update to move a task directly to in-progress or done.

Write guard and temporary bypass

Agent Plan enforces task discipline only where it matters most: write operations.

The guard exists because agents often need to inspect the repo, run tests, or pull changes before opening a task. Blocking all shell access was too restrictive. The current model therefore:

keeps bash free for git pull, build, test, search, and inspection;
blocks only edit / write when a planner exists, tasks exist, and no task is in-progress;
allows an explicit temporary bypass when the user authorizes proceeding without opening a task.

Recommended workflow:

Start the task normally:

/planner task start <task-id>

If the user explicitly wants work without opening a task, authorize a temporary bypass:

/planner bypass

Do the edit/write work.
Revoke the bypass when you want normal discipline back:

/planner clear-bypass

The same flow is available through low-level tools:

Pi/runtime tools: plan_authorize_bypass, plan_clear_bypass
Claude/MCP tools: planner-authorize-bypass, planner-clear-bypass

The bypass is stored in .planner/resume.json as guardBypassUntil, so it is shared across harnesses and auto-expires.

Claude Code task guard

agent-plan setup claude-code installs a Claude Code PreToolUse hook for Edit|Write (bash is intentionally not guarded, so git pull, build and test always work).

The hook blocks Edit/Write when no task is in-progress, unless the user has authorized a temporary bypass. The block is not a dead wall: the agent can start a task with /planner task start, OR the user can authorize a one-time bypass so Edit/Write proceeds without a task.

Authorize a bypass:

/planner bypass

or via MCP:

planner-authorize-bypass  (default 15 minutes)

Revoke:

/planner clear-bypass
planner-clear-bypass

The bypass is harness-agnostic (stored in resume.json), so Pi, Claude Code, Codex and other adapters all respect it.

Repository structure

packages/
  agent-plan/      CLI: agent-plan mcp/init/setup
  plan-core/       schemas, persistence, rendering, status logic
  plan-server/     local HTTP/WebSocket server
  plan-web-ui/     React dashboard
  plan-mcp/        MCP stdio server for Claude Code
  pi-adapter/      Pi extension adapter

Important docs:

PROJECT.md
ROADMAP.md
CHECKLIST.md
docs/multi-agent-strategy.md
docs/setup-claude-code.md

Development

Install dependencies:

pnpm install

Build/check all packages:

pnpm check

Build MCP and CLI only:

pnpm --filter @agent-plan/mcp build
pnpm --filter agent-plan build

Smoke test MCP tools locally:

node packages/agent-plan/dist/index.js mcp

For automated MCP smoke testing, use the MCP SDK client to call listTools; the expected Phase 1 count is currently 32 public planner-* tools.

Runtime implementation notes

These behaviors are mainly relevant to contributors extending the adapters:

Pi caches its injected planner context block between turns and rebuilds it only on the first turn or after planner writes. This reduces repeated I/O and large prompt regeneration on steady turns.
Pi appends a reminder after successful edit/write work when a task is active, nudging the agent to call task_complete when implementation is truly finished.
The write guard is intentionally harness-agnostic: the shared source of truth is .planner/resume.json, not a Pi-only in-memory flag.
The startup resume summary must mention the dashboard URL when the web UI is active, and must treat handoff targets as hints rather than current focus when nothing is actually in progress.

Troubleshooting

`/planner` is not available in Claude Code

Check that the slash command exists:

User scope:

~/.claude/commands/planner.md

Project scope:

.claude/commands/planner.md

Then restart Claude Code in the project.

Bash/Edit/Write is blocked in Claude Code

This is expected if .planner/ exists, tasks exist, and no task is in-progress.

Run:

/planner task start <task-id>

Then retry the implementation action.

MCP tools are not available in Claude Code

For project-local setup, check:

.mcp.json

For user-scope setup, check Claude Code's MCP list:

claude mcp list

If needed, re-run:

agent-plan setup claude-code --user --force

Design principles

.planner/ is project-local and explicit.
Markdown is generated, not the source of truth.
Core planning logic must remain harness-agnostic.
Pi, Claude Code, and future agents are adapters over the same planning model.
Installation should be global/user-level when possible; project initialization should remain explicit.
Public naming uses planner-* for MCP tools and /planner ... for human command UX.

Build and publish

This repository is a pnpm workspace. Only some packages are published to npm.

Packages

Published (public npm):

@agent-plan/core — schemas, persistence, ordering, status rollups, rendering
@agent-plan/mcp — MCP stdio server
@agent-plan/server — local HTTP/WebSocket server
agent-plan — CLI (init, mcp, setup claude-code, export, guard pre-tool-use)

Private (not published):

@agent-plan/pi-adapter — Pi extension; depends on the local monorepo layout (web UI path), so it is not a standalone npm package yet
@agent-plan/web-ui — Vite application, served as a build artifact, not a standalone npm package

Prerequisites

Node.js and pnpm installed
npm login performed (or NPM_TOKEN configured) on the account that owns the @agent-plan scope

Build and validate

From the repository root:

pnpm install
pnpm release:validate

release:validate runs the full build and the TypeScript check:

pnpm build
pnpm check

Inspect the published tarballs

Before publishing, inspect what would actually be packaged:

pnpm release:pack-dry-run

Important: use pnpm pack (or pnpm release:pack-dry-run), not npm pack.

pnpm pack/pnpm publish rewrite workspace:* dependency ranges to the real published versions inside the tarball. npm pack leaves workspace:* verbatim, which makes the resulting tarball uninstallable.

The expected tarball contents for each public package are:

dist/**/*.js, dist/**/*.d.ts, dist/**/*.d.ts.map
README.md
LICENSE
package.json

src/, tsconfig.json, and dist/.tsbuildinfo must NOT appear in the tarball.

Publish to npm

From the repository root:

pnpm release:publish

This publishes the public packages in dependency order:

@agent-plan/core
@agent-plan/mcp
@agent-plan/server
agent-plan

Each step runs pnpm publish --access public, so workspace:* ranges are rewritten to the resolved versions before upload.

Do not run npm publish manually per package: it would publish stale workspace:* ranges that npm cannot install.

Versioning

All public packages currently share version 0.1.0. To release a new version, bump the version field in each public package.json, commit, tag if desired, then run pnpm release:publish.

Install the published CLI

After publishing, end users install once:

npm install -g agent-plan

Then configure an agent harness, e.g. for Claude Code at user scope:

agent-plan setup claude-code --user

Project initialization stays explicit and is done later inside a project with /planner init or agent-plan init.

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
docs		docs
packages		packages
scripts		scripts
.gitignore		.gitignore
.pnpmrc.json		.pnpmrc.json
AGENTS.md		AGENTS.md
BACKLOG.md		BACKLOG.md
CHECKLIST.md		CHECKLIST.md
HANDOFF.md		HANDOFF.md
LICENSE		LICENSE
PROJECT.md		PROJECT.md
README.md		README.md
ROADMAP.md		ROADMAP.md
agent-plan-core-0.2.1.tgz		agent-plan-core-0.2.1.tgz
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Agent Plan

Status

Core concepts

.planner/ is the source of truth

Hierarchy

Harness-agnostic core

Recommended Claude Code setup

1. Install once

2. Initialize a project only when needed

User commands — Claude Code

Core

Project

Features

Phases

Tasks

Handoff

Export & Web

Guard bypass

Agent tools (MCP)

Core

Project

Features

Phases

Tasks

Handoff

Export

Guard bypass

Claude Code setup modes

User-scope setup, recommended

Project-local setup

Local development setup

CLI

agent-plan mcp

agent-plan init

agent-plan export

agent-plan setup claude-code

User commands — Pi

Core

Project

Features

Phases

Tasks

Handoff

Web

Export

Guard bypass

Pi session prompts and startup resume

Stable planning order and visible numbering

Web UI

Planner housekeeping

Handoff workflow

Task status discipline

Write guard and temporary bypass

Claude Code task guard

Repository structure

Development

Runtime implementation notes

Troubleshooting

/planner is not available in Claude Code

Bash/Edit/Write is blocked in Claude Code

MCP tools are not available in Claude Code

Design principles

Build and publish

Packages

Prerequisites

Build and validate

Inspect the published tarballs

Publish to npm

Versioning

Install the published CLI

About

Resources

License

Uh oh!

Stars

Watchers

`.planner/` is the source of truth

`agent-plan mcp`

`agent-plan init`

`agent-plan export`

`agent-plan setup claude-code`

`/planner` is not available in Claude Code

Packages