{"id":39478551,"url":"https://github.com/sgrade/plan-manager","last_synced_at":"2026-03-12T11:14:21.436Z","repository":{"id":311182270,"uuid":"1027859816","full_name":"sgrade/plan-manager","owner":"sgrade","description":"Sync AI agents and models around common plan.","archived":false,"fork":false,"pushed_at":"2025-10-26T18:28:32.000Z","size":628,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-26T20:35:30.291Z","etag":null,"topics":["ai","cursor","mcp","model-context-protocol","planning","project-management","vscode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgrade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-28T16:34:45.000Z","updated_at":"2025-10-23T10:28:57.000Z","dependencies_parsed_at":"2025-08-22T17:51:08.205Z","dependency_job_id":"a32d8620-575a-493e-a8e1-6201e8e8b317","html_url":"https://github.com/sgrade/plan-manager","commit_stats":null,"previous_names":["sgrade/plan-manager"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/sgrade/plan-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgrade%2Fplan-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgrade%2Fplan-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgrade%2Fplan-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgrade%2Fplan-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgrade","download_url":"https://codeload.github.com/sgrade/plan-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgrade%2Fplan-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28530617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cursor","mcp","model-context-protocol","planning","project-management","vscode"],"created_at":"2026-01-18T05:00:38.714Z","updated_at":"2026-01-18T05:01:02.983Z","avatar_url":"https://github.com/sgrade.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plan Manager\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python: 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![CI](https://github.com/sgrade/plan-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/sgrade/plan-manager/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/sgrade/plan-manager/branch/main/graph/badge.svg)](https://codecov.io/gh/sgrade/plan-manager)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)\n\nSync AI agent(s) and models around common plan.\n\n## Overview\n\nAI 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.\n\n## Positioning\n\nFor large projects we use project management systems like Jira or Linear. With their help, leaders coordinate work of developers.\n\nPlan 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.\n\n## Core concepts\n\n- Plan: groups stories.\n- Story: user-facing goal; contains tasks.\n- Task: discrete unit of agent work.\n- Statuses: apply to plans, stories, and tasks; primary progression is TODO → IN_PROGRESS → PENDING_REVIEW → DONE; side states: BLOCKED, DEFERRED.\n- Approvals: optional guardrail before progressing status.\n- Dependencies: tasks/stories may block others.\n- Priority: 0–5 (0 is highest).\n\n## Installation\n\n\u003e ⚠️ **Pre-release:** Plan Manager is not yet published to PyPI.\n\u003e Install from source (see [Contributing](docs/contributing.md)) or GitHub:\n\u003e\n\u003e ```bash\n\u003e pip install git+https://github.com/sgrade/plan-manager.git\n\u003e ```\n\n### Future: PyPI Installation (when published)\n\n```bash\n# Using uv (recommended)\nuv add plan-manager\n\n# Using pip\npip install plan-manager\n```\n\n## Quick Start\n\n### Start the Server\n\n```bash\n# Using uv\nuv run pm\n\n# Using pip installation\npm\n```\n\nThe server will start on `http://localhost:3000/mcp`.\n\n### Connect from Cursor IDE\n\nAdd to your `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"plan-manager\": {\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n## Usage\n\n### Convenience\n\nPlan 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.\n\nCurrently, 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.\n\n### Connecting to the Server\n\n#### Connect in the devcontainer\n\n- **Start the server:** `uv run pm`\n- **Endpoint:** `http://localhost:3000/mcp`\n- **Browse files:** `http://localhost:3000/browse`\n\n#### Connect from another container on the same host.\n\nChange `localhost` to `host.docker.internal` in the MCP configuration. For example:\n\n```json\n{\n  \"mcpServers\": {\n    \"plan-manager\": {\n      \"url\": \"http://host.docker.internal:3000/mcp\"\n    }\n  }\n}\n```\n\n#### Connect from another host\n\nSet environment variable `HOST=0.0.0.0` when starting the server, then connect using the host's IP address instead of `localhost`.\n\nIf starting Plan Manager in the devcontainer, you can add the environment variable to existing ones in the devcontainer.json by modifying `containerEnv`.\n\n```json\n{\n  \"containerEnv\": {\n    \"HOST\": \"0.0.0.0\"\n  }\n}\n```\n\nSee [docs/config_reference.md](docs/config_reference.md) for details.\n\nSecurity Considerations.\n\nImportant: 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.\n\n### Hints\n\nInstruct the AI agent to use Plan Manager, when you start a new chat.\n\nUse `/` in the client (Cursor) chat window to list Plan Manager prompts (instructions, templates to interact with the server).\n\nUse MCP inspector to explore Plan Manager capabilities - [doc](dev/mcp-inspector/README.md).\n\nUse 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.\n\nThere 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).\n\nBoth documents are exposed as an MCP [resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) to the agents.\n\n## Contributing\n\nWant to contribute? See [docs/contributing.md](docs/contributing.md) for development setup, testing, and guidelines.\n\n## Documentation\n\n### For Users \u0026 Agents\n- [Usage Guide for Agents](docs/usage_guide_agents.md) - How agents interact with Plan Manager\n- [Project Workflow](docs/project_workflow.md) - Workflow diagrams and patterns\n- [Configuration Reference](docs/config_reference.md) - Environment variables and settings\n\n### For Developers\n- [Contributing Guide](docs/contributing.md) - Development setup and guidelines\n- [Triage Guide](docs/triage_guide.md) - Issue triage process\n- [Release Checklist](docs/release_checklist.md) - Release process\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nBuilt with:\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework\n- [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation\n- [Starlette](https://www.starlette.io/) - ASGI framework\n- [uv](https://github.com/astral-sh/uv) - Fast Python package manager\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgrade%2Fplan-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgrade%2Fplan-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgrade%2Fplan-manager/lists"}