vibeflow tasks.
Every verb your agent needs.
List, claim, create, edit, comment and verify tasks — one command, no
browser. It reads and writes the same .vibeflow/
tasks the kanban board renders, so agents and humans always work from
a single board.
Overview
The task store, without a browser.
vibeflow tasks is the command line over the
task store: plain JSON files in .vibeflow/
inside your repository. Versioned in git, no account, no cloud —
the same tasks the board renders.
Hand your agent one unit of work.
--next picks the highest-priority root
task in todo, moves it to in-progress and prints it with
its children. Claiming is atomic, so parallel agents never
collide on the same task.
- Roots only — a child belongs to its parent, so it is never claimed on its own.
- Children included — the result carries each child's id, title and status.
-
Filter the claim — add
--type Bugor--tag frontend.
See exactly what is open.
List mode returns root tasks by default — matching how the
board renders them — and the footer reports how many children
the query matched, so nothing is hidden silently. Pass
--children to include them,
--json for machine-readable output.
-
Five filters —
--status,--type,--user,--tag(repeatable, AND),--limit. -
Default is 5 — use
--limit 0for everything.
Flag reference
Every flag, at a glance.
Run npx @vibeflow-tools/cli tasks --help
for the canonical list — this table mirrors it exactly.
| Flag | What it does |
|---|---|
| Filters | |
--status <status> |
Filter by status: backlog, todo, in-progress, review, done. |
--type <type> |
Filter by type: Task, Bug, Feature, Enhancement, Research. |
--user <user> |
Filter by exact task author email (case-insensitive). |
--tag <tag> |
Filter by tag — repeat the flag for AND matching. |
--limit <n> |
How many tasks to return in list mode (default 5; 0 for unlimited). |
| Listing | |
--children |
Include child tasks. By default only root tasks are listed — a child belongs to its parent, matching the board. |
--fields <fields> |
Comma-separated list of fields to include in list/get output. |
--json |
Machine-readable JSON output. |
| Reading | |
--get <task-id> |
Full details of one task: description, comments, files, linked commits. Accepts a partial id prefix. |
--next |
Claim the highest-priority root task in todo — move it to in-progress and print it ready to work on. Never returns a child. |
| Creating | |
--add |
Create a task (requires --title). |
--title <title> |
Title for --add (or a new title with --edit). |
--description <text> |
Description text for --add or --edit. |
--priority <priority> |
Critical, High, Medium or Low (with --add). |
--parent <task-id> |
Create the task as a child of an existing task (with --add; full id or prefix). |
| Editing | |
--edit [task-id] |
Edit a task by id — omit the id to print usage instructions. |
--set-status <status> |
New status: backlog | todo | in-progress | review | done. |
--set-parent <task-id> |
Set or replace the parent link (with --edit; empty string clears). |
--no-parent |
Remove the parent link (with --edit). |
--comment <text> |
Report comment — written with any status, and required when setting status to review. |
--report-file <path> |
Upload a local .md research report (Research tasks, with --set-status review). |
| Committing | |
--commit + --task <id> |
Commit staged changes and link the resulting SHA to a task (--message sets the message). |
--commit-message <msg> |
Commit message for auto-commit on review (required when auto-commit is ON). |
| Verification | |
--set-verify <verdict> |
pass (correct), fail (not correct) or cannot (unverifiable) — the agent verdict recorded on the review transition. |
--verify-reason <reason> |
Why the task cannot be verified — required with --set-verify cannot. |
| Maintenance | |
--reindex-sort-keys |
One-time re-keying of keyless or duplicate sort keys so the rendered board order survives. Honors --dry-run and --json. |
--dry-run |
Preview what a mutation would change without modifying anything. |
The model
Root tasks are the unit of work.
A task with a parent link is a child; a task without one is a root. Agents get whole units, so listing and claiming operate on roots — and the board renders children inside their parent card.
Claiming a root does not cascade to its children — the
result reports them and the agent walks them one by one.
Because --next only considers roots
whose own status is todo, move a
parked root to todo to make the whole unit claimable.
-
List — roots only by default;
--childrenincludes children. - Claim — a root in todo, never a child; its children come along with statuses.
-
Read —
--getis unfiltered and resolves any task, child or root.
Workflow
Claim → implement → review.
Statuses run backlog → todo → in-progress →
review → done. The interesting transition is into review —
that is where the report, the commit and the verification verdict
live.
Three things can be required on the way to review, depending on how your project is configured:
-
A report —
--commentis always required with--set-status review. -
A commit message — when auto-commit is ON,
--commit-messageis required and the SHA is linked to the task. -
A verdict — annotated tasks (URL + selector) need
--set-verify passorfail;cannotrequires--verify-reason. Research tasks carry no verdict.
If something looks wrong
Common questions.
An agent said there were no tasks available.
--next only picks up root tasks in todo. Run tasks --status backlog to see anything still parked, then move what is ready with tasks --edit <id> --set-status todo.
Two agents tried to claim the same task.
They cannot. Claiming with --next is atomic: the task flips to in-progress in the same write that hands it out, so the second agent receives the next available root instead. You can run as many agents in parallel as you like.
The review transition fails asking for a commit message.
This project has auto-commit turned on for review transitions, so --set-status review also requires <id> --commit-message "<summary>". Provide the message and the CLI commits the staged work and links the SHA to the task.
Can --next claim my child tasks?
No — a root is the unit of work. --next claims a root and prints its children with their ids and statuses; your agent then walks them. --get <id> is unfiltered and resolves any child by (prefix of its) id.
Related pages
Where to go next.
- How to use Vibeflow — the three-step workflow and the full command table
- vibeflow kanban — start the board, the overlay and the MCP endpoint
- vibeflow serve — serve prototypes or run the API-only task server
- vibeflow watch — stream task events to a file or webhook
- MCP setup guide — the same operations as ten MCP tools
- Give your AI agent UI context — why structured tasks beat prose bug reports
Ten seconds to your
first annotated task.
No account, no cloud, no browser extension.
Apache-2.0 · Node.js 22+ · tasks stay in your repository