Vibeflow README

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.

npm install -g @vibeflow-tools/cli
vibeflow kanban

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

# 1. Embed the overlay into your app (bookmarklet, script tag, or devtools)
#    Visit /inject on your running server for ready-to-use snippets

# 2. Open the Kanban board
vibeflow kanban

# 3. Click elements in your app to annotate, or create tasks on the board

# 4. Your agent picks the next task with full context executing following command
vibeflow tasks --next

Commands

vibeflow kanban [dir]

vibeflow kanban                   # open Kanban board for current directory
vibeflow kanban ./my-project      # open Kanban for a specific project

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]

vibeflow serve .                  # serve all HTML files in current directory
vibeflow serve dashboard.html     # serve a single file
vibeflow serve -p 4000 .          # custom port
vibeflow serve --no-open .        # don't open browser automatically
vibeflow serve                    # API-only mode — connects to an existing hosted app

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.

# Pick the next task (auto-claims a ROOT task in todo)
vibeflow tasks --next                             # highest-priority ROOT task in todo
vibeflow tasks --next --type Bug                  # next bug ROOT task only

# List tasks
vibeflow tasks                                    # ROOT tasks only (default: 20 most recent)
vibeflow tasks --children                         # include child tasks
vibeflow tasks --limit 0                          # show all tasks (no limit)
vibeflow tasks --json                             # machine-readable JSON output

# Filter
vibeflow tasks --status todo                      # by status
vibeflow tasks --type Bug                         # by type (Task, Bug, Feature, Enhancement, Research)
vibeflow tasks --user dev@example.com             # by author email
vibeflow tasks --tag frontend --tag urgent        # by tags (AND matching)

# Get full details of a single task
vibeflow tasks --get <id>                         # supports partial ID prefix

# Create a task
vibeflow tasks --add --title "Fix header" --description "Button overflows on mobile"

# Edit a task
vibeflow tasks --edit <id> --set-status in-progress
vibeflow tasks --edit <id> --title "Updated title" --description "More detail"

# Mark as review (requires implementation report)
vibeflow tasks --edit <id> --set-status review \
  --commit-message "fix: header layout" \
  --comment "Fixed the alignment issue by adjusting flex-wrap"

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 <id> is deliberately unfiltered: it resolves any task, child or root, so a child is always reachable by id.

# A root with children, claimed as one unit of work
vibeflow tasks --next
#   ▶ NEXT TASK — Status moved to in-progress. Implement this now:
#   [in-progress] Rebuild the settings page
#     ↓ 2 child tasks (1 done)
#       [done]        a1b2c3d4  Remove the legacy toggle
#       [todo]        e5f6a7b8  Add the keyboard shortcut

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]

vibeflow watch                    # watch the current directory's task store
vibeflow watch ./my-project       # watch a specific project

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

vibeflow telemetry              # show current status
vibeflow telemetry --disable    # opt out of usage tracking
vibeflow telemetry --enable     # opt back in

No PII is ever collected. User identity is hashed.

What is collected. One command_run event per invocation with a small, coarse property set:

• command — the top-level command (tasks, serve, kanban, …)
• subcommand — the mode within a command that has one: tasks emits list / get / add / edit / next / reindex, serve emits api (API-only task server) or prototype (an HTML target was given)
• from_status / to_status — on tasks --edit only: the task's status before and after the edit, drawn from backlog | todo | in-progress | review | done, so status transitions are queryable as a funnel

Never collected: task ids, titles, descriptions, file paths, selectors, URLs, or any other task content.

Browser Overlay

The overlay is a Shadow DOM panel injected into any page — HTML prototypes or live apps:

• Click-to-annotate — click any element to open a task form, pre-filled with CSS selector, URL, and source location
• Task sidebar — lists open tasks with status badges; click to jump to the annotated element
• Task indicators — numbered markers on annotated elements
• Real-time sync — over WebSocket with live file watching
• Screenshot capture — attach screenshots to tasks via the overlay
• Dark theme — polished dark UI, no configuration needed
• Keyboard shortcut — Alt+A to toggle annotation mode
• CSP-safe injection — bookmarklet bypasses script-src restrictions

Injection Methods

The overlay can be injected into any page three ways:

Visit /inject on your running server for ready-to-use bookmarklets and snippets.

How It Works

You browse your app  →  click to annotate  →  task created with context
         ↑                                         ↓
   browser reloads  ←  agent implements  ←  vibeflow tasks --next

1. Overlay — embed the bookmarklet or script into your app, click any element to annotate
2. Kanban — open the board to see all tasks at a glance, create new ones directly
3. Tasks — vibeflow tasks --next claims the highest-priority root task in todo, and returns it with its children — the whole unit of work, with full context for your agent
4. Iterate — agent implements, browser reloads, annotate again

Agent Integration

Vibeflow tasks are formatted for AI agents with full context:

• CSS selectors — exact element targeting, no guesswork
• Source locations — file, line, and column where the element is defined
• Screenshots — visual context attached to tasks
• Comments — threaded discussions on each task
• File attachments — research reports, specs, and reference materials
• Git commits — changes linked back to tasks via [proto:task-id] in commit messages

Agents can also run directly from the Kanban board via POST /api/agent/run, which spawns opencode with full task context.

MCP Server

Vibeflow gives an AI coding agent a Kanban board over your own repository: click any element in your app and it becomes a ticket carrying that element's CSS selector, URL, source file and line. Tasks, progress and verification then live in one place instead of being scattered across a chat transcript.

The server runs locally over stdio, one process per project — there is no hosted Vibeflow service to sign up for. It is published as an MCP server in the official MCP Registry (server.json in this repo).

Install and run

npm install -g @vibeflow-tools/cli
vibeflow mcp --project /path/to/project

--project is required. The project root is resolved once at startup and every tool call uses that root, so a server can never write into the wrong project. Point it at your own repository.

Client configuration

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "vibeflow": {
      "command": "npx",
      "args": ["-y", "@vibeflow-tools/cli", "mcp", "--project", "/path/to/project"]
    }
  }
}

Cursor — the same block goes in .cursor/mcp.json in your project:

{
  "mcpServers": {
    "vibeflow": {
      "command": "npx",
      "args": ["-y", "@vibeflow-tools/cli", "mcp", "--project", "/path/to/project"]
    }
  }
}

Tools

The published package exposes every tool listed above. server.json records that count as toolsAtPinnedVersion, and sync-server-manifest.mjs checks it against packages/cli/src/mcp/manifest.ts on every release — a mismatch warns loudly rather than shipping a number nobody verified.

Authentication

None required. Vibeflow is local-first: no login, no account, no API key. Every task is a file in your repo.

An HTTP transport also exists (vibeflow serve, MCP endpoint at /api/mcp), but it is a local loopback server rather than a public one.

For the full protocol reference — result envelope shape, refusal codes, notices, and the dryRun preview — see the CLI package README.

API

A REST API and tRPC router are available at http://localhost:3700 for integrations and the browser overlay. Key endpoints:

• /kanban — live Kanban board
• GET/POST /api/tasks — list and create tasks
• GET/PATCH/DELETE /api/tasks/:id — manage individual tasks
• GET/POST /api/tasks/:id/comments — task comments
• GET/POST/DELETE /api/tasks/:id/files — file attachments
• POST /api/agent/run — spawn an AI agent for a task
• /inject — overlay injection helper page

See src/server/server.ts for the full API.

Installation

npm install -g @vibeflow-tools/cli

Or run without installing:

npx @vibeflow-tools/cli kanban

Requirements: Node.js >= 22

Contributing

pnpm install       # install dependencies
pnpm build:cli     # build CLI
pnpm test          # unit tests
pnpm test:e2e      # end-to-end tests

License

Apache-2.0 — see NOTICE for third-party attributions.