Overseer

🚀 Overseer

MCPを介したAIエージェントのタスクオーケストレーション。SQLiteバックエンド、ネイティブVCS（jj - lib + gix）を使用しています。

🚀 クイックスタート

📦 インストール

npm経由

npm install -g @dmmulroy/overseer

skills.sh経由（エージェント用）

npx skills add dmmulroy/overseer

💻 使用例

MCPサーバー

MCPクライアントの設定に追加します。

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["@dmmulroy/overseer", "mcp"]
    }
  }
}

CLI

os task create -d "Implement auth"
os task list --ready
os task start <task-id>
os task complete <task-id>

✨ 主な機能

アーキテクチャ

┌─────────────────────────────────────┐
│     Overseer MCP (Node.js)          │
│  - Single "execute" tool (codemode) │
│  - VM sandbox with tasks/learnings  │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│         os CLI (Rust)               │
│  - SQLite storage                   │
│  - jj-lib (primary VCS)             │
│  - gix (git fallback)               │
└─────────────────────────────────────┘

コードモードパターン

単一のexecuteツール - エージェントがJSを書き、サーバーが実行します。

const milestone = await tasks.create({
  description: "User auth system",
  context: "JWT + refresh tokens"
});

const login = await tasks.create({
  description: "Login endpoint",
  parentId: milestone.id
});

await tasks.start(login.id);  // VCS required: creates bookmark, records start commit
// ... do work ...
await tasks.complete(login.id, {  // VCS required: commits changes, bubbles learnings to parent
  result: "Implemented with bcrypt",
  learnings: ["bcrypt rounds should be 12+ for production"]
});

return { milestone, login };

タスク階層

• マイルストーン (深さ0) - ルート、親なし
• タスク (深さ1) - 親はマイルストーン
• サブタスク (深さ2) - 最大深さ、親はタスク

📚 詳細ドキュメント

📄 APIドキュメント

tasks

tasks.create({ description, context?, parentId?, priority?, blockedBy? })
tasks.get(id)           // Returns TaskWithContext
tasks.list({ parentId?, ready?, completed?, depth?, type? })  // type: "milestone"|"task"|"subtask"
tasks.update(id, { description?, context?, priority?, parentId? })
tasks.start(id)
tasks.complete(id, { result?, learnings? })  // Learnings bubble to immediate parent
tasks.reopen(id)
tasks.delete(id)
tasks.block(taskId, blockerId)
tasks.unblock(taskId, blockerId)
tasks.nextReady(milestoneId?)
tasks.tree(rootId?)     // Returns TaskTree or TaskTree[] (all milestones if no ID)
tasks.search(query)     // Search by description/context/result
tasks.progress(rootId?) // Returns { total, completed, ready, blocked }

learnings

learnings.list(taskId)  // Learnings are added via tasks.complete()

VCS (ワークフローに必要)

VCS操作はタスクワークフローに統合されており、直接のAPIはありません。

VCS（jjまたはgit）は、開始/完了に必要です。CRUD操作はVCSなしでも動作します。

プログレッシブコンテキスト

タスクは祖先からコンテキストを継承します。学習内容は完了時に直接の親に伝播します（元のsourceTaskIdを保持）。

const subtask = await tasks.get(subtaskId);
// subtask.context.own       - このタスクのコンテキスト
// subtask.context.parent    - 親タスクのコンテキスト (深さ > 0)
// subtask.context.milestone - ルートマイルストーンのコンテキスト (深さ > 1)
// subtask.learnings.own     - このタスクの学習内容 (子タスクを完了したときに追加)

CLIリファレンス

# タスク
os task create -d "description" [--context "..."] [--parent ID] [--priority 1-5]
os task get <id>
os task list [--parent ID] [--ready] [--completed]
os task update <id> [-d "..."] [--context "..."] [--priority N] [--parent ID]
os task start <id>
os task complete <id> [--result "..."] [--learning "..."]...
os task reopen <id>
os task delete <id>
os task block <id> --by <blocker-id>
os task unblock <id> --by <blocker-id>
os task next-ready [--milestone ID]
os task tree [ID]           # IDがない場合はすべてのマイルストーンツリー
os task search "query"
os task progress [ID]       # 集計カウント: 合計、完了、準備完了、ブロックされている

# 学習内容 (タスク完了時に --learning で追加)
os learning list <task-id>

# VCS (CLIのみ - MCPでは自動)
os vcs detect
os vcs status
os vcs log [--limit N]
os vcs diff [BASE_REV]
os vcs commit -m "message"
os vcs cleanup [--delete]  # 孤立したタスクブランチをリスト/削除

# データ
os data export [-o file.json]

タスクビューアー

タスクを表示するためのWeb UIです。

# CLI経由（インストール後）
os ui

# またはリポジトリから（開発用）
cd ui && npm install && npm run dev
# http://localhost:5173 が開きます

3つのビューがあります。

• グラフ - ブロッキング関係を持つDAGビジュアライゼーション
• リスト - フィルタリング可能なタスクリスト
• カンバン - 完了ステータス別のボード

キーボード操作: g=グラフ、l=リスト、k=カンバン、?=ヘルプ

🔧 技術詳細

開発

# Rust CLI
cd overseer && cargo build --release
cd overseer && cargo test

# Node MCP
cd mcp && npm install
cd mcp && npm run build
cd mcp && npm test

# UI (開発サーバー)
cd ui && npm install && npm run dev

ストレージ

SQLiteデータベースの場所（優先順位）:

1. OVERSEER_DB_PATH環境変数（設定されている場合）
2. VCS_ROOT/.overseer/tasks.db（jj/gitリポジトリ内の場合）
3. $CWD/.overseer/tasks.db（フォールバック）

最初のコマンドで自動作成されます。

VCS検出

1. カレントディレクトリから上方向に.jj/を探し、見つかった場合はjj - libを使用します。
2. 見つからない場合は、.git/を探し、見つかった場合はgixを使用します。
3. どちらも見つからない場合は、VcsType::Noneを使用します。

jjを優先: 利用可能な場合は常にjjを優先します。

ドキュメント

• アーキテクチャ - システム設計、不変条件
• CLIリファレンス - 完全なコマンドドキュメント
• MCPガイド - エージェントの使用パターン

📄 ライセンス

MIT