v0.1.0 — Open Source

Stop losing your plan
between agent sessions

Workplanr turns work plans into a git-native, branch-aware interface that AI agents read through MCP and humans monitor in real time.

View on GitHub Read the Docs

$ npm install -g workplanr

workplanr

$ wp list

branch: feature/auth 4 tasks

[✓] task-001 Setup project ██████████ 100% high

[●] task-002 Implement auth ██████████ 60% critical

[○] task-003 Write tests ██████████ 0% medium

[○] task-004 Deploy to staging ██████████ 0% low

● in_progress ○ pending ✓ done ✗ blocked

The Problem

AI agents are fast.
But they forget everything.

Working with coding agents today is like managing a brilliant developer who gets amnesia every time they close their laptop.

Session Amnesia

The agent loses the entire plan the moment the session closes. Next session? Starts from scratch. Every. Single. Time.

Context Drift

Without a structured plan, agents wander. They start "fixing" code you didn't ask about, or loop on the same problem for 20 minutes.

Zero Visibility

You have no idea what the agent is doing, how far along it is, or whether it's even working on the right thing. It's a black box.

The Solution

A plan that lives in your repo.

.planr/plan.json is a structured work plan inside your git repository. It changes with branches, resolves conflicts like code, and is accessible to any MCP-compatible agent.

Git-Native Storage

The plan is a JSON file in your repo. Committed, versioned, diffable. No external databases, no cloud sync, no vendor lock-in.

Branch-Aware

Switch to feature/payments and the plan switches with it. Each branch has its own tasks, its own progress, its own state.

Definition of Done

Each task can have a DoD checklist with auto-validated shell commands. The agent literally cannot mark a task "done" if tests fail.

Human-in-the-Loop

Agent thinks a task is too big? It proposes subtasks. You approve or reject in the TUI or CLI. The agent waits for your decision.

MCP Protocol

Works with any MCP-compatible agent: Claude Code, Aider, Cursor, or your own. Not locked to any vendor.

Zero Cloud

Everything runs locally. Your plan, your machine, your git repo. No accounts to create, no data leaving your system.

How It Works

10-step agent workflow

From plan creation to task completion — here's how humans and agents collaborate through Workplanr.

Human creates a plan

wp init + wp add "Implement auth"

Agent starts a session

Calls get_plan to see all tasks, priorities, and dependencies

Agent picks up work

Calls get_next_task — gets the highest priority task with all deps satisfied

Agent reports progress

Calls update_task_progress after each significant step. Human sees updates in real time.

Task too big? Propose subtasks

Agent calls propose_subtasks. Parent task is blocked until human approves.

Human approves

wp propose approve prop-001 — subtasks are created, work continues

Agent validates Definition of Done

Calls validate_dod — runs tests, linter, type checker automatically

Agent completes the task

Calls complete_task — only succeeds if all DoD checks pass

Next task, automatically

Agent calls get_next_task again. Dependencies are recalculated. Work continues.

Human monitors everything

wp tui — live-updating dashboard. Or wp list for a quick check.

Feature	Shrimp / planner-mcp	saga-mcp	Workplanr
Plan stored in repo (git-native)	✗	✗	✓
Branch-aware plan	✗	✗	✓
Definition of Done validation	✗	✗	✓
Human-in-the-loop approval	✗	✗	✓
Zero cloud dependency	✓	✓	✓
Vendor-agnostic (any MCP client)	✓	✓	✓

Quick Start

Set up in 2 minutes

Install globally, initialize in your project, connect your agent.

# Install globally
npm install -g workplanr

# Initialize in your project
cd my-project
wp init --name "My Project" --goal "Ship v2.0"

# Add tasks
wp add "Implement authentication" --priority critical
wp add "Write tests" --priority high --depends-on task-001
wp add "Deploy" --priority medium --depends-on task-001,task-002

# See your plan
wp list

# Start MCP server for AI agents
wp serve
        

// .claude/mcp.json
{
  "mcpServers": {
    "workplanr": {
      "command": "wp",
      "args": ["serve"]
    }
  }
}

// Add to AGENTS.md or CLAUDE.md:
//
// 1. Call get_plan at session start
// 2. Call get_next_task before starting work
// 3. Call update_task_progress after each step
// 4. Call validate_dod before completing
// 5. Call complete_task only when DoD passes
        

# .aider.conf.yml
mcp_servers:
  - name: workplanr
    command: wp
    args: [serve]
        

# .planr/dod/task-001.md
# Definition of Done: Implement authentication

## Required
- [ ] `npm test` -- all tests pass
- [ ] `npm run lint` -- no lint errors
- [ ] `tsc --noEmit` -- no type errors
- [ ] Auth module has JSDoc comments

## Optional
- [ ] Test coverage >= 80%
- [ ] CHANGELOG.md updated

# Commands in backticks are executed automatically.
# Task cannot be completed if Required items fail.
        

Stop losing your plan
between agent sessions

AI agents are fast.
But they forget everything.

Session Amnesia

Context Drift

Zero Visibility

A plan that lives in your repo.

Git-Native Storage

Branch-Aware

Definition of Done

Human-in-the-Loop

MCP Protocol

Zero Cloud

10-step agent workflow

Human creates a plan

Agent starts a session

Agent picks up work

Agent reports progress

Task too big? Propose subtasks

Human approves

Agent validates Definition of Done

Agent completes the task

Next task, automatically

Human monitors everything

Why not existing tools?

Set up in 2 minutes

Plan like code.
Ship with agents.

Stop losing your planbetween agent sessions

AI agents are fast.But they forget everything.

Session Amnesia

Context Drift

Zero Visibility

A plan that lives in your repo.

Git-Native Storage

Branch-Aware

Definition of Done

Human-in-the-Loop

MCP Protocol

Zero Cloud

10-step agent workflow

Human creates a plan

Agent starts a session

Agent picks up work

Agent reports progress

Task too big? Propose subtasks

Human approves

Agent validates Definition of Done

Agent completes the task

Next task, automatically

Human monitors everything

Why not existing tools?

Set up in 2 minutes

Plan like code.Ship with agents.

Stop losing your plan
between agent sessions

AI agents are fast.
But they forget everything.

Plan like code.
Ship with agents.