agent-tasks

agent-tasksは、プロジェクト内で作業するAIエージェント向けのローカルタスク管理CLIです。サーバーや外部サービスを必要とせず、タスクの作成、検索、claim、状態遷移を機械処理しやすいインターフェースで提供します。

インストール

Node.js 24以降で利用する。

npm install --global @haiix/agent-tasks
taskctl --version
taskctl --help

インストール後は、対象プロジェクトでデータベースを初期化する。

taskctl init
taskctl skill install

taskctl skill installは、初期化済みprojectをカレントディレクトリから探索し、同梱のAgent Skillを<project>/.agents/skills/agent-tasks/へ配置する。同じ内容が既にある場合は変更せず成功し、利用者による編集や追加ファイルがある場合は上書きしない。別のprojectを指定する場合は--project <path>を使用する。

開発

Node.js 24を使用する。

npm install
npm run check

npm run checkは型検査、lint、書式検査、テスト、ビルドを実行する。書式を修正する場合はnpm run formatを使用する。

npm run dev -- <command>でTypeScriptソースを直接実行できる。ビルドすると、実行時npm依存のない単一ESMファイルdist/taskctl.mjsが生成される。

カレントディレクトリの.agent-tasks/tasks.sqliteを初期化するには、次を実行する。

npm run dev -- init
npm run dev -- skill install

保存先は--db <path>または環境変数AGENT_TASKS_DBでも指定でき、--dbが優先される。

タスクを作成し、取得・一覧・更新する例を次に示す。コマンドの成功・失敗は公開JSON仕様に従ってstdoutへ出力される。

npm run dev -- create --input-json '{"title":"Implement parser","priority":"high"}'
npm run dev -- get --id <task-id>
npm run dev -- list --status pending --limit 20
npm run dev -- update --id <task-id> --expected-version 1 --input-json '{"labels":["cli"]}'
npm run dev -- dependency-add --id <task-id> --depends-on <dependency-id> --expected-version 2
npm run dev -- list --runnable
npm run dev -- claim --id <task-id> --agent <agent-id> --expected-version 3
npm run dev -- transition --id <task-id> --to done --agent <agent-id> --expected-version 4 --input-json '{"result":"Implemented and tested"}'
npm run dev -- history --id <task-id>
npm run dev -- export

シェルの引用やコマンドライン長の影響を避ける場合は、--input-json -を指定して標準入力からJSONを渡す。

get、list、historyでは、対話的な確認用に--format textも指定できる。exportは確認・バックアップ用のスナップショットであり、編集して正本として扱うための形式ではない。

目的

• Node.js CLIとしてローカルで動作する
• 対象プロジェクト内にタスクデータを保存する
• 複数のローカルAIエージェントから安全に利用できる
• プログラムから扱いやすい安定したJSON入出力を提供する
• タスクの状態遷移と担当変更を履歴として記録する
• 実行時npm依存のない単一ESMファイルtaskctl.mjsとして配布する

ドキュメント

プロジェクトの仕様と設計判断はdocuments/で管理します。

• アーキテクチャと保存方式
• SQLiteスキーマとマイグレーション
• CLI仕様
• AIエージェント向けCLI利用プロンプト
• タスクモデルとライフサイクル
• 開発環境と配布方式
• npm公開手順

ライセンス

LICENSEを参照してください。