# agent-tasks [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/keshrath/agent-tasks  
**GitHub Stars:** 22  
**npm Downloads (last month):** 833  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-tasks

## Description
Pipeline task management for AI agents - stages, dependencies, artifacts, claiming

## Tools
Capabilities this server exposes over MCP:

- **task_create** — Create a pipeline task. Tasks start in "backlog" and move through stages: backlog → spec → plan → implement → test → review → done. Use parent_id to create subtasks under an existing task.
- **task_get** — Get a single task by ID. By default returns task with artifact count, comment count, dependencies, and collaborators. Use "include" to inline full subtasks, artifacts (filterable by stage), comments (with limit), or transitive_deps (full upstream + downstream closure of the dependency graph in one call — answers questions like "what depends on this task transitively?" and "what is its critical path depth?" without forcing the caller to BFS the graph).
- **task_list** — List, search, or pick tasks. Without params: returns all tasks. With filters: narrow by status/stage/project/assignee. With "query": full-text search across titles and descriptions. With "next": true: returns the single highest-priority unassigned task with all dependencies met (uses affinity scoring when agent is provided).
- **task_update** — Update task metadata — title, description, priority, tags, project, assignment, or dependencies. Does not change stage or status (use task_stage for that).
- **task_delete** — Delete a task and all its artifacts, comments, and dependencies (cascading delete). Cannot be undone.
- **task_stage** — Move a task through its lifecycle. Actions: "claim" → assign to you and advance from backlog to spec, "assign" → assign to you WITHOUT advancing the stage (use for custom pipelines where the first stage is itself a do-work stage), "advance" → next stage (or jump to a specific one), "regress" → earlier stage (requires reason), "complete" → marks done with result, "fail" → marks failed with error, "cancel" → cancels with reason.
- **task_artifact** — Attach artifacts or comments to a task. Types: "general" → document (spec, test-results, review-notes), "decision" → structured decision record (chose/over/because), "learning" → insight that auto-propagates to parent and sibling tasks on completion, "comment" → discussion comment (supports threading via parent_comment_id, satisfies stage-gate require_comment checks).
- **task_config** — Configuration and admin. Actions: "session" → set agent identity (call this first), "pipeline" → get/set pipeline stages and gate config for a project, "cleanup" → purge old completed tasks, "rules" → generate IDE rule files (.mdc or CLAUDE.md).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-tasks": {
    "command": "npx",
    "args": ["agent-tasks"],
    "env": {
      "AGENT_TASKS_DB": ""
    }
  }
}
```

**Requires environment variables:** `AGENT_TASKS_DB` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
npm install -g agent-tasks
```

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

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/agent-tasks/readme_