# 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.

```bash
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

```bash
# 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

| 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]`

```bash
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]`

```bash
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.

```bash
# 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.

```bash
# 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]`

```bash
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`

```bash
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:

| Method | Best for | CSP-safe |
| -------- | ---------- | ---------- |
| **Bookmarklet** (recommended) | Any page, including production apps | Yes |
| **Script tag** | Pages you control the HTML of | No |
| **DevTools console** | Quick one-off sessions | Yes |

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](https://github.com/opencode-ai/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](https://registry.modelcontextprotocol.io) (`server.json` in this repo).

### Install and run

```bash
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`:

```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:

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

### Tools

| Tool | What it does |
| ---- | ------------ |
| `list_tasks` | List tasks with optional filters (root tasks only unless `children`) |
| `get_task` | One task by ID, with comments and files |
| `get_project` | The resolved project this server is attached to — root, branch, mode |
| `create_task` | Create a task, optionally annotated with a URL and selector |
| `update_task` | Edit a task: status, title, links, and the verification verdict |
| `claim_next_task` | Claim the highest-priority root task in `todo` as `in-progress` |
| `add_comment` | Comment on a task |
| `attach_file` | Attach a file (base64); a `.md` satisfies the research-report gate |
| `export_prompt` | Export one or more tasks as a formatted LLM prompt |
| `verify_task` | Run visual verification for an annotated task |
| `start_kanban` | Start the local Kanban board server and return its URLs |
| `get_integration_guide` | The overlay/bookmarklet integration instructions |

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](packages/cli/README.md#mcp-server).

---

## 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

```bash
npm install -g @vibeflow-tools/cli
```

Or run without installing:

```bash
npx @vibeflow-tools/cli kanban
```

**Requirements:** Node.js >= 22

---

## Contributing

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

---

## License

[Apache-2.0](LICENSE) — see [NOTICE](NOTICE) for third-party attributions.