remotion-best-practices

Via npm

```bash

npm install -g @dmmulroy/overseer

```

Via skills.sh (for agents)

```bash

npx skills add dmmulroy/overseer

```

MCP Server

Add to your MCP client config:

```json

{

"mcpServers": {

"overseer": {

"command": "npx",

"args": ["@dmmulroy/overseer", "mcp"]

}

}

}

```

CLI

```bash

os task create -d "Implement auth"

os task list --ready

os task start

os task complete

```

```

┌─────────────────────────────────────┐

│ 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:

```javascript

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

```javascript

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

```javascript

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/, 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):

```javascript

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)

```

```bash

# Tasks

os task create -d "description" [--context "..."] [--parent ID] [--priority 1-5]

os task get

os task list [--parent ID] [--ready] [--completed]

os task update [-d "..."] [--context "..."] [--priority N] [--parent ID]

os task start

os task complete [--result "..."] [--learning "..."]...

os task reopen

os task delete

os task block --by

os task unblock --by

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

# 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:

```bash

# 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

```bash

# 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

```

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.

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.

• [Architecture](docs/ARCHITECTURE.md) - System design, invariants
• [CLI Reference](docs/CLI.md) - Full command documentation
• [MCP Guide](docs/MCP.md) - Agent usage patterns

MIT