Vibeflow

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.

🌐 Website · 📖 Tutorial

▶ [Watch the full motion demo (MP4)](https://www.vibeflow.tools/assets/demo/showcase.mp4)

---

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.

---

Install

Run it once with npx — nothing to install:

npx @vibeflow-tools/cli kanban

Or install it globally for day two. This adds the short alias vf:

npm install -g @vibeflow-tools/cli

vibeflow kanban # or: vf kanban

Requirements: Node.js >= 22. Apache-2.0 licensed. No account and no cloud — every task is a JSON file in your repo.

---

Quick Start

# 1. Start the local server and open the Kanban board

npx @vibeflow-tools/cli kanban

2. Annotate a running app: open http://localhost:3700/inject and drag the

bookmarklet onto your bookmarks bar (or use the script tag / console snippet)

3. Click elements in your app to create tasks — the CSS selector, URL and

source location are captured for you. You can also create tasks on the board.

4. Let your agent pick up the next task with full context

npx @vibeflow-tools/cli tasks --next

---

See It in Action

Drag tasks across the board — Backlog → Todo → In Progress → Review → Done. Drag a card to change its status and the board persists the new column and order, even after a reload. Tag, user and type filters keep their state while you move work, and every change is written straight to the task store — so the CLI and your agent see it immediately.

Break work into a parent / child tree — Turn an epic into child tasks that keep their own status, priority and history. Expand the tree inline on the card, or create children from the terminal with vibeflow tasks --add --title "..." --parent . The same hierarchy comes back from vibeflow tasks --get , so an agent can pick up a leaf without losing the parent.

Get the whole ticket in one panel — Open any card for the full ticket: status, description, tags, priority, author, relations (children and related tasks), an activity feed and file attachments. Changes save automatically, and pasting a screenshot or file anywhere in the panel attaches it to the task instead of your Downloads folder.

---

MCP Server

Vibeflow exposes its task tools over MCP, so an agent can read and update tickets directly. Configure one server per project: a server resolves its project root once at startup and every tool call uses that root, so it cannot write into the wrong project.

stdio (recommended — no port, nothing to keep running):

{

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

--project is required: a spawned client's working directory (often your home directory) is never trusted, and the root is validated before anything is created. Put this config _with_ the project — .mcp.json at the repo root, or your editor's workspace config using ${workspaceFolder}.

HTTP (a server you keep running):

vibeflow serve --project ./my-project    # MCP endpoint at /api/mcp

Loopback-only until you configure a token. Both transports mount the identical tool set; only the transport differs.

Do not run one global server with a per-call project argument — that is deliberately not supported. One process serves one root, resolved at startup.

A type:"Research" task is refused review with RESEARCH_REPORT_REQUIRED until a .md report is attached, and over MCP the way to do that is `attach_file` with a `.md` filename — the gate looks for a .md among a task's files, so the name is what counts. There is no --report-file equivalent on this surface; the CLI flag is named in the refusal's suggestion for CLI callers only. A Research task must not carry a verification verdict (RESEARCH_VERIFY_NOT_ALLOWED) — it has no annotated UI to verify.

MCP results

A tool's result carries its payload as one JSON document in `content[0].text` — that holds for every tool-level success and every tool-level refusal. There are exactly two shapes that are not JSON: a *protocol-level* failure — arguments the tool's own schema rejects, or the name of a tool that does not exist — comes back as result.isError === true with content[0].text = MCP error -32602: … and no envelope to parse. So check isError first and parse the text as JSON only when it is absent.

Those two protocol-level failures are told apart by what the message names, not by the code — the SDK reports an unknown tool through the same input-validation path, so both carry -32602 even though JSON-RPC reserves -32601 for "method not found":

The schema-error class (-32602) — no vibeflow code, by design

An input the tool's own schema rejects (create_task with no title, attach_file with no contentB64, list_tasks with limit:-1) is refused by the MCP SDK's input validation, before any vibeflow handler runs. vibeflow therefore never sees the call and cannot attach a code or a suggestion to it. What arrives is:

result.isError === true

content[0].text = "MCP error -32602: Input validation error: Invalid arguments for tool create_task: Invalid input: expected string, received undefined at title"

Three properties, all deliberate and all load-bearing:

• It has no entry in the code table below, and never will. Every code in that table is a vibeflow domain code that a handler produced on purpose. -32602 is the JSON-RPC *invalid params* code; it is not a member of vibeflow's vocabulary, and -32602 will never appear as a row there.
• It names the offending field (… at title, … at contentB64) — the last word of the message is the field you got wrong.
• Its code string is client-dependent, so do not key on it. Some clients normalise this class into a string of their own (the Pi MCP adapter reports it as call_failed, for instance). That label belongs to the client, not to vibeflow: the same refusal is MCP error -32602 from a plain JSON-RPC client, and greping for one client's label in another's output is how a consumer concludes the behaviour differs when it does not.

Recognise the class by its shape, not by any code string: a result with isError === true whose text carries an input-validation message naming a field. The remedy is always the same — send the field it names, with the type the schema asks for. An unknown tool is NOT a member of this class: it names no field, so the rule above does not match it, and its remedy is a different one (the table above). Keying on the code alone would put the two in one bucket and send the reader after an input field when the real mistake was the tool's name.

Because tools/list is the only place a client can read the contract *before* it fails, the input shapes publish a description for every field an agent commonly gets wrong — id on each task tool (most take a full id or a unique prefix), the setVerify/verifyReason pair, limit, contentB64, the comment body, and filename (its extension decides acceptance). Read them there; there is no second chance.

Three rules for the JSON case, all of them the CLI's own conventions:

• A refusal is the CLI envelope. {ok:false, error:{code, message, retryable, suggestion?}} — the same shape tasks --json writes to stderr, so one parser reads both surfaces. A tool-level refusal does not set isError; it is an ordinary result whose JSON is {ok:false, …}.
• Every refusal carries a `suggestion`, and it means "what to change". A code tells you which rule fired; the suggestion tells you the input that satisfies it. error.suggestion is a non-empty string on every tool-level refusal — including the generic catch wrappers (LIST_TASKS_ERROR, GET_TASK_ERROR, CREATE_TASK_ERROR, UPDATE_TASK_ERROR, ADD_COMMENT_ERROR, ATTACH_FILE_ERROR, VERIFY_TASK_ERROR, PUSH_TASKS_ERROR, CLAIM_TASK_ERROR) — and it names both surfaces where the same gate is reachable: the MCP input or tool *and* the CLI flag. A shared gate's suggestion is read by the CLI and by MCP update_task alike, so a CLI-only suggestion is an answer an MCP client cannot act on. (verify_task is the one tool that returns the CLI verify engine's own codes — E_NOT_FOUND, E_NO_BASELINE, E_NO_SELECTOR and the rest. Those codes are unchanged; where the engine attaches no text of its own, the tool substitutes a generic recovery line rather than returning a code with nothing to act on.) The one class with no suggestion is the schema error above, which never reaches a handler.
• "Nothing to claim" is a success. claim_next_task on an empty board — or with a valid filter that matched no task — is ok with a payload of null, not an error. A claim's payload is the Task itself, so an object means a task was claimed and `null` means there was nothing to claim; that is the same answer vibeflow tasks --next --json gives with task:null and exit 0. The dryRun preview answers the same way, so a preview cannot disagree with the real call. There is no NO_TASKS_AVAILABLE code.
• Non-failures you must know about ride `notices`, an array of {code, message} objects and the *same* key the CLI puts on its --json success payloads. A notice is a non-fatal signal, not a synonym for partial success — branch on code, never on the array merely being present:

A dryRun:true preview carries notices:[{code:"DRY_RUN", message:"Task would be updated"}] (or the matching phrase — Task would be created / claimed, Comment would be added, File would be attached, Verification would run); a review transition carries GIT_COMMITTED with the sha when its auto-