zorcec/vibeflow

> **Task management for AI coding agents — with annotation and verification built in.**
Vibeflow gives your coding agent sequenced, claimable work: tasks with hierarchy, an atomic --next claim, and a review gate with verification verdicts — on a local-first kanban board that stays in your repo. Clicking a UI element to file a ticket with its exact selector, URL, and source location is built in, so visual feedback arrives as structured tasks instead of prose.
---
Why It Matters
AI agents write code fast, but **understanding what to change is slow**. Describing a UI issue in prose wastes tokens and produces wrong fixes.
Vibeflow turns visual feedback into structured tasks:
- **Click any element** → instant task with CSS selector, URL, and source file location
- **Track on a Kanban board** → see everything at a glance, drag between columns
- **Agents implement with context** → no guessing, no wrong elements, no wasted iterations
Perfect for small UI fixes, broken layouts, spacing issues, and anything where pointing is faster than explaining.
---
Quick Start
---
Commands
| Command | Description |
| --------- | ------------- |
| vibeflow kanban [dir] | Start the server and open the live Kanban board in your browser |
| vibeflow serve [target] | Serve HTML files with live annotation overlay, or run API-only task server for existing apps |
| vibeflow tasks | List, filter, create, edit, and comment on tasks |
| vibeflow watch [dir] | Watch the task store and print ticket details for important updates |
| vibeflow telemetry | Manage CLI usage telemetry (opt-out at any time) |
vibeflow kanban [dir]
The Kanban board provides a visual task tracker with drag-and-drop columns, agent status display, and file attachments. Create tasks directly on the board or import them from annotated prototypes.
vibeflow serve [target]
Serve HTML prototypes with the annotation overlay — click any element to create a task with its CSS selector, URL, and source location.
vibeflow tasks
Full task management from the command line — designed to be agent-friendly.
**Task types:** Task · Bug · Feature · Enhancement · Research
**Task statuses:** backlog → todo → in-progress → review → done
**Priorities:** Critical · High · Medium · Low
Root and child tasks
A task with a parent link is a **child**; a task without one is a **root**. The CLI hands an agent
whole units of work, so both listing and claiming operate on roots:
- vibeflow tasks lists **root tasks only**. A child belongs to its parent and is rendered inside
that parent's card on the board, so listing it as a peer would contradict the board. The footer
reports how many children the query matched — · 3 child tasks hidden (use --children) — so they
are never hidden silently. Pass --children to include them.
- vibeflow tasks --next claims **only a root whose own status is todo**, and never a child. The
result carries that root's children with their ids, titles and statuses, so the agent sees what
remains without a second call. Claiming a root does **not** cascade to its children — the agent
walks them.
- vibeflow tasks --get is deliberately **unfiltered**: it resolves any task, child or root,
so a child is always reachable by id.
Because --next only considers roots whose own status is todo, a child in todo whose parent is
in backlog, in-progress or done is not returned by --next. Move the root to todo to make the
whole unit claimable.
vibeflow watch [dir]
Runs until interrupted (Ctrl+C) and prints full ticket details whenever a task is
newly created or moved back to todo — handy as a driver for AI-agent loops that
react to new work.
vibeflow telemetry
No PII is ever collected. User identity is hashed.
**What is collected.** One command_run event per invocation with a small,