Overseer

Developer tools Version control .TypeScript

rating : 3.5 points

downloads : 5.8K

update time : 2026-03-12

Open Site

Installation

Copy the following command to your Client for configuration

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

Note: Your key is sensitive information, do not share it with anyone.

🚀 Overseer

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

🚀 Quick Start

Get started with Overseer by installing it using one of the following methods:

📦 Installation

Via npm

npm install -g @dmmulroy/overseer

Via skills.sh (for agents)

npx skills add dmmulroy/overseer

💻 Usage Examples

MCP Server

Add the following 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>

🔧 Technical Details

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)

📚 Documentation

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