dum-e

Named for Tony Stark's clumsy robot arm. A personal, single-user AI task manager that AI agents (Claude, Codex, opencode, any LLM) drive through a defined lifecycle, with you as the approval gate.

Three surfaces, one shared core: a powerful CLI, a REST API with live updates, and an MCP server that any agent can plug into.

The idea

Whenever you delegate work to an AI agent, it first creates a task here. The agent pulls the highest-priority task from the queue, analyzes it, works it, runs AI-level testing, then hands it to manual testing. It waits there for your approve or reject. Rejected tasks bounce back with high-priority comments the agent must address; approved tasks flow to deployment (PR review and merge) then completed. The loop repeats until you approve. Tool- and LLM-agnostic.

              agent auto-advances                    human gate
   ┌──────┐   ┌─────────────┐   ┌────────────┐   ┌────────────────┐   ┌────────────┐   ┌───────────┐
   │ todo │ → │ in_progress │ → │ ai_testing │ → │ manual_testing │ → │ deployment │ → │ completed │
   └──────┘   └─────────────┘   └────────────┘   └────────────────┘   └────────────┘   └───────────┘
                    ↑                                    │                   │
                    └────────────── reject ──────────────┴───────────────────┘
                      (priority bumped, flagged for the agent to fix first)

Every transition requires a comment, recorded in an append-only history.

Install

Requires Node.js 22+ and pnpm 9+.

git clone <repo> dum-e && cd dum-e
pnpm install
pnpm build

Then put dum-e on your PATH. The recommended way is a small launcher that pins the Node the native dependency (better-sqlite3) was built against, so the CLI works no matter which node is first on your PATH (a plain symlink to dist/index.js breaks if your default node differs from the one you built with):

mkdir -p ~/.local/bin
cat > ~/.local/bin/dum-e <<EOF
#!/bin/sh
exec "$(command -v node)" "$PWD/packages/cli/dist/index.js" "\$@"
EOF
chmod +x ~/.local/bin/dum-e

Ensure ~/.local/bin is on your PATH. Alternatively, if you have run pnpm setup (so pnpm has a global bin dir): pnpm --filter @dum-e/cli link --global.

If you rebuild against a different Node version later (e.g. after pnpm install under a new node), regenerate the launcher so it points at the matching interpreter.

Verify:

dum-e --version
dum-e --help

Quickstart

dum-e init                                   # create ~/.config/dum-e/{config.yaml,db}
dum-e project add "Web App" -k WEB           # a project
dum-e task add "Fix login" --type bug --priority high
dum-e task next -m "starting"                # claim the highest-priority queued task
dum-e task move <id> ai_testing -m "unit tests green"
dum-e task move <id> manual_testing -m "verified locally"   # now waits for you
dum-e task ls --status manual_testing        # what awaits your review
dum-e serve --open                           # REST API + web UI, opens the browser

Surfaces

CLI (dum-e ...): full task and project lifecycle from the terminal. Add --json to any command for scriptable output. See docs/CLI.md.
REST + web (dum-e serve): Hono API with Server-Sent Events for live updates, serving the React web UI (kanban board, table view, metrics, detail drawer). See docs/REST-API.md.
MCP (dum-e mcp): a Model Context Protocol server on stdio exposing task tools to any agent. See docs/AGENTS.md. Teach an agent to use dum-e by handing it skills/dum-e/SKILL.md.

All three open the same local SQLite database directly (WAL mode: concurrent readers, serialized writes), so none of them needs the others to be running.

Architecture

Modular monolith, pnpm workspaces. Every surface is a thin adapter over @dum-e/core.

Package	Responsibility
`@dum-e/core`	Domain types, storage (SQLite + FTS5), config, state machine, services, event bus
`@dum-e/server`	Hono REST API + SSE; serves the web build
`@dum-e/mcp`	MCP server (stdio): task tools for any agent
`@dum-e/cli`	commander CLI
`@dum-e/web`	Vite + React: kanban board, table view, charts, detail drawer

Runtime state lives in ~/.config/dum-e/ (config.yaml, db, attachments/), auto-created on first run. Override the location with $DUM_E_HOME. Full detail in docs/ARCHITECTURE.md.

Configuration

~/.config/dum-e/config.yaml holds the agent roster, model roster, defaults, and server host/port. Show or locate it:

dum-e config show      # effective config (YAML, or JSON with --json)
dum-e config path      # path to the file

Development

pnpm build        # build every package (tsup for libs, Vite for web)
pnpm test         # Vitest (state machine + services)
pnpm typecheck    # tsc --noEmit across the workspace
pnpm lint         # oxlint

After editing the CLI, rebuild it: pnpm --filter @dum-e/cli build. The global dum-e symlink points at the build output, so it picks up changes automatically.

License

MIT