https://github.com/sgrade/plan-manager
Sync AI agents and models around common plan.
https://github.com/sgrade/plan-manager
ai cursor mcp model-context-protocol planning project-management vscode
Last synced: 3 months ago
JSON representation
Sync AI agents and models around common plan.
- Host: GitHub
- URL: https://github.com/sgrade/plan-manager
- Owner: sgrade
- License: mit
- Created: 2025-07-28T16:34:45.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-10-26T18:28:32.000Z (8 months ago)
- Last Synced: 2025-10-26T20:35:30.291Z (8 months ago)
- Topics: ai, cursor, mcp, model-context-protocol, planning, project-management, vscode
- Language: Python
- Homepage:
- Size: 613 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Plan Manager
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/sgrade/plan-manager/actions/workflows/ci.yml)
[](https://codecov.io/gh/sgrade/plan-manager)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
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](docs/contributing.md)) or GitHub:
>
> ```bash
> pip install git+https://github.com/sgrade/plan-manager.git
> ```
### Future: PyPI Installation (when published)
```bash
# Using uv (recommended)
uv add plan-manager
# Using pip
pip install plan-manager
```
## Quick Start
### Start the Server
```bash
# Using uv
uv run pm
# Using pip installation
pm
```
The server will start on `http://localhost:3000/mcp`.
### Connect from Cursor IDE
Add to your `.cursor/mcp.json`:
```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](dev/mcp-inspector/README.md) 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:
```json
{
"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`.
```json
{
"containerEnv": {
"HOST": "0.0.0.0"
}
}
```
See [docs/config_reference.md](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. 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 - [doc](dev/mcp-inspector/README.md).
Use the commands as explained on the workflow diagrams [docs/project_workflow.md](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](docs/usage_guide_agents.md).
Both documents are exposed as an MCP [resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) to the agents.
## Contributing
Want to contribute? See [docs/contributing.md](docs/contributing.md) for development setup, testing, and guidelines.
## Documentation
### For Users & Agents
- [Usage Guide for Agents](docs/usage_guide_agents.md) - How agents interact with Plan Manager
- [Project Workflow](docs/project_workflow.md) - Workflow diagrams and patterns
- [Configuration Reference](docs/config_reference.md) - Environment variables and settings
### For Developers
- [Contributing Guide](docs/contributing.md) - Development setup and guidelines
- [Triage Guide](docs/triage_guide.md) - Issue triage process
- [Release Checklist](docs/release_checklist.md) - Release process
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation
- [Starlette](https://www.starlette.io/) - ASGI framework
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager