Why

AI coding agents are brilliant until the next morning. Every session starts from zero: the plan is in an old chat, the TODO file is stale, and the task board was never updated.

taskwire gives your agents the task board you already use. They find the task before they start, move it along while they work, and leave a comment for whoever comes next, human or agent.

Quick start

1. Install (Node 24.7 or later):

npm install --global @richi2293/taskwire

2. Store the API token of your task system in the macOS Keychain. On Linux or CI, set TASKWIRE_API_TOKEN instead. The provider page says where to create the token.

security add-generic-password -a "$USER" -s taskwire -w
taskwire whoami

3. Let your agent set up the project. From the project root, tell it:

Set up taskwire in this project: run `taskwire setup` and follow it.

It asks you which folder, lists and language to use, connects the project and adds a short block to its AGENTS.md, so every agent runs taskwire rules first. To do it by hand instead, see docs/agent-rules.md.

Next session, ask your agent: "What was I doing yesterday?"

How it works

• Any agent. Agents run plain shell commands and read compact JSON. No server, no SDK, no plugin: if a model can run a command, it can use taskwire.
• Rules built in. taskwire rules tells agents how to handle tasks: search before starting, move the status along a default flow that adapts to each list, write comments people can skim. Projects add their own language and habits on top.
• Safe by default. Every write is checked against the project in .taskwire.json, and anything outside it is refused. Deleting needs --yes.
• Token stays secret. It lives in the Keychain (or an environment variable) and is never printed.
• Zero dependencies. One small CLI on Node, nothing else to install or trust.

Commands

| Area | Commands | |---|---| | Setup | setup, whoami, folders, init, rules, conventions, project, area set | | Groups and areas | group, group init, area add, area remove, areas | | Tasks | tasks, task get, task create, task update, task delete --yes | | Lists and tags | lists, list create, tags | | Comments | comment add, comment update | | Checklists | checklist add, check, add-item, rename-item, remove-item --yes | | Dependencies | dependency add, dependency remove |

Run taskwire --help for every option. A few things worth knowing:

• Output is compact JSON on stdout; errors and warnings are JSON lines on stderr. Add --pretty for a human view.
• Search (taskwire tasks --search <words>) matches every word in the name or description, ignoring case and accents.
• Due dates (--due YYYY-MM-DD) are midnight in your system time zone. Set TZ to use another one.
• Descriptions and comments are markdown.
• Waiting for a person: taskwire task update <id> --needs decision|test|review marks why a task waits for you, with a tag (needs-decision, needs-test, needs-review). taskwire tasks --needs any lists those tasks, and every task shows it in its needs field. You clear it (--needs none, or remove the tag) as the go-ahead.
• Shared task lists: when several projects (for example the backend, the frontend and the app of one product) share one task list, each project sets its area, a tag such as be, fe or mobile. taskwire tasks then shows only the tasks of that area (--area <tag> for others, --all-areas for every task) and taskwire task create adds the tag (--area none for a task with no area). Set it with taskwire area set <tag>, or init --area.
• Groups: the projects that share a task list form a group, recorded on your machine (see Groups of projects). The group knows where the code of each area is, and has areas without code too, such as infra or feedback.
• Exit codes: 0 success, 1 provider or network error, 2 wrong usage, 3 configuration problem.

Configuration

Each project has a .taskwire.json at its root, written by taskwire init (--language and --instructions set the conventions). Commit it: it holds only ids, useless without the token. In a public repository you may prefer to keep it local, in .git/info/exclude.

{
  "provider": "clickup",
  "account": "acme",
  "workspaceId": "9012345",
  "folderId": "901234567",
  "listIds": ["901234890"],
  "defaultListId": "901234890",
  "area": "be",
  "needsTags": { "test": "to-test" },
  "conventions": {
    "language": "English",
    "instructions": "Task names in the imperative, under 80 characters.",
    "rulesFile": "docs/task-rules.md"
  }
}

| Field | Meaning | |---|---| | provider | the task system; defaults to clickup | | account | a name for the account of the task system this project uses, when you have more than one; its token is read from the Keychain service taskwire:<account> or from TASKWIRE_API_TOKEN_<ACCOUNT>. Leave it out to use the default token | | workspaceId, folderId, listIds, defaultListId | where the project lives in the task system, and its default list. listIds lets several projects share one container, each limited to its own lists. The exact fields depend on the provider: see its page. | | area | the tag of this project's tasks when several projects share one task list, for example be, fe or mobile. Leave it out to see every task | | needsTags | other tag names for the needs kinds (decision, test, review), for example in the project language; the others keep their default name | | conventions.language | language of task names, descriptions, comments and checklists (default English) | | conventions.instructions | any other rule for agents, added on top of the defaults and winning when they conflict | | conventions.rulesFile | a markdown file, relative to .taskwire.json, that replaces the default rules entirely |

taskwire init --force rewrites the ids and keeps the conventions, the account and the area. taskwire project prints the configuration as JSON, for tools that work on several projects.

Several accounts. Give each account a name, store its token under that name, and set it in the project with taskwire init --account <name>. --account <name> also works on any command, for example taskwire folders --account acme before init. With an account, taskwire never falls back to the default token.

Environment variables: TASKWIRE_API_TOKEN (the token, when the Keychain is not available), TASKWIRE_API_TOKEN_<ACCOUNT> (the token of a named account, uppercase with - as _), TASKWIRE_NO_UPDATE_CHECK=1 (turns off the update check), TASKWIRE_HOME (the folder of the groups file), TZ (time zone for due dates).

Updating

npm install --global @richi2293/taskwire@latest

taskwire rules checks npm for a newer version at most once a day and reports it in its update field, so your agent can tell you.

Groups of projects

A group records, on your machine, the projects that share one task list and the areas of that list. Each area has a description and, when it has code, the folder of its repository. Areas without code (servers, marketing, customer feedback) have no folder. Agents keep the group up to date themselves: tell them which projects belong together and they record them.

taskwire group init acme --description "API and database"     # from the backend, whose area is "backend"
taskwire area add frontend --path ../acme-web --description "Web app"
taskwire area add infra --description "Servers, DNS, deploy"
taskwire areas                                                # the areas, their tasks, and the tasks with no area

• Where: ~/.config/taskwire/groups.json ($XDG_CONFIG_HOME/taskwire when set, or $TASKWIRE_HOME). It holds local paths, so it stays out of the repositories and out of the task system.
• Which group: a project belongs to the group that has its folder as the path of an area. Its area in .taskwire.json must be that area: taskwire area set renames it in both places.
• Area names: taskwire area add refuses a name close to an existing area (infrastructure when infra exists), so that one kind of work keeps one tag; --force adds it anyway.
• In a group: --area accepts only the areas of the group, taskwire tasks --no-area lists the tasks with none of them, taskwire tags marks the areas with "area": true, and taskwire rules lists the areas with their folders, so that an agent knows where the code of each one is.
• Without a group taskwire works as before, with the area of the project only.

Providers

| Provider | Status | Docs | |---|---|---| | ClickUp | supported | docs/providers/clickup.md |

Want another one? Open an issue and say which.

Roadmap

Ideas, not promises:

• More task systems, driven by what people ask for.
• An MCP server as a second way in, next to the CLI.
• Orchestration: agents that work on the backlog of several projects on their own, and leave you only decisions, reviews and manual checks. An experimental first piece lives in orchestrator/.

Development

Run the CLI from a clone with ./bin/taskwire: it executes the TypeScript sources directly, with no build step. Run the tests with node --test. AGENTS.md has the rules for contributors, human or AI, and docs/releasing.md explains releases.

License

MIT. The images use the JetBrains Mono font, under the SIL Open Font License.