agent-task

Task tracking for coding agents: the tasks running in parallel, the ones handed back for review and the ones waiting to run, each with its repo and the brief it started from

agent-task records each coding-agent task on this machine, with the repository its work lands in, from the time it is queued or started until its work is over.

• agent-task add <name> queues a task with its goal, plan, priority, what it waits for and the check that says its wait is met, and list prints the queue in the order to start it.
• agent-task start <name> runs a task from a brief, recording the brief's path and git blob sha and the session that started it; review marks it handed back for review, and list flags a brief that changed since.
• start refuses while the machine is too busy for another task: while the load per CPU core is above 0.7 or less than 15% of memory is available, limits the owner can change per machine in ~/.local/share/agent-task/limits.json.
• agent-task done <name> removes a task however its work ended; whether the work landed is git's to show.
• agent-task project add <id> adds a project, which a task can belong to, and list --project <id> shows that project's tasks alone.
• agent-task halt "<reason>" stops all agent work on this machine until the owner runs agent-task resume, and the plugin enforces it in every session.
• The cniska-task Claude Code plugin tells every session that queued and running work lives in agent-task. Where the working directory holds a running or in-review task's brief, it adds every running and in-review task, each with whether its brief changed.

Install

Install the agent-task command for macOS on Apple silicon or Linux on x64 through one of these channels.

With the release's installer:

curl -fsSL https://github.com/cniska/agent-task/releases/latest/download/install.sh | sh

With Homebrew:

brew install cniska/tap/agent-task

With npm:

npm install -g @cniska/agent-task

With Bun:

bun add -g @cniska/agent-task

The curl line installs ~/.local/bin/agent-task and, when that directory is not on your PATH, adds it to ~/.zshrc for zsh or to an existing ~/.bashrc or ~/.bash_profile for bash, and otherwise asks you to add it. Each channel updates the way it installed: brew upgrade agent-task, npm update -g @cniska/agent-task, bun update -g @cniska/agent-task, or the curl line run again.

Then install the Claude Code plugin:

claude plugin install cniska-task@cniska

Updates

When a newer release is out on its channel, every agent-task command prints one line on stderr naming that channel's upgrade. Set AGENT_TASK_NO_UPDATE_CHECK=1 to turn the check off; it is also off while CI is set and not blank. The update check shows the line and has the details.

Why

Agents running in parallel on one machine need one record of which task each is on, which work came back for review and what waits to start next. A brief edited while its task runs leaves the agent working from instructions no one can see anymore, so agent-task records the brief's sha when the task starts and list flags briefChanged once the brief no longer has it.

agent-task is the record of the work on this machine, not an issue tracker such as Linear: it keeps nothing of a task once it is removed, and it depends on git and /bin/sh alone.

Commands

Command	Does
agent-task add <name> --repo <path> --goal <text> [...]	Queue a task, or replace a queued one
agent-task start <name> --repo <path> --brief <file> [...]	Run a task, new or queued, from its brief, unless the machine is too busy
agent-task wait <name> [--after <name>]... [--waits <text>] [--until <command>]	Replace what a task waits for
agent-task map <name> --project <id>	Make a task belong to a project
agent-task priority <name> urgent|high|medium|low|none	Set or clear a task's priority
agent-task review <name>	Record that a running task was handed back for review
agent-task list [--started [--brief-under <dir>]] [--project <id>] [--full]	List the running and in-review tasks, then the queue, running each queued task's check; --started lists the started tasks alone, --project one project's tasks, --full every field
agent-task stop <name>	Take a running or in-review task back to queued
agent-task done <name>	Remove a task in any state
agent-task project add|list|remove	Add or replace a project, list the projects, or remove one no task belongs to
agent-task halt <reason>	Halt all agent work on this machine
agent-task resume	Lift the halt
agent-task halted	Say whether a halt is raised
agent-task doctor [--full]	Check what agent-task and its plugin need
agent-task	Run list
agent-task --help	List the commands and flags
agent-task --version	Print the version

Commands lists every command, its flags, its output and the store.

Docs

• Commands: every command, its flags and output, and where the store lives.
• Claude Code plugin: what the plugin's hooks do, the halt they enforce, and what they need.
• Development: setup, checks, scripts and rules, for working on this repo.
• Contributing: how outside contributors propose a change.
• Releasing: the release workflow, what a release guarantees, the owner's one-time setup and each release's steps.

Related

agent-task works on its own in any agent workflow, and is one of the optional add-ons to agent-skills, engineering skills for coding agents. The other add-ons:

• agent-record: a session record for coding agents, every past session queryable and joined to its commits
• agent-gates: commit gates for coding agents, git hooks and CI checks that refuse a bad commit
• agent-worktree: task worktrees for coding agents, one checkout per task, set up and torn down by the project's own commands