// 3 steps to ship

Simple by design.
Powerful by default.

Run the tool. Annotate your UI. Point your AI agent at the task list. That's the entire workflow.

// requirements

What you need

Required
Node.js 22+
Vibeflow runs on Node.js. Install from nodejs.org or via your package manager. Run node --version to verify.
Recommended
React in dev mode, or sourcemaps enabled
For React apps, run in NODE_ENV=development (the default for next dev). Dev mode exposes component names, source files, and line numbers — giving your agent precise context for every annotation.
1Add overlay
Inject onto any page.
Start the Vibeflow server with one command. Then inject the overlay onto any page — bookmarklet, script tag, or the built-in file server. No browser extension needed.
# drag to bookmarks bar — runs on any tab
keep CLI server running on localhost:3700
# add before </body> while server is running
<script src="http://localhost:3700/vibeflow-overlay.js" data-vibeflow-overlay></script>
# fastest setup for local HTML projects
$ npx @vibeflow-tools/cli serve ./my-app
opens localhost:3700 with overlay enabled
2Annotate
Click. Type. Done.
Open localhost:3700 in your browser. Click any element, write a note, set priority. Tasks go straight to .vibeflow/ — versioned in git, live in the Kanban board.
# open kanban board
$ npx @vibeflow-tools/cli kanban
or press Alt+A in the browser overlay to toggle annotation mode
 
3Tell the agent
Ship it.
Give your AI agent one command. It claims the next task, implements it, and marks it for review — automatically. Tasks include CSS selector, file, line number, and your note.
 
Get next tasks and implement them:
npx @vibeflow-tools/cli tasks --next
 

The magic prompt for your agent

Drop this into Copilot, Claude, or Cursor. --next claims the task atomically — safe even when multiple agents are running in parallel.

// paste into your agent "Get next tasks and implement them:
npx @vibeflow-tools/cli tasks --next"
// cli reference

All commands, at a glance

Everything you need. Nothing you don't.

Command Description
Serving
npx @vibeflow-tools/cli serve [target]
Serve an HTML folder with the annotation overlay. Omit target for API-only mode.
npx @vibeflow-tools/cli kanban
Start the server and open the live Kanban board.
Tasks
npx @vibeflow-tools/cli tasks --next
Agent workflow. Atomically claim the next todo task, set to in-progress, and print details. Safe for parallel agents.
npx @vibeflow-tools/cli tasks
List tasks. Filter with --status, --type, --user, --tag.
npx @vibeflow-tools/cli tasks --get <id>
Full task detail: comments, files, linked commits. Supports partial IDs.
npx @vibeflow-tools/cli tasks --add
Create a task. Requires --title, optional --description.
npx @vibeflow-tools/cli tasks --edit <id>
Update a task: --set-status, --title, --description. Setting review requires --comment.
npx @vibeflow-tools/cli tasks --commit
Commit staged changes and link the SHA to a task. Requires --task <id>.
Other
npx @vibeflow-tools/cli telemetry
Manage anonymous usage telemetry: --enable, --disable, --status.