agent-tasks

agent-tasks

AI コーディングエージェント向けのパイプライン駆動型タスク管理。 段階ごとのゲートを備えたパイプライン、複数エージェントの協働、Claude Code ネイティブの /pipeline ペインを提供する MCP サーバーです。タスクは設定可能なステージ（backlog、spec、plan、implement、test、review、done）を進み、依存関係の追跡、ステージゲート、成果物のバージョン管理、スレッド形式のコメントに対応します。

AI コーディングエージェント（Claude Code、Codex CLI、Gemini CLI、Aider）向けに構築されていますが、あらゆる MCP クライアントや REST の利用者でも同様に使用できます。

ユーザーマニュアルでは、実際の CLI のスクリーンショットや短い動画とともに、ペインのすべての表示と操作を紹介しています。

2.0 ではウェブダッシュボードが Claude Code 内の /pipeline ペインに置き換わりました。ブラウザー UI、WebSocket、agent-desk プラグインはなくなりました。

1.x からの変更点

• http://localhost:3422 のダッシュボードはなくなりました。Claude Code で /pipeline を実行してボードを開いてください（以下のプラグインをインストールします）。agent-desk の Tasks タブもなくなりました。
• REST：GET /api/overview と PUT /api/tasks/:id/stage は廃止されました（GET /api/board と POST /api/tasks/:id/stage を {"action": "advance"} とともに使用してください）。何も呼び出さないルートも廃止されました。詳しくはREST APIをご覧ください。
• ポート 3422 をまだ使用している 1.x プロセスは、ペイン上では An older agent-tasks (1.10.13) holds the port、ステータス行では old server 1.10.13 on the port と表示されます。引き続きそのプロセスを実行している Claude Code セッションを終了するか、古い agent-tasks プロセスを停止して、2.x プロセスがポートを使用できるようにしてから、Refresh を実行してください。

---

agent-tasks を使う理由

同じコードベースで複数の AI エージェントを動かす場合、必要なのは単なるフラットな ToDo リストではなく、共有タスクパイプラインです。ステージ、依存関係、ステージゲート、可視性が必要です。

---

機能

• パイプラインのステージ — プロジェクトごとに設定可能です：backlog > spec > plan > implement > test > review > done
• タスクの依存関係 — DAG と自動サイクル検出に対応し、解決されるまで次のステージへの進行をブロックします
• 複数エージェントによるタスクの取得 — タスクを取得、割り当て、理由を添えて前のステージに差し戻せます
• サブタスクの階層構造 — 進捗を追跡できる親子タスクツリーです
• スレッド形式のコメント — タスク上でエージェント同士が非同期で議論できます
• アーティファクトのバージョン管理 — ステージごとのドキュメント添付に対応し、自動でバージョン管理します
• 全文検索 — タスクのタイトルと説明を FTS5 で検索できます
• Claude Code の /pipeline ペイン — 会話の横にボードを表示します。キーボード操作を優先した設計で、ステージ別のタスク一覧、アーティファクトとコメントを含むタスク詳細、次のステージへの進行、差し戻し、完了、失敗、キャンセル、コメントと削除、ステータス行への表示に対応します
• 2 つのトランスポート層 — MCP（stdio）と、ペインが読み取るループバック REST API（HTTP）です
• TodoWrite ブリッジ — Claude Code に組み込まれた TodoWrite をインターセプトし、パイプラインと同期します
• ステージゲート — ステージごとのルールを設定できるプロジェクト単位のゲートです。次のステージに進む前に、指定したアーティファクト、最低限のアーティファクト数、またはコメントを必須にできます（スキーマには require_approval もありますが、承認を記録する MCP ツールや REST ルートはないため、これを設定するとそのステージから進めなくなります。無効のままにしてください）
• 決定ログ — task_artifact(type: "decision") により、「Z という理由で Y ではなく X を選んだ」という形式の構造化された決定アーティファクトを記録します
• 学びの伝播 — task_artifact(type: "learning") で知見（手法、落とし穴、決定、パターン）を記録し、タスク完了時に親タスクと兄弟タスクへ自動的に伝播します
• エージェントの親和性 — task_list(next: true) は、関連する履歴（親タスク、依存関係、プロジェクト）を持つエージェントへのタスクのルーティングを、同点時の優先基準として選好します
• ハートビートに基づくクリーンアップ — agent-comm のハートビートデータを使って、停止したエージェントのタスクを自動的に失敗扱いにします
• タスクのクリーンアップフック — セッション停止時に孤立したタスクを自動的に失敗扱いにし、セッション開始時に古いタスクをクリーンアップします
• エージェントブリッジ — タスクのイベント（取得、次のステージへの進行、コメント）を接続中のエージェントに通知します
• ナレッジブリッジ — タスク完了時に学びと決定のアーティファクトを agent-knowledge に自動送信し、埋め込みインデックス作成と自動リンクを行います

---

クイックスタート

npm からインストール

npm install -g agent-tasks

またはソースからクローン

git clone https://github.com/keshrath/agent-tasks.git
cd agent-tasks
npm install
npm run build

オプション 1：MCP サーバー（AI エージェント向け）

MCP クライアントの設定（Claude Code、Cline など）に追加します：

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

最初に起動した MCP プロセスが http://localhost:3422 で REST API も提供します。それ以外のプロセスは 5 秒ごとに再試行し、先行プロセスの終了後に引き継ぎます。

オプション 2：Claude Code プラグイン（MCP サーバー + /pipeline ペイン）

claude plugin marketplace add keshrath/agent-tasks
claude plugin install agent-tasks@agent-tasks

このプラグインは MCP サーバーを実行し、Claude Code のモッド（関数フック、Claude Code 2.1.289 以降）を追加します。/pipeline で会話の横にボードが開きます。チュートリアルで使い方を説明しています。ツールが重複して表示されないよう、~/.claude.json に手書きで追加した agent-tasks エントリがあれば削除してください。

オプション 3：スタンドアロン REST サーバー

node dist/server.js --port 3422

---

Claude Code との連携

上記のクイックスタートを参照して設定すると、Claude Code は 8 つの MCP ツールを直接使い、タスクの作成、ステージの進行、アーティファクトの追加、コメントなどを実行できます。プラグインをインストールすると、/pipeline で会話の横のペインにボードが開きます（Claude Code 2.1.289 以降）。詳しい連携手順については、セットアップガイドを参照してください。

---

MCP ツール（8）

カテゴリ	ツール
タスクの CRUD（4）	task_create、task_get（サブタスク／成果物／コメント／推移的依存関係を含む）、task_list（検索、次）、task_delete
メタデータ（1）	task_update（タイトル、説明、優先度、タグ、プロジェクト、割り当て、依存関係）
ライフサイクル（1）	task_stage（取得、割り当て、進行、差し戻し、完了、失敗、キャンセル）
成果物（1）	task_artifact（一般、決定、学習、コメント）
設定とユーティリティ（1）	task_config（パイプライン、セッション、クリーンアップ、ルール）

各ツールとエンドポイントの詳しい説明については、API リファレンス全文をご覧ください。

REST API（8 エンドポイント）

すべてのエンドポイントは JSON を返します。ループバック接続のみです。外部の Host は 403 になり、Origin ヘッダーを含むリクエストも同様です（ブラウザーからこの API を呼び出すことはできません）。また、リクエスト本文は application/json である必要があります。それ以外の処理はすべて MCP ツール経由で行います。詳しくはAPI リファレンス全文をご覧ください。

GET    /health                        Health check with version + uptime
GET    /api/tasks/:id                 One task, as task_get (?include=subtasks,comments,transitive_deps)
GET    /api/pipeline                  Pipeline stage configuration
GET    /api/board                     Open and recently closed tasks (what the pane polls)

POST   /api/tasks                     Create a task
POST   /api/tasks/:id/stage           Lifecycle action (claim, assign, advance, regress, complete, fail, cancel)
POST   /api/tasks/:id/comments        Add a comment
DELETE /api/tasks/:id                 Delete a task

---

テスト

npm test              # vitest: 472 tests across 25 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test
npm run plugin:check  # the /pipeline pane: claude plugin validate + its tests (needs the claude CLI)
npm run e2e:claude    # the pane in the real Claude Code CLI (see CONTRIBUTING.md)

---

環境変数

変数	デフォルト	説明
AGENT_TASKS_DB	~/.agent-tasks/agent-tasks.db	SQLite データベースファイルのパス
AGENT_TASKS_PORT	3422	REST API のポート（/pipeline ペインが読み取ります）
AGENT_TASKS_HOST	127.0.0.1	REST のバインドアドレス（0.0.0.0 にするとネットワークに公開されます）
AGENT_TASKS_USER	OS のユーザー	/pipeline ペインの操作ユーザー（created_by、コメント作成者、by）
AGENT_TASKS_INSTRUCTIONS	有効	0 に設定すると、レスポンスに埋め込まれた指示を無効にします
AGENT_TASKS_RETENTION_DAYS	30	クリーンアップで解決済みの承認記録を保持する日数
AGENT_TASKS_COMPLETED_RETENTION_DAYS	7	完了したタスクを削除前に保持する日数（ペインの「完了」に表示される期間）
AGENT_TASKS_FAILED_RETENTION_DAYS	7	失敗したタスクを削除前に保持する日数
AGENT_TASKS_CANCELLED_RETENTION_DAYS	1	キャンセルされたタスクを削除前に保持する日数
AGENT_TASKS_ORPHAN_TIMEOUT_MINUTES	360	担当者のいない進行中のタスクがキャンセルされるまでの分数
AGENT_TASKS_COMM_TIMEOUT_MS	5000	クリーンアップのエージェント通信リクエストのタイムアウト
AGENT_TASKS_DEAD_SESSION_GRACE_MINUTES	60	task-cleanup-start.js：停止したセッションのタスクを失敗にするまでのアイドル分数
AGENT_TASKS_HEARTBEAT_FRESH_MINUTES	15	task-cleanup-start.js：この時間内にハートビートがあれば、エージェントを稼働中とみなします
AGENT_COMM_URL	http://localhost:3421	ブリッジ通知用の agent-comm REST URL
AGENT_KNOWLEDGE_URL	http://localhost:3423	ナレッジブリッジ用の agent-knowledge REST URL

---

依存関係

必須：Node.js >= 20.11、better-sqlite3（同梱）

オプション（ソフト依存関係 — フェイルオープン、HTTP のみ、npm 依存関係なし）：

• agent-comm — ハートビートに基づくタスクのクリーンアップとイベント通知を行います。agent-comm がハートビートを追跡し、agent-tasks がハートビートを確認して、停止したエージェントのタスクを自動的に失敗にします。また、タスクの担当開始時や進行時にダイレクトメッセージを送り、コメント時にチャンネルへ投稿します。agent-comm がない場合、古いエージェントの検出と通知は問題なくスキップされます。

• agent-knowledge — タスクから得られた学びや決定を永続化します。タスクの完了時、KnowledgeBridge は learning と decision のアーティファクトを POST /api/knowledge 経由で agent-knowledge に送信します。エントリは埋め込み表現で自動的にインデックス化され、類似エントリと自動的にリンクされ、Git と同期されます。agent-knowledge がない場合、アーティファクトは agent-tasks 内にのみ保持されます。

---

ドキュメント

• チュートリアル — /pipeline ペインを、実際の CLI を記録しながら順を追って説明します
• ユーザーマニュアル — /pipeline ペインの各画面（スクリーンショットと GIF）、すべてのツール、パイプライン、ゲート、クリーンアップについて説明します
• API リファレンス — 8 つの MCP ツールと REST エンドポイントすべてを説明します
• フック — scripts/setup.js がインストールする Claude Code のコマンドフック
• アーキテクチャ — ソース構成、設計原則、データベーススキーマ
• セットアップガイド — インストール、クライアントのセットアップ（Claude Code、OpenCode、Cursor、Windsurf）、フック
• コントリビューション — 開発、テスト、実際の CLI での E2E 実行
• 変更履歴

---

ライセンス

MIT — LICENSE を参照