plan-manager

Plan Manager

Sync AI agent(s) and models around common plan.

Overview

AI agents supported by models operate in a limited context window. If the amount of work is greater, there is a need to periodically coordinate the agent with broader context. Moreover, if several AI models or agents perform different parts of the work, for example, to optimize costs, they need to be aligned. The Plan Manager makes it easier to coordinate agents and LLMs with a plan according to user-defined constraints.

Positioning

For large projects we use project management systems like Jira or Linear. With their help, leaders coordinate work of developers.

Plan Manager is a tool for a single developer or orchestrator to coordinate work of one or more AI agents or models. For example, ask an expensive thinking model to create a plan and document it in Plan Manager. Delegate work items (stories, tasks) to less expensive models. Review the summary of work before and after the work item is completed, correct deviations from the plan. Export the report to the changelog and/or to larger project management systems.

Core concepts

• Plan: groups stories.
• Story: user-facing goal; contains tasks.
• Task: discrete unit of agent work.
• Statuses: apply to plans, stories, and tasks; primary progression is TODO → IN_PROGRESS → PENDING_REVIEW → DONE; side states: BLOCKED, DEFERRED.
• Approvals: optional guardrail before progressing status.
• Dependencies: tasks/stories may block others.
• Priority: 0–5 (0 is highest).

Installation

⚠️ Pre-release: Plan Manager is not yet published to PyPI. Install from source (see Contributing) or GitHub:

pip install git+https://github.com/sgrade/plan-manager.git

Future: PyPI Installation (when published)

# Using uv (recommended)
uv add plan-manager

# Using pip
pip install plan-manager

Quick Start

Start the Server

# Using uv
uv run pm

# Using pip installation
pm

The server will start on http://localhost:3000/mcp.

Backup and Restore (Operational)

• pm export is the only supported backup path for SQLite storage.
• pm export --plan <id> is scoped and writes only that plan's tree. It refuses to target an existing multi-plan backup directory.
• pm import --dry-run --from <dir> validates a backup tree without publishing.
• pm import --from <dir> restores a full tree; pm import --replace-plan <id> --from <dir> atomically replaces one plan.
• Export/import require the server to be offline; they refuse to run while a live server process holds the DB lock.
• Copying/tarring a live DB volume is unsupported and can produce torn WAL snapshots.
• Rollback after a cutover is safe only if you exported first; otherwise post-cutover writes are lost.
• Exit codes: 0 on success, non-zero on failure.

Connect from Cursor IDE

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "plan-manager": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Usage

Convenience

Plan manager is stable and has proven to be very useful for coordinating the actions of AI agents and models working on the same project. On the other hand, it may lack the user-friendly interface, flexibility, and other qualities that are expected from a mature product aimed at a wide audience. This is a reasonable decision: to develop quickly with limited resources; to focus on functions that arise as a result of practical use in real projects, and to avoid the overhead of non-core development.

Currently, the most convenient way is to run Plan Manager in devcontainer on the same laptop/desktop computer where you have IDE/agents. Use web interface of MCP Inspector as the main GUI and the read-only /ui page for supervision.

Connecting to the Server

Connect in the devcontainer

• Start the server: uv run pm
• Endpoint: http://localhost:3000/mcp
• Read-only supervision UI: http://localhost:3000/ui

Connect from another container on the same host.

Change localhost to host.docker.internal in the MCP configuration. For example:

{
  "mcpServers": {
    "plan-manager": {
      "url": "http://host.docker.internal:3000/mcp"
    }
  }
}

Logs go to stdout (12-factor); use docker logs / docker compose logs to read them. Note that recreating a container discards its logs — capture them first when investigating an incident, or temporarily set PLAN_MANAGER_ENABLE_FILE_LOG=true and LOG_DIR=/data/logs to persist logs onto the mounted volume during an investigation window.

Connect from another host

Set environment variable HOST=0.0.0.0 when starting the server, then connect using the host's IP address instead of localhost.

Warning: the /ui page is intentionally unauthenticated in this phase. If you bind to 0.0.0.0, treat it as world-readable from your reachable network.

If starting Plan Manager in the devcontainer, you can add the environment variable to existing ones in the devcontainer.json by modifying containerEnv.

{
  "containerEnv": {
    "HOST": "0.0.0.0"
  }
}

See docs/config_reference.md for details.

Security Considerations.

Important: When binding to 0.0.0.0, the server will accept connections from any computer on your network. The read-only /ui page is unauthenticated in this phase, so LAN-exposed means world-readable.

Hints

Instruct the AI agent to use Plan Manager, when you start a new chat.

Use / in the client (Cursor) chat window to list Plan Manager prompts (instructions, templates to interact with the server).

Use MCP inspector to explore Plan Manager capabilities - doc.

Use the commands as explained on the workflow diagrams docs/project_workflow.md. In this way the agents/LLMs need to think less to understand what you mean, so they respond much faster, the request is cheaper, and the result is more predictable.

There is a document primarily for agents using Plan Manager, which can also be useful for humans to understand how the agents learn about Plan Manager: usage_guide_agents.md.

Both documents are exposed as an MCP resources to the agents.

Contributing

Want to contribute? See docs/contributing.md for development setup, testing, and guidelines.

Documentation

For Users & Agents

• Usage Guide for Agents - How agents interact with Plan Manager
• Project Workflow - Workflow diagrams and patterns
• Configuration Reference - Environment variables and settings

For Developers

• Contributing Guide - Development setup and guidelines
• Triage Guide - Issue triage process
• Release Checklist - Release process

License

This repository is dual-licensed:

• Code — Apache License 2.0. See LICENSE.
• Documentation — Creative Commons Attribution 4.0 International (CC-BY-4.0). See LICENSE-docs.

If reusing the documentation, please credit:

plan-manager — © 2026 Roman Klyuev — licensed under CC-BY-4.0 — https://github.com/sgrade/plan-manager

Apache-2.0 §4(d) attribution for the code is provided in NOTICE and must be propagated by downstream consumers.

Releases through v0.11.0 were published under the MIT License; the relicense to Apache-2.0 + CC-BY-4.0 applies from the next release onward. Those earlier tagged versions remain available under MIT.

Acknowledgments

Built with:

• FastMCP - MCP server framework
• Pydantic - Data validation
• Starlette - ASGI framework
• uv - Fast Python package manager