Project Manager

PyPI version Python 3.9+ License: MIT Code style: black

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

1. Install from PyPI

pip install project-manager-mcp
# or
uvx project-manager-mcp

2. 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": {}
  }
}

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

1. ra-methodology - Response Awareness methodology enforcement

   • Activates when: Creating tasks, discussing complexity, managing projects
   • Contains: Complexity scoring, RA modes, tagging guide, workflow examples

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

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

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

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

2. Post-Tool-Use - Tracks file edits during work

   • Logs all Edit/Write operations
   • Builds list for Stop hook to process
   • Enables "#NoMessLeftBehind" quality gates

3. Stop Event - Runs after Claude finishes responding

   • Build Checker: Runs mypy, black, pytest on modified files
   • RA Tag Reminder: Prompts to add tags for task implementations
   • Knowledge Capture Reminder: Suggests capturing trial-and-error solutions

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

1. SSE (Server-Sent Events): HTTP-based MCP for network clients
2. Stdio: Pipe-based MCP for shell and local integration
3. None: Dashboard-only mode without MCP server

Key Features

Atomic Task Locking

Two patterns are supported:

1. 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"
})

2. 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 updates
• task.locked - Task lock acquisition
• task.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

1. Query available work: get_available_tasks
2. Claim exclusive access: acquire_task_lock
3. Update progress: update_task_status
4. 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 location
• DEBUG: 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 structure
• examples/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.