Pm
A Model Context Protocol server for managing background processes
Installation
npx pmAsk AI about Pm
Powered by Claude Β· Grounded in docs
I know everything about Pm. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Project Manager MCP
Quick Start
Option 1: Claude Code Plugin (Recommended)
The easiest way to get started with Claude Code:
# Add the plugin marketplace
/plugin marketplace add https://github.com/Commands-com/pm.git
# Install the plugin
/plugin install pm
# Restart Claude Code - you're ready to go!
This automatically installs:
- β
MCP server (via
uvx) - β
All
/pm:*slash commands - β Specialized agents (adaptive-assessor, task-runner, etc.)
Option 2: Manual Installation
- Install from PyPI
pip install project-manager-mcp
# or
uvx project-manager-mcp
- Add MCP server to your AI assistant:
Claude Code:
claude mcp add project-manager -- uvx project-manager-mcp
Codex:
[mcp_servers.project-manager-mcp]
command = "uvx"
args = ["project-manager-mcp"]
Gemini:
"mcpServers": {
"project-manager": {
"type": "stdio",
"command": "uvx",
"args": ["project-manager-mcp"],
"env": {}
}
}
- Install Claude assets (commands & agents) to your project:
project-manager-mcp install-claude-assets --target-dir ~/my-project
Features
A comprehensive project management system with Model Context Protocol (MCP) support, enabling AI agents to manage projects, epics, and tasks through both programmatic interfaces and a web dashboard.
- AI Agent Integration: MCP tools for autonomous project management
- Web Dashboard: Real-time web interface for project visualization
- Task Locking System: Atomic operations prevent concurrent modifications
- WebSocket Updates: Real-time synchronization across all clients
- SQLite Backend: Lightweight, serverless database with WAL mode
- Zero-Config Setup: Single command deployment with automatic port allocation
- Project Import: YAML-based project definition and import system
- RA Tag Context Detection: Zero-effort context capture for Response Awareness tags
- Auto-Activating Skills: Claude Code skills that automatically load based on context
- Quality Gate Hooks: Automatic build checks and RA awareness reminders
Skills + Hooks System
PM Dashboard includes an auto-activation system that ensures Claude actually uses skills and enforces quality standards:
Skills (Knowledge Layer)
Four skills automatically activate based on what you're working on:
-
ra-methodology - Response Awareness methodology enforcement
- Activates when: Creating tasks, discussing complexity, managing projects
- Contains: Complexity scoring, RA modes, tagging guide, workflow examples
-
pm-dashboard-dev - Development patterns and architecture
- Activates when: Working in
src/task_manager/, adding MCP tools, writing tests - Contains: Project structure, adding tools guide, testing requirements, code patterns
- Activates when: Working in
-
knowledge-management - Capture hard-won insights
- Activates when: Encountering gotchas, multi-attempt solutions, user corrections
- Contains: What to capture vs skip, knowledge hierarchy, category guidelines
-
task-locking - Atomic locking patterns
- Activates when: Working with task locks, concurrent operations, multi-agent workflows
- Contains: Atomic patterns, lock lifecycle, multi-agent coordination
Hooks (Enforcement Layer)
Three hooks ensure quality and consistency:
-
UserPromptSubmit - Analyzes prompts BEFORE Claude sees them
- Matches keywords and intent patterns against skill rules
- Injects skill activation reminders into the conversation
- Ensures relevant skills load automatically
-
Post-Tool-Use - Tracks file edits during work
- Logs all Edit/Write operations
- Builds list for Stop hook to process
- Enables "#NoMessLeftBehind" quality gates
-
Stop Event - Runs after Claude finishes responding
- Build Checker: Runs
mypy,black,pyteston modified files - RA Tag Reminder: Prompts to add tags for task implementations
- Knowledge Capture Reminder: Suggests capturing trial-and-error solutions
- Build Checker: Runs
How It Works
User asks: "Create a task with complexity 7"
β
UserPromptSubmit Hook matches: ra-methodology skill
β
Injects: "π― Use ra-methodology skill"
β
Claude sees prompt with skill reminder
β
ra-methodology skill automatically loads
β
Claude follows RA methodology patterns
β
Stop Hook checks: RA tags added? Tests passing?
Benefits
Before Skills + Hooks:
- β RA methodology documented but not enforced
- β Skills sit unused
- β Errors slip through
- β Inconsistent code
After Skills + Hooks:
- β RA methodology automatically enforced
- β Skills activate when needed
- β Zero errors left behind
- β Consistent quality
See skills/ and hooks/ directories for implementation details.
Installation & Usage
Installation Options
# Install from source (development)
pip install -e .
# Or install development dependencies
pip install -e .[dev]
# Run directly with uvx (no installation needed)
uvx --from . project-manager-mcp
Basic Usage
# Start with default configuration (dashboard on :8080, MCP over stdio)
project-manager-mcp
# Custom port and options
project-manager-mcp --port 9000 --no-browser
# Import a project on startup
project-manager-mcp --project examples/simple-project.yaml
# MCP over stdio (default; for shell integration)
project-manager-mcp --mcp-transport stdio
# Add RA tags with automatic context detection
python -m task_manager.cli add-ra-tag "#COMPLETION_DRIVE_IMPL: Assuming user validation upstream" --task-id 123
# Install Claude agents and commands to your project
project-manager-mcp install-claude-assets --target-dir ~/my-project
After startup, access the dashboard at http://localhost:8080 (or your chosen port).
MCP Client Integration
Connect MCP clients to interact programmatically:
# Stdio transport (default)
# Connect via stdin/stdout
# SSE transport (optional)
project-manager-mcp --mcp-transport sse
# Connect to http://localhost:8081/sse
# Using uvx for MCP integration
uvx --from . project-manager-mcp --mcp-transport stdio
uvx --from . project-manager-mcp --mcp-transport sse --port 9000
Architecture Overview
Core Components
- CLI Interface (
task_manager.cli): Zero-config server coordination - FastAPI Backend (
task_manager.api): REST endpoints and WebSocket broadcasting - MCP Server (
task_manager.mcp_server): AI agent tool integration - Database Layer (
task_manager.database): SQLite with atomic locking - MCP Tools (
task_manager.tools): GetAvailableTasks, AcquireTaskLock, UpdateTaskStatus, ReleaseTaskLock, AddRATag - Context Detection (
task_manager.context_utils): Automatic file, git, and symbol context detection
Data Model
Projects (top-level containers)
βββ Epics (high-level initiatives)
βββ Tasks (specific work items)
Each task supports:
- Status tracking: pending β in_progress β completed
- Atomic locking: Prevent concurrent modifications
- Agent assignment: Track work ownership
- Real-time updates: WebSocket broadcasting
- RA Tag Context: Automatic context detection for Response Awareness tags
Transport Modes
- SSE (Server-Sent Events): HTTP-based MCP for network clients
- Stdio: Pipe-based MCP for shell and local integration
- None: Dashboard-only mode without MCP server
Key Features
Atomic Task Locking
Two patterns are supported:
- Single-call update (auto-lock):
# Automatically acquires a short-lived lock if unlocked, updates status, then releases.
mcp_client.call_tool("update_task_status", {
"task_id": "123",
"status": "DONE", # UI vocabulary also accepted
"agent_id": "agent-1"
})
- Explicit lock + update (long-running work):
# Acquire exclusive lock on task (status moves to IN_PROGRESS)
mcp_client.call_tool("acquire_task_lock", {
"task_id": "123",
"agent_id": "agent-1",
"timeout": 300
})
# Perform work...
# Update status and auto-release on DONE
mcp_client.call_tool("update_task_status", {
"task_id": "123",
"status": "DONE",
"agent_id": "agent-1"
})
Real-time Dashboard Updates
WebSocket events keep all clients synchronized:
task.status_changed- Task status updatestask.locked- Task lock acquisitiontask.unlocked- Task lock release
Project Import System
Define projects in YAML and import on startup:
projects:
- name: "User Management System"
description: "Complete user lifecycle management"
epics:
- name: "User Authentication"
status: "ACTIVE"
tasks:
- name: "Create registration form"
status: "TODO"
- name: "Implement login validation"
status: "TODO"
Use Cases
AI Agent Workflows
- Query available work:
get_available_tasks - Claim exclusive access:
acquire_task_lock - Update progress:
update_task_status - Release when done: Auto-release on completion
Multi-Agent Coordination
- Prevent conflicts: Atomic locking prevents multiple agents on same task
- Work distribution: Available task querying enables load balancing
- Progress tracking: Status updates provide visibility across agents
- Real-time sync: WebSocket updates keep all systems current
Dashboard Management
- Project visualization: Project β Epic β Task hierarchy
- Real-time monitoring: Live updates from agent activity
- Manual intervention: Override task states when needed
- Project import: Load new projects without restart
Configuration
CLI Options
--port PORT: Dashboard server port (default: 8080)--mcp-transport {stdio|sse|none}: MCP transport mode (default: stdio)--project PATH: Import project YAML on startup--no-browser: Skip automatic browser launch--host HOST: Server bind address (default: 127.0.0.1)--db-path PATH: Database file location (default: project_manager.db)--verbose: Enable debug logging
Claude Assets Installation
Install Claude Code agents and commands to your projects:
# Install both agents and commands to a project
project-manager-mcp install-claude-assets --target-dir ~/my-project
# Install with overwrite protection
project-manager-mcp install-claude-assets --target-dir ~/my-project --force
# Install only agents
project-manager-mcp install-claude-assets --target-dir ~/my-project --agents-only
# Install only commands
project-manager-mcp install-claude-assets --target-dir ~/my-project --commands-only
# Verbose output showing all installed files
project-manager-mcp install-claude-assets --target-dir ~/my-project --verbose
# Alternative standalone command
pm-install-claude-assets --target-dir ~/my-project
This creates a .claude/ directory in your target location with:
- Agents (
.claude/agents/): Specialized agents for adaptive assessment, planning review, task execution, and verification - Commands (
.claude/commands/pm/): Project management commands for task workflow, epic management, and status tracking
Environment Variables
DATABASE_PATH: Override default database locationDEBUG: Enable verbose logging
Performance Characteristics
- Startup time: < 2 seconds with empty database
- Task operations: < 50ms for lock acquisition/release
- WebSocket latency: < 10ms for local connections
- Concurrent agents: Tested with 50+ simultaneous agents
- Database size: Handles 10,000+ tasks efficiently
Error Recovery
- Port conflicts: Automatic alternative port allocation
- Database corruption: WAL mode provides crash recovery
- WebSocket disconnections: Automatic reconnection handling
- Lock timeouts: Automatic cleanup of expired locks
- Agent failures: Lock expiration prevents indefinite blocking
Security Model
- No authentication: Open access for development and testing
- Local binding: Default 127.0.0.1 limits network exposure
- File permissions: Database protected by filesystem ACLs
- Input validation: Pydantic models prevent injection attacks
- Resource limits: Lock timeouts prevent resource exhaustion
Troubleshooting
Common Issues
Port already in use
# Use alternative ports
project-manager-mcp --port 9000
# Check what's using the port
lsof -i :8080
Database locked errors
# Check for competing processes
ps aux | grep project-manager-mcp
# Remove database if corrupted
rm project_manager.db
WebSocket connection refused
# Verify server is running
curl http://localhost:8080/healthz
# Check WebSocket endpoint
curl -H "Upgrade: websocket" http://localhost:8080/ws/updates
MCP client connection issues
# Test SSE endpoint (when using --mcp-transport sse)
curl http://localhost:8081/sse
# For stdio mode, verify no conflicting processes
project-manager-mcp --mcp-transport stdio --verbose
Documentation
- Detailed Usage Guide - CLI options, MCP tools, WebSocket events
- API Documentation - REST endpoints, request/response formats
- Development Guide - Contributing, testing, architecture decisions
- RA Tag Context Usage Guide - Complete guide for Response Awareness tag context detection
Examples
examples/simple-project.yaml- Basic project structureexamples/complex-project.yaml- Multi-epic enterprise project
License
This project is licensed under the MIT License - see the LICENSE file for details.
You are free to use, modify, and distribute this software for any purpose, including commercial use.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for:
- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process
- Response Awareness (RA) methodology guidelines
For detailed architecture and development information, see Development Guide.
