AgentPM

AgentPM is a planning and orchestration system for AI-driven software development. Installed locally as an MCP server, it integrates with any IDE that supports Anthropic's Model Context Protocol specification, including Cursor, Augment, VS Code Copilot, Cline and Roo.

AgentPM serves the role of product manager, helping developers plan, prioritize, and execute complex projects:

- Develops comprehensive requirements
- Breaks down complex projects into actionable tasks with clear dependencies
- Orchestrates implementation with context-aware assistance
- Delivers relevant documentation and context when needed
- Guides technical decisions and systems design
- Promote software development best practices (TDD, vertical slicing)

<https://github.com/user-attachments/assets/6ddb551c-0c10-4a93-8665-fc5c1e3127c1>

Why AgentPM?

- Frictionless Setup: Get started simply by chatting with your coding agent - no CLIs or complex rules needed.

- Token/Context Optimization: Consolidates functionality around a core set of dynamic tools that are contextually economical and easy for coding agents to use and understand.

- Intelligent Context Management: Delivers the right information to your coding agent at the right time, optimizing token usage and eliminating the need for manual context handling or "memory banks".

- Structured Output: Automatically generates clear, human-readable markdown documents; no need to decipher JSON or plain text files.

- Integrated Documentation Retrieval: Automatically retrieve relevant documentation through Context7 integration.

- Comprehensive Task Management: Creates well-structured tasks with proper dependencies, priorities, implementation details, and status tracking. Complex work can be broken down into manageable subtasks with clear relationships.

- Flexible Requirements Process: Works with or without existing documentation, guiding you through a structured interview when starting from scratch, or easily adapting to an existing project or plan.

- AI-Powered Generation: Leverages Claude Sonnet 3.7 for consistent task generation regardless of IDE coding model, with optional Perplexity API integration for research-backed results.

- Adaptive Project Evolution: Updates future tasks based on completed work to handle implementation drift, while maintaining living documentation that evolves with your project.

- Best Practices Built-in: Incorporates software development best practices with opinionated recommendations that improve code quality.

- Seamless IDE Integration: Works directly within your preferred development environment through Model Context Protocol support.

Getting Started

Prerequisites

- Node.js: Version 20.0.0 or higher
- Anthropic API Key: For Claude AI integration
- Perplexity API Key: For research-backed task generation

Installation & Configuration

Cursor

Add the following to your project's .cursor/mcp.json file (or install globally at ~/.cursor/mcp.json).

{
    "mcpServers": {
        "agent-pm": {
          "command": "npx",
          "args": [
            "-y",
            "@gannonh/agent-pm@latest"
          ],
          "env": {
            "PROJECT_ROOT": "/path/to/project/root/",
            "ANTHROPIC_API_KEY": "sk-your-anthropic-api-key",
            "PERPLEXITY_API_KEY": "pplx-your-perplexity-api-key"
          }
        }
    }
  }
  

Augment

Add the following to your VS-Code Augment User Settings file (CMD+SHIFT+P > Augment: Edit Settings > Edit in settings.json): ~/Library/Application Support/Code/User/settings.json.

"augment.advanced": {
"mcpServers": [

    {

      "name": "agent-pm",

      "command": "npx",

          "args": [

            "-y",

            "@gannonh/agent-pm@latest"

          ],

          "env": {

            "PROJECT_ROOT": "/path/to/project/root/",

            "ANTHROPIC_API_KEY": "sk-your-anthropic-api-key",

            "PERPLEXITY_API_KEY": "pplx-your-perplexity-api-key"

    },

  ]

}

For more information on MCP server configuration, refer to the documentation for your specific IDE:

- Cursor MCP Server Docs
- Augment MCP Server Docs
- VS Code Copilot MCP Server Docs
- Cline MCP Server Docs

Environment Variables

> ⚠️ Warning: Most configuration options have been carefully tuned for optimal results. Unless you have specific requirements, it's recommended to only set the required variables and leave the rest at their default values.

Required Variables

| Variable | Description | Default |
| ------------------- | --------------------------------- | ----------------- |
| PROJECT_ROOT | Path to the project directory | Current directory |
| ANTHROPIC_API_KEY | API key for Claude AI integration | None |

Common Optional Variables

| Variable | Description | Default |
| -------------------- | ------------------------------------- | ------- |
| PERPLEXITY_API_KEY | API key for Perplexity AI integration | None |
| DEBUG_LOGS | Enable debug mode with file logging | false |

Advanced Configuration (Not Recommended to Change)

Anthropic API Configuration

| Variable | Description | Default | | -------------------------- | --------------------------------- | ------------------------------ | | ANTHROPIC_MODEL | Claude model to use | "claude-3-7-sonnet-20250219" | | ANTHROPIC_TEMPERATURE | Temperature for Claude API calls | 0.2 | | ANTHROPIC_MAX_TOKENS | Maximum tokens for Claude API | 64000 | | ANTHROPIC_MAX_CACHE_SIZE | Maximum cache size for Claude API | 100 | | ANTHROPIC_CACHE_TTL | Cache TTL for Claude API (ms) | 3600000 | | ANTHROPIC_MAX_RETRIES | Maximum retries for Claude API | 5 | | ANTHROPIC_BASE_URL | Base URL for Claude API | "https://api.anthropic.com" | | ANTHROPIC_SYSTEM_PROMPT | System prompt for Claude API | "You are a helpful assistant." |

Perplexity API Configuration

| Variable | Description | Default | | --------------------------- | ------------------------------------- | --------------------------------------------------------------------------------- | | PERPLEXITY_MODEL | Perplexity model to use | "sonar-pro" | | PERPLEXITY_MAX_TOKENS | Maximum tokens for Perplexity API | 1024 | | PERPLEXITY_MAX_CACHE_SIZE | Maximum cache size for Perplexity API | 100 | | PERPLEXITY_CACHE_TTL | Cache TTL for Perplexity API (ms) | 3600000 | | PERPLEXITY_MAX_RESULTS | Maximum results for Perplexity API | 5 | | PERPLEXITY_MAX_RETRIES | Maximum retries for Perplexity API | 5 | | PERPLEXITY_BASE_URL | Base URL for Perplexity API | "https://api.perplexity.ai" | | PERPLEXITY_TEMPERATURE | Temperature for Perplexity API calls | 0.7 | | PERPLEXITY_SYSTEM_PROMPT | System prompt for Perplexity API | "You are a helpful research assistant. Provide factual information with sources." |

File and Directory Configuration

| Variable | Description | Default | | -------------------- | -------------------------- | ------------------ | | ARTIFACTS_DIR | Directory for artifacts | "apm-artifacts" | | ARTIFACTS_FILE | Filename for artifacts | "artifacts.json" | | PRODUCT_BRIEF_FILE | Filename for project brief | "project-brief.md" |

Debug Mode

Setting DEBUG_LOGS=true enables:

- Detailed logging to files in the logs directory
- Log files named with timestamps (e.g., apm-2025-05-04-18-16.log)
- Useful for troubleshooting API integrations and complex operations

When DEBUG_LOGS=false (default):
- No log files are created
- Essential messages are still output to stderr
- Improved performance for normal operation

MCP Tools

Task Management (apm_task)

Purpose: Query tasks in the project.

Actions:

- get_all: List tasks, optionally filtered by status
- get_single: View a specific task by ID
- get_next: Find the next task to work on
- filter_by_status or filter_by_priority: Targeted task lists

<details>
<summary><strong>Functional Details</strong></summary>

When the apm_task tool is called:

1. Parameter Validation:
- Validates the action parameter (required, must be one of the valid actions)
- Validates the projectRoot parameter (required, must be an absolute path)
- Validates action-specific parameters:
- For get_single: Validates the id parameter (required, non-empty string)
- For filter_by_status: Validates the status parameter (required, must be a valid status)
- For filter_by_priority: Validates the priority parameter (required, must be a valid priority)
- Validates optional parameters: file, withSubtasks, and containsText

2. Task Retrieval:
- Reads the tasks file from the specified location (defaults to apm-artifacts/artifacts.json if not provided)
- Extracts the task list from the file

3. Action Execution:
- Executes the appropriate action based on the action parameter:
- get_all: Returns all tasks, optionally filtered by status
- get_single: Returns a specific task by ID
- get_next: Returns the next task to work on based on dependencies and status
- filter_by_status: Returns tasks filtered by status
- filter_by_priority: Returns tasks filtered by priority

4. Action-Specific Processing:
- For get_all and filter_by_status:
- Filters tasks by status if specified
- Handles subtasks based on the withSubtasks parameter
- Calculates summary metrics
- For get_single:
- Parses the task ID to determine if it's a subtask
- Finds the specific task or subtask
- For get_next:
- Filters out completed tasks
- Applies priority and text filters if specified
- Checks dependency satisfaction
- Prioritizes and selects the next task
- For filter_by_priority:
- Filters tasks by priority
- Handles subtasks based on the withSubtasks parameter
- Calculates summary metrics

5. Response Formatting:
- Returns a structured JSON response containing:
- The requested task data
- Success status and message
- Contextual information about the query
- Timestamps and session information

6. Error Handling:
- Handles validation errors (missing required fields, invalid values)
- Handles file not found errors
- Handles task not found errors
- Returns standardized error responses with context information

JSON-RPC Request

{
  "method": "apm_task",
  "params": {
    "action": "get_all|get_single|get_next|filter_by_status|filter_by_priority",
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "id": "5",  // Required for get_single action
    "status": "pending|in-progress|done|deferred|cancelled",  // For get_all and filter_by_status actions
    "priority": "high|medium|low",  // For get_next and filter_by_priority actions
    "withSubtasks": true|false,
    "containsText": "optional search text"  // For get_next action
  }
}

JSON-RPC Response

For get_all and filter_by_status actions:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "pending"
        },
        "message": "Found 5 tasks with status 'pending'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_all",
              "status": "pending",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

For get_single action:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "task": {
            "id": "5",
            "title": "Implement Feature",
            "description": "Create the feature",
            "status": "pending",
            "priority": "high",
            "dependencies": ["3", "4"],
            "details": "Implementation details..."
          }
        },
        "message": "Found task: Implement Feature",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_single",
              "id": "5"
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

For get_next action:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "nextTask": {
            "id": "2",
            "title": "Next Task",
            "description": "Description",
            "status": "pending",
            "priority": "high",
            "dependencies": []
          },
          "allTasks": [
            / Array of all tasks /
          ]
        },
        "message": "Found next task: Next Task",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_next",
              "priority": "high",
              "containsText": null
            },
            "taskCount": 10,
            "readyTaskCount": 3,
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

For filter_by_priority action:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "high"
        },
        "message": "Found 5 tasks with priority 'high'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "filter_by_priority",
              "priority": "high",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

</details>

Task Creation & Modification (apm_task_modify)

Purpose: Create, update, and delete tasks and subtasks

Actions:

- create: Add a new task
- update: Update a task's details
- update_status: Change a task's status
- delete: Remove a task
- add_subtask: Add a subtask to a task
- remove_subtask: Remove a subtask from a task
- clear_subtasks: Remove all subtasks from a task
- expand: Break down a task into subtasks
- expand_all: Expand all pending tasks

Parameters:

- action: The specific action to perform
- projectRoot: Root directory of the project
- Action-specific parameters (id, status, data, etc.)

<details>
<summary><strong>Functional Details</strong></summary>

When the apm_task_modify tool is called:

1. Parameter Validation:
- Validates the action parameter (required, must be one of the valid actions)
- Validates the projectRoot parameter (required, must be an absolute path)
- Validates action-specific parameters based on the action being performed
- Validates optional parameters like file

2. Action Execution:
- Executes the appropriate action based on the action parameter:
- create: Creates a new task with the specified properties
- update: Updates an existing task with new information
- update_status: Changes the status of one or more tasks
- delete: Removes a task from the project
- add_subtask: Adds a subtask to an existing task
- remove_subtask: Removes a subtask from a task
- clear_subtasks: Removes all subtasks from one or more tasks
- expand: Breaks down a task into subtasks using AI
- expand_all: Expands all pending tasks into subtasks using AI

3. File Operations:
- Reads the tasks file from the specified location (defaults to apm-artifacts/artifacts.json if not provided)
- Updates the tasks data based on the action performed
- Writes the updated tasks data back to the file
- Generates individual task files if needed (unless skipGenerate is true)

4. AI Integration (for certain actions):
- Uses Claude AI for task expansion and updates
- Optionally uses Perplexity AI for research-backed operations
- Generates intelligent subtasks based on task context

5. Response Formatting:
- Returns a structured JSON response containing:
- Action-specific data (task, subtasks, etc.)
- Success message
- User communication guidance
- Agent instructions for next steps

6. Error Handling:
- Handles validation errors (missing required fields, invalid values)
- Handles file not found errors
- Handles task not found errors
- Handles AI service errors
- Returns standardized error responses with context information

JSON-RPC Request

{
  "method": "apm_task_modify",
  "params": {
    "action": "create|update|update_status|delete|add_subtask|remove_subtask|clear_subtasks|expand|expand_all",
    "projectRoot": "/absolute/path/to/project",
    // Action-specific parameters
    // For create action
    "title": "Task Title",
    "description": "Task Description",
    "priority": "high|medium|low",
    "dependencies": "1,2,3",
    "details": "Implementation details",
    "testStrategy": "Test strategy",
    // For update action
    "id": "1",
    "prompt": "Update information",
    "research": true|false,
    "researchOnly": true|false,
    // For update_status action
    "id": "1",
    "status": "pending|in-progress|done|deferred|cancelled",
    // For delete action
    "id": "1",
    "confirm": true|false,
    // For add_subtask action
    "id": "1",
    "title": "Subtask Title",
    "description": "Subtask Description",
    "details": "Subtask details",
    "dependencies": "1.1,1.2",
    "status": "pending|in-progress|done|deferred|cancelled",
    "taskId": "2", // Existing task ID to convert to subtask
    "skipGenerate": true|false,
    // For remove_subtask action
    "id": "1.1",
    "convert": true|false,
    "skipGenerate": true|false,
    // For clear_subtasks action
    "id": "1", // Can be comma-separated for multiple tasks
    "all": true|false, // Clear subtasks from all tasks
    // For expand action
    "id": "1",
    "num": 3, // Number of subtasks to generate
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // For expand_all action
    "num": 3,
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // Common optional parameters
    "file": "optional/path/to/artifacts.json"
  }
}

JSON-RPC Response

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          // Action-specific response data
          // For create action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For update action
          "task": {
            "id": "1",
            "title": "Updated Task Title",
            "description": "Updated Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Updated implementation details",
            "testStrategy": "Updated test strategy"
          },
          // For update_status action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "status": "done"
            }
          ],
          // For delete action
          "removedTask": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For add_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Subtask Title",
                "description": "Subtask Description",
                "status": "pending",
                "details": "Subtask details",
                "dependencies": []
              }
            ]
          },
          // For remove_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": []
          },
          // For clear_subtasks action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy"
            }
          ],
          // For expand action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Generated Subtask 1",
                "description": "Description for Generated Subtask 1",
                "status": "pending",
                "details": "Details for Generated Subtask 1",
                "dependencies": []
              },
              {
                "id": "1.2",
                "title": "Generated Subtask 2",
                "description": "Description for Generated Subtask 2",
                "status": "pending",
                "details": "Details for Generated Subtask 2",
                "dependencies": ["1.1"]
              },
              {
                "id": "1.3",
                "title": "Generated Subtask 3",
                "description": "Description for Generated Subtask 3",
                "status": "pending",
                "details": "Details for Generated Subtask 3",
                "dependencies": ["1.2"]
              }
            ]
          },
          // For expand_all action
          "expandedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy",
              "subtasks": [
                {
                  "id": "1.1",
                  "title": "Generated Subtask 1",
                  "description": "Description for Generated Subtask 1",
                  "status": "pending",
                  "details": "Details for Generated Subtask 1",
                  "dependencies": []
                },
                {
                  "id": "1.2",
                  "title": "Generated Subtask 2",
                  "description": "Description for Generated Subtask 2",
                  "status": "pending",
                  "details": "Details for Generated Subtask 2",
                  "dependencies": ["1.1"]
                },
                {
                  "id": "1.3",
                  "title": "Generated Subtask 3",
                  "description": "Description for Generated Subtask 3",
                  "status": "pending",
                  "details": "Details for Generated Subtask 3",
                  "dependencies": ["1.2"]
                }
              ]
            }
          ]
        },
        "message": "Action-specific success message",
        "userCommunication": {
          "message": "User-friendly message about the action result"
        },
        "agentInstructions": "Instructions for the AI agent on how to proceed"
      }
    }
  ]
}

</details>

Task File Generation (apm_task_generate)

Purpose: Generates individual task files in apm-artifacts/ directory based on artifacts.json.

<details>
<summary><strong>Functional Details</strong></summary>

When the apm_task_generate tool is called:

1. Parameter Validation:
- Validates the projectRoot parameter (required, must be an absolute path)
- Validates optional parameters: file and output

2. Task Retrieval:
- Reads the tasks file from the specified location (defaults to artifacts.json if not provided)
- Returns an error if the tasks file is not found or is empty

3. Directory Preparation:
- Ensures the output directory exists (creates it if necessary)
- Uses the default artifacts directory if no output directory is specified

4. File Generation Process:
- For each task in the tasks data:
- Generates a markdown file with the task details
- Includes all task properties (title, description, status, dependencies, etc.)
- Formats subtasks as nested sections if present
- Uses a consistent naming convention based on task IDs
- Creates a well-structured, readable format for each task file

5. Response Formatting:
- Returns a structured JSON response containing:
- Success status
- The number of task files generated
- The path to the artifacts directory
- The path to the tasks file
- A success message
- Context information (timestamp, task count)

6. Error Handling:
- Handles file not found errors
- Handles directory creation errors
- Handles file writing errors
- Returns standardized error responses with context information

JSON-RPC Request

{
  "method": "apm_task_generate",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "output": "optional/path/to/output/directory"
  }
}

JSON-RPC Response

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "success": true,
          "taskCount": 10,
          "artifactsDir": "/path/to/project/apm-artifacts",
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Generated 10 task files in /path/to/project/apm-artifacts",
        "context": {
          "timestamp": "2023-06-15T10:30:00Z",
          "taskCount": 10
        }
      }
    }
  ]
}

</details>

Project Brief (apm_project_brief_create)

Purpose: Create a project brief through an interactive interview process and generate tasks.

- Use apm_project_brief_status to check operation progress
- Use apm_project_brief_result to retrieve completed briefing

<details>
<summary><strong>Functional Details</strong></summary>

When the apm_project_brief_create tool is called:

1. Parameter Validation:
- Validates the projectRoot parameter (required, must be an absolute path)
- Validates optional parameters: sessionId, input, stage, response, exportFormat, and maxTasks

2. Session Handling:
- If no sessionId is provided, starts a new interview session
- If a sessionId is provided, continues an existing interview session
- Maintains state across multiple interactions

3. Interview Process:
- Guides the user through a structured interview with multiple stages:
- Project Overview: Basic information about the project's purpose and scope
- Goals and Stakeholders: Project objectives and involved parties
- Constraints: Limitations, requirements, and boundaries
- Technologies: Technical stack and tools
- Timeline and Phases: Project schedule and major milestones
- Features: Detailed functionality requirements
- Review: Final confirmation and adjustments
- Asks contextually relevant questions based on previous answers
- Processes user responses to build a comprehensive project brief

4. Task Generation:
- After completing the interview, generates tasks based on the project brief
- Creates a structured task hierarchy with proper dependencies
- Organizes tasks by phases and features
- Limits the number of tasks based on the maxTasks parameter
- Saves tasks to the artifacts.json file

5. Response Formatting:
- For new sessions: Returns an operation ID for tracking the interview process
- For continuing sessions: Returns the next question or confirmation of task generation
- Includes user communication guidance with suggested responses
- Provides clear next steps and commands

6. Error Handling:
- Handles validation errors
- Handles file not found errors
- Handles interview processing errors
- Returns standardized error responses with context information

JSON-RPC Request

…