taskdeck
A task runner built for working with coding agents. Like a Makefile or justfile, each repo
gets one file, taskdeck.yaml, listing the commands people run in it. You run them from
the CLI or a local UI, and your agent runs them over MCP.
Every repo grows commands you forget: pnpm run deploy worker --skip-build,
.\launch-two.ps1 -Count 3 -Manual, "edit tfvars, then apply, then deploy". make and just
gave those commands a name. taskdeck also tells you, and your agent, how to run each one
and how risky it is:
- Typed params. Every action is a form in the UI and a schema for agents, so nobody guesses flags.
- Risk levels. Your agent runs the safe actions itself. A deploy or a delete becomes a proposal with a Run button for you, not a command in chat that you forget by tomorrow.
- Nothing to rewrite. Actions call what you already have: npm scripts, PowerShell, make, or your own CLI.
- Somewhere to watch them. Each repo gets real terminals, run history and multi-step workflows shown as checklists, all kept by one small local daemon.
Get started
Add taskdeck to your agent once:
npx taskdeck init --claude
init adds taskdeck's MCP server to the client you name, using the right command for your
OS:
--claudefor Claude Code--copilot(or--vscode) for GitHub Copilot in VS Code--cursorfor Cursor--windsurffor Windsurf
Name several clients, or pass --all for every one installed. With no flags, init asks
about each client it finds. --dry-run shows what it would change. For any other MCP client, add the
server yourself: "command": "npx", "args": ["-y", "taskdeck@latest", "mcp"] (on Windows,
"command": "cmd", "args": ["/c", "npx", "-y", "taskdeck@latest", "mcp"]).
Then open a new chat in any repo (chats that are already open don't load new MCP servers) and say:
set up taskdeck
In Claude Code, /mcp__taskdeck__setup does the same. The agent finds the repo's commands,
reads its docs, writes taskdeck.yaml and checks it. If your agent has no MCP, ask it to
read AGENT_SETUP.md and do what it says.
After that, the agent checks taskdeck before it tells you to run anything. It runs what the
contract allows (agent: run) and proposes the rest. If no taskdeck window is open, one
opens on the proposal (set TASKDECK_POPUP=0 in the daemon's environment to turn that off).
An open window brings the proposal up for review, and runs the agent starts show up in its
terminal dock.
The UI
npx taskdeck ui
This command starts the daemon if it isn't running and adds the current repo. It opens in
its own window (Chrome, Edge or Brave app mode); --browser opens a normal tab instead.
- Run actions. Fill in the form and the exact command updates as you type. Press Run to watch it in a real terminal, with colors, progress bars and prompts you can type into. "Open in my terminal" sends it to your own terminal instead.
- Keep going after you close the tab. Runs carry on in the daemon. High-risk actions ask you to confirm first.
- Review proposals. Proposals from your agent wait under "Waiting for you" until you run or dismiss them.
- Switch between repos. Each repo keeps its own terminal tabs, and the left bar marks the ones with something running. Add repos with Browse, and pick one of 14 themes from the gear icon.
Real terminals come from the optional node-pty dependency, prebuilt for Windows and macOS.
On Linux it needs build tools; without it, output is piped instead.
The CLI
npx taskdeck list
npx taskdeck show deploy
npx taskdeck run deploy target=worker skipBuild --dry-run
npx taskdeck check
check validates the contract and lists commands in the repo that the contract doesn't
cover yet.
Scripts can add and remove repos, e.g. when creating and deleting worktrees. The contract can
live outside the repo; action cwds resolve from the repo root you pass:
npx taskdeck add ../feat-login --contract ../feat-login.taskdeck.yaml
npx taskdeck remove ../feat-login
remove only takes the repo out of the UI and leaves its files alone. Agents have the same
pair of commands over MCP.
The daemon
The daemon is one Node process that uses about 60 MB and no CPU while nothing runs. It
doesn't start at login: the UI, the CLI or the MCP server starts it when one of them needs it.
When a newer taskdeck connects (@latest picks up releases), it restarts the daemon on the
new version once no runs are going, and open UI windows reload themselves.
npx taskdeck status
npx taskdeck stop
stop refuses while runs are still going; --force stops them too. Your repo list and run
history stay in ~/.taskdeck either way.
Uninstall
npx taskdeck uninstall
This command takes taskdeck out of every client that has it and stops the daemon. It
refuses while runs are going; --force stops them too. Your repo list and run history stay
in ~/.taskdeck unless you add --purge. It never touches the taskdeck.yaml files in
your repos. If you also installed taskdeck globally, run npm rm -g taskdeck.
To take taskdeck out of one client and leave the rest running, name it:
npx taskdeck uninstall --copilot.
Status
Early, but in daily use. Today taskdeck has the contract format (CONTRACT.md), discovery helpers for npm-family scripts and PowerShell, the CLI, the local UI and the MCP server. See examples/ for real contracts and ROADMAP.md for what might come next.
State lives in ~/.taskdeck: repos, run logs and proposals (TASKDECK_HOME moves it). The
daemon only listens on 127.0.0.1, and every API call needs the key in ~/.taskdeck, so web
pages you visit can't drive it.
License
Public domain (Unlicense). Do whatever you like with it.
