Agent Tasks

What agent-tasks does

agent-tasks provides pipeline task management for AI coding agents through MCP. Tasks move through an ordered lifecycle that can include backlog, spec, plan, implement, test, review, and done; projects can configure their own stages and gate rules. The system tracks task metadata, assignments, priorities, tags, projects, dependencies, parent-child relationships, artifacts, and comments.

Dependency relationships form a directed acyclic graph with cycle detection. A task cannot advance while required dependencies remain unresolved. Subtasks provide hierarchical work breakdown and progress tracking. Artifacts can hold general documents, structured decisions, learning records, or comments. Learning artifacts can propagate to parent and sibling tasks when the task completes.

How it works

Configure an agent session before using agent-specific operations. Agents can create or find work, inspect dependency closures, claim the highest-priority eligible task, and update task metadata. The task_list tool supports filters for status, stage, project, and assignee, full-text searches over titles and descriptions, and a next mode that selects an unassigned task whose dependencies are met. Agent history can influence tie-breaking in that selection.

Lifecycle changes go through task_stage. Claiming assigns the task and normally moves it from backlog to spec; assigning alone leaves the stage unchanged. Other actions advance, jump, regress with a reason, complete with a result, fail with an error, or cancel with a reason. Stage gates can require named artifacts, minimum artifact counts, or comments before advancement.

The package exposes MCP over stdio and also starts a loopback REST API from the first MCP process on port 3422. Additional MCP processes retry and take over if the active process exits. The REST API supports health checks, task retrieval and creation, board and pipeline queries, lifecycle actions, comments, and deletion.

Setup and configuration

Install the package globally with npm:

npm install -g agent-tasks

An MCP client can launch it with a stdio entry such as:

{
  "mcpServers": {
    "agent-tasks": {
      "command": "npx",
      "args": ["agent-tasks"]
    }
  }
}

Node.js 20.11 or newer is required. The database location can be configured with AGENT_TASKS_DB. For a standalone REST process, run node dist/server.js --port 3422.

Claude Code users can install the companion plugin from the keshrath/agent-tasks marketplace. It adds the /pipeline pane beside the conversation and requires Claude Code 2.1.289 or newer. Remove a duplicate hand-written MCP configuration when using the plugin.

Tools and capabilities

• task_create, task_get, task_list, and task_delete manage task records, searches, subtasks, dependency views, and cascading removal.
• task_update changes titles, descriptions, priorities, tags, projects, assignments, and dependencies.
• task_stage handles claiming, assignment, progression, regression, completion, failure, and cancellation.
• task_artifact stores documents, decision records, learning entries, and threaded comments.
• task_config manages agent sessions, project pipelines and gates, cleanup, and IDE rule-file generation.
• The Claude Code pane presents tasks by stage and supports task actions, comments, and deletion.

Limitations and notes

Deletion cascades to a task's artifacts, comments, and dependencies and cannot be undone. The REST service is loopback-only: requests with a foreign Host or any Origin header are rejected, and request bodies must use JSON. The current interface is the Claude Code pane rather than a browser dashboard. Stage gates using require_approval cannot be satisfied through the available MCP or REST operations, so that setting should remain disabled.