⚠️ Archived: This project is no longer actively maintained. I've moved on to other tools and workflows. Feel free to fork and use this project as you see fit!

Overseer

Task orchestration for AI agents via MCP. SQLite-backed, native VCS (jj-lib + gix).

Install

Via npm

npm install -g @dmmulroy/overseer

Via skills.sh (for agents)

npx skills add dmmulroy/overseer

Usage

MCP Server

Add to your MCP client config:

{
  "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>

Architecture

┌─────────────────────────────────────┐
│     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)               │
└─────────────────────────────────────┘

Codemode Pattern

Single execute tool - agents write JS, server runs it:

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 };

Task Hierarchy

• Milestone (depth 0) - Root, no parent
• Task (depth 1) - Parent is milestone
• Subtask (depth 2) - Max depth, parent is task

APIs

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 (Required for Workflow)

VCS operations are integrated into task workflow - no direct API:

Operation	VCS Effect
tasks.start(id)	VCS required - creates bookmark task/<id>, records start commit
tasks.complete(id)	VCS required - commits changes, deletes bookmark (best-effort)
tasks.complete(milestone)	Also cleans ALL descendant bookmarks (depth-1 and depth-2)
tasks.delete(id)	Best-effort bookmark cleanup (works without VCS)

VCS (jj or git) is required for start/complete. CRUD operations work without VCS.

Progressive Context

Tasks inherit context from ancestors. Learnings bubble to immediate parent on completion (preserving original sourceTaskId):

const subtask = await tasks.get(subtaskId);
// subtask.context.own       - This task's context
// subtask.context.parent    - Parent task context (depth > 0)
// subtask.context.milestone - Root milestone context (depth > 1)
// subtask.learnings.own     - This task's learnings (added when completing children)

CLI Reference

# Tasks
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]           # No ID = all milestone trees
os task search "query"
os task progress [ID]       # Aggregate counts: total, completed, ready, blocked

# Learnings (added via task complete --learning)
os learning list <task-id>

# VCS (CLI only - automatic in 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]  # List/delete orphaned task branches

# Data
os data export [-o file.json]

Task Viewer

Web UI for viewing tasks:

# Via CLI (after installing)
os ui

# Or from repo (development)
cd ui && npm install && npm run dev
# Opens http://localhost:5173

Three views:

• Graph - DAG visualization with blocking relationships
• List - Filterable task list
• Kanban - Board by completion status

Keyboard: g=graph, l=list, k=kanban, ?=help

Development

# 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 (dev server)
cd ui && npm install && npm run dev

Storage

SQLite database location (in priority order):

1. OVERSEER_DB_PATH env var (if set)
2. VCS_ROOT/.overseer/tasks.db (if in jj/git repo)
3. $CWD/.overseer/tasks.db (fallback)

Auto-created on first command.

VCS Detection

1. Walk up from cwd looking for .jj/ → use jj-lib
2. If not found, look for .git/ → use gix
3. Neither → VcsType::None

jj-first: always prefer jj when available.

Docs

• Architecture - System design, invariants
• CLI Reference - Full command documentation
• MCP Guide - Agent usage patterns

License

MIT