sgrade/plan-manager

Plan Manager

Sync AI agent(s) and models around common goals and constraints.

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 plans. Moreover, if several AI models or agents perform different tasks, for example, to optimize costs, they need to be synchronized. 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).

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 as the main GUI and the browse files function to view the raw data generated by Plan Manager.

Connecting to the Server

Connect in the devcontainer

• Start the server: uv run pm
• Endpoint: http://localhost:3000/mcp
• Browse files: http://localhost:3000/browse

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"
    }
  }
}

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.

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 for details.

Security Considerations.

Important: When binding to 0.0.0.0, the server will accept connections from any computer on your network. As authentication is not yet implemented, other people will have access to Plan Manager.

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 - .

Use the commands as explained on the workflow diagrams . 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: .

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

Development

If you want to contribute, see