Taskwarrior MCP
# Taskwarrior MCP
An MCP server that gives coding agents one shared [Taskwarrior](https://taskwarrior.org) ledger. It picks the project from the folder the agent is working in, gives every task a short id, and lets parallel agents claim tasks and hand them over without editing each other's work.
[](https://github.com/alessai/Taskwarrior-MCP/actions/workflows/ci.yml)
```
scope acme.api (from session folder) · 6 open · 2 claimed · 1 blocked · 1 waiting on owner · 0 stale >60d
you: no operator lane (opencode-laptop-ses_0001)
CLAIMED BY OTHERS (do not change without a handoff):
7a6f65d2 H bug Login fails when the session cookie has expired [claimed: AcmeProjects/Operator_2, 30m left]
4cc2f1bd H feature Rate-limit the CSV export endpoint [claimed: AcmeProjects/Operator_1, 30m left]
NEXT:
b63f4002 M followup Remove the v1 auth shim after the mobile release
d7edb42d L feature Add OpenAPI examples for the orders endpoints
BLOCKED:
c06a60ad M feature Switch billing webhooks to the new provider [blocked by b63f4002]
WAITING ON OWNER:
7d7eb526 M admin Rotate the staging database password [waiting on owner approval]
```
That is what an agent sees for `~/projects/AcmeProjects/api`. With the OpenCode plugin the block is in every session automatically; other clients call `task_context`.
## Why
Agents keep losing track of work that spans sessions. Built-in todo lists disappear when the session ends. A plain task tool lets the model invent project names and task ids, so the same project ends up under five spellings and updates go to ids that don't exist. When several agents run at once, two of them pick up the same task.
This server keeps one Taskwarrior ledger and removes the guesswork:
- **Project from the folder.** A session in `~/projects/AcmeProjects/api` works in project `acme.api`. Agents don't type project names, and near-misses (`acme.apii`, a path instead of a name) are refused with the closest existing project.
- **Short ids.** Every reply uses the first 8 characters of the task UUID. A string that isn't an id is refused instead of matched loosely.
- **Claims with leases.** Updating a task claims it for 30 minutes (longer on request). Another agent's change is refused with who holds it and for how long. Claim checks and writes are serialized across server processes with a lock file.
- **Lanes and handoffs.** Agents running in `<Job>/Operators/Operator_N` folders act as named lanes. A lane can hand a task to another lane; it moves only when the receiver accepts. A takeover needs a written reason, recorded on the task.
- **Small replies.** Writes return one line (`ok 7a6f65d2 done`). The context view above is about 200 tokens and stays short as the ledger grows (each section lists a few tasks and counts the rest).
- **Six tools.** `task_context`, `task_list`, `task_get`, `task_create`, `task_update`, `task_claim`.
## Requirements
- Taskwarrior 2.6 or 3.x (tested with 2.6.2 and 3.5.0)
- Node.js 20 or newer
- Linux (tested). macOS should work but is untested; Windows is not supported.
## Install
```sh
git clone https://github.com/alessai/Taskwarrior-MCP.git
cd Taskwarrior-MCP
npm install # also builds dist/
npm link # puts `taskwarrior-mcp` on your PATH
```
The server uses your normal Taskwarrior configuration (`~/.taskrc`, `TASKRC`, `TASKDATA`). It declares the extra fields it needs on every call, so your `.taskrc` doesn't need changes.
## Connect a client
### OpenCode
`~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"servers": {
"taskwarrior": {
"type": "local",
"command": ["taskwarrior-mcp"],
"cwd": "/home/you",
"pool": true,
"codemode": false
}
}
}
}
```
`pool: true` runs one server process for all sessions; give it a fixed `cwd` (your home folder). `codemode: false` keeps the tools visible instead of behind a search step. Then install the plugin, which tells the server each session's folder and injects the context block:
```sh
cp integrations/opencode/taskwarrior-context.js ~/.config/opencode/plugins/
```
### Claude Code
```sh
claude mcp add taskwarrior -- taskwarrior-mcp
```
Claude Code tells the server the project folder (`CLAUDE_PROJECT_DIR`), and calls that don't name a folder use it. Add "Call task_context at the start of a session" to your `CLAUDE.md`.
### Other clients
```json
{ "mcpServers": { "taskwarrior": { "command": "taskwarrior-mcp" } } }
```
Calls without a folder use the folder the client started the server in. If the client runs one server for several projects, the agent has to pass `cwd` (the working folder) in each call.
## How the project is chosen
The server expects work to live in `<root>/<Job>/<repo>/…`:
```
~/projects/ a root
AcmeProjects/ job "acme" (lowercased, a trailing "Projects" is dropped)
api/ project "acme.api"
web/ project "acme.web"
Operators/Operator_1/ lane "AcmeProjects/Operator_1" in job "acme"
```
Roots default to `projects`, `Projects`, `Work`, `work`, `code` and `src` under any home folder. Set `TASKWARRIOR_MCP_ROOTS` to change them.
Each task records the folder it was created in (`repo_path`). Once a folder has at least 3 tasks and 60% of them are in one project, that project wins over the folder name. Renamed or oddly named folders still land in the right project.
The root of a job (`~/projects/AcmeProjects`) shows the whole job. A folder outside every root gives no scope, and the tools ask for `job`/`repo`.
## Tools
| Tool | What it does |
| --- | --- |
| `task_context` | Start here: your claims, handoffs for you, tasks other lanes hold, NEXT, blocked, waiting on owner. `all_projects: true` gives counts per project. |
| `task_list` | Filter by status, plain-text search (description, context, notes), tags, priority, kind, stale, claimed, waiting on owner. |
| `task_get` | One task in full: claim, handoff, context, dependencies, last 5 notes. |
| `task_create` | New task in the folder's project. Returns the existing open task instead of a duplicate. `claim: true` claims it. |
| `task_update` | Fields, a note, or a status (`done`, `deleted` with a reason, `pending` with a reason to reopen). Claims the task for you and renews your claim; a rejected change leaves no claim behind. |
| `task_claim` | `claim`, `release`, `handoff` (to a lane, with a note), `accept`, `takeover` (with a reason). |
Fields agents can set: `priority` (H/M/L), `kind` (bug, feature, research, followup, decision, admin, test, release), `tags`, `due`, `scheduled`, `wait`, `depends` (short ids; on update it replaces the list), `context_summary`, `waiting_on` (who must act; keeps the task out of NEXT), `gate` (0–8) and `risk` (A–E) for teams that track review gates.
Tasks with no activity for 60 days stay open but leave NEXT. `task_list stale: true` shows them.
## Several agents at once
- Claims are per session. With OpenCode the session id comes from the request; other clients get one identity per server process.
- Lanes: a session in `AcmeProjects/Operators/Operator_2` acts as `AcmeProjects/Operator_2`, so a replacement session in the same folder continues that lane's claims. Run one session per lane folder.
- A handoff target must be an existing lane folder. The giver keeps the claim (extended to 4 hours) until the receiver accepts. If the giver's claim lapses and a third lane takes the task, the accept is refused.
- Writes to a task another lane has claimed are refused, notes included. Coordinate with that lane or hand off.
## One ledger, several machines
Run the ledger on one machine. On the others, point the MCP client at the ssh relay, which reconnects after network drops and sleep:
```json
"command": ["node", "/path/to/Taskwarrior-MCP/integrations/ssh-relay.mjs"],
"environment": { "TASKWARRIOR_MCP_SSH": "ledger-host" }
```
For the OpenCode plugin on those machines, set `TASKWARRIOR_MCP_SSH=ledger-host` in OpenCode's environment. The relay needs key-based ssh and `taskwarrior-mcp` installed on the ledger host. Paths from different machines match as long as the folders below the root have the same names.
## Configuration
| Variable | Default | |
| --- | --- | --- |
| `TASKWARRIOR_MCP_ROOTS` | `/home/*/projects:/home/*/Work:…` | Colon-separated roots; `*` matches one folder |
| `TASKWARRIOR_MCP_STALE_DAYS` | `60` | Idle days before a task leaves NEXT |
| `TASKWARRIOR_MCP_TASK_TIMEOUT_MS` | `30000` | Timeout for each `task` call |
| `TASKWARRIOR_MCP_HOST` | hostname | Machine label in claim owners |
| `TASKWARRIOR_MCP_AGENT_ID` | `mcp-<host>-<pid>` | Claim owner for clients that send no session id |
| `TASKWARRIOR_BACKUP_DIR` | `~/.task-backups` | Used by the backup and maintenance scripts |
## Backups and cleanup
```sh
npm run backup # export + raw data files, then restores them into a temp ledger to prove they work
npm run maintenance -- normalize # dry run: merge projects spelled several ways
npm run maintenance -- normalize --apply # applies, after writing a backup and a manifest
npm run maintenance -- stop-stale-active --apply # stop tasks left "active" by expired claims
```
Run the backup on a schedule (cron or a systemd timer) into a folder your machine backup covers.
## Limits
- Claims are leases. They stop agents that use this server; someone running `task` by hand can still change a claimed task.
- The lock file serializes every server process that uses the same Taskwarrior data folder. Taskwarrior's own sync (taskd, TaskChampion sync) is untested.
- How Taskwarrior stores backslashes differs between versions. The server handles 2.6 and 3.x and the tests check it. Run `npm test` after upgrading Taskwarrior.
## Development
```sh
npm test # build, 33 behaviour tests, then multi-session and two-process race tests
```
Tests run against temporary ledgers and never touch your own data. See [docs/reference.md](docs/reference.md) for internals.
## License
MIT
TDQS
Scored across 6 tools
Each tool targets a distinct aspect of task management: claim lifecycle, context dashboard, search/list, single-task detail, creation, and updates. The only mild overlap is between task_context (curated view) and task_list (search/filter), but descriptions clarify their different roles.
All tools use a consistent `task_` prefix and snake_case, with most following a verb_noun pattern (claim, list, get, create, update). `task_context` is a noun and slightly breaks the verb pattern, but the set remains highly predictable.
Six tools are well-scoped for a task management server with claim/handoff workflows. Each tool has a clear, non-redundant purpose, and the count is neither thin nor bloated.
The surface covers full task lifecycle (create, read, update, delete via status change) plus a sophisticated claim/handoff mechanism. Minor gaps exist, such as no explicit tool for adding/removing dependencies or managing tags, though task_update may accommodate some field changes.