⚠️ 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!
Task orchestration for AI agents via MCP. SQLite-backed, native VCS (jj-lib + gix).
npm install -g @dmmulroy/overseernpx skills add dmmulroy/overseerAdd to F440 your MCP client config:
{
"mcpServers": {
"overseer": {
"command": "npx",
"args": ["@dmmulroy/overseer", "mcp"]
}
}
}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) │
└─────────────────────────────────────┘
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 };- Milestone (depth 0) - Root, no parent
- Task (depth 1) - Parent is milestone
- Subtask (depth 2) - Max depth, parent is task
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.list(taskId) // Learnings are added via tasks.complete()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.
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)# 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]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:5173Three views:
- Graph - DAG visualization with blocking relationships
- List - Filterable task list
- Kanban - Board by completion status
Keyboard: g=graph, l=list, k=kanban, ?=help
# 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 devSQLite database location (in priority order):
OVERSEER_DB_PATHenv var (if set)VCS_ROOT/.overseer/tasks.db(if in jj/git repo)$CWD/.overseer/tasks.db(fallback)
Auto-created on first command.
- Walk up from cwd looking for
.jj/→ use jj-lib - If not found, look for
.git/→ use gix - Neither → VcsType::None
jj-first: always prefer jj when available.
- Architecture - System design, invariants
- CLI Reference - Full command documentation
- MCP Guide - Agent usage patterns
MIT