[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_177":178},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":56,"_57":-5,"_58":50,"_59":60,"_61":62,"_63":-5,"_64":-5,"_65":-5,"_66":-5,"_67":68,"_69":70,"_71":72,"_73":74,"_75":76,"_77":-5,"_78":-5,"_79":-5,"_80":81,"_82":-5,"_83":44,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95,"_96":97},"apiUrl","https://odel.app/api","creator","zorcec","moduleId","vibeflow","@zorcec/vibeflow","displayName","Vibeflow","tagline","Kanban for agentic development over MCP — annotate any UI element into a ticket with file and line.","iconKey","external/e6b168a049329c24905cd1e3b1fdb506af38c1446216ab97d121b7c81cdbc6a1.svg","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","priceCredits",0,"creatorUserId","system:external-import","createdAt",1791445603000,"updatedAt",1791532208000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.zorcec%2Fvibeflow","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",2,"upstreamUpdatedAt",1791405009000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/zorcec/vibeflow","githubRepoFullName","zorcec/vibeflow","releaseId","ext-zorcec-vibeflow","version","0.19.3","descriptionMarkdown","# Vibeflow\n\n> **Tell your AI agent exactly what to fix — by clicking on it.**\n\nVibeflow eliminates the back-and-forth of describing UI bugs in words. Click any element on a page to create a task with its exact CSS selector, URL, and source location. Your agent gets precise, actionable context — no \"the button in the top right\" needed.\n\n```bash\nnpm install -g @vibeflow-tools/cli\nvibeflow kanban\n```\n\n---\n\n## Why It Matters\n\nAI agents write code fast, but **understanding what to change is slow**. Describing a UI issue in prose wastes tokens and produces wrong fixes.\n\nVibeflow turns visual feedback into structured tasks:\n\n- **Click any element** → instant task with CSS selector, URL, and source file location\n- **Track on a Kanban board** → see everything at a glance, drag between columns\n- **Agents implement with context** → no guessing, no wrong elements, no wasted iterations\n\nPerfect for small UI fixes, broken layouts, spacing issues, and anything where pointing is faster than explaining.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Embed the overlay into your app (bookmarklet, script tag, or devtools)\n# Visit /inject on your running server for ready-to-use snippets\n\n# 2. Open the Kanban board\nvibeflow kanban\n\n# 3. Click elements in your app to annotate, or create tasks on the board\n\n# 4. Your agent picks the next task with full context executing following command\nvibeflow tasks --next\n\n```\n\n---\n\n## Commands\n\n| Command | Description |\n| --------- | ------------- |\n| `vibeflow kanban [dir]` | Start the server and open the live Kanban board in your browser |\n| `vibeflow serve [target]` | Serve HTML files with live annotation overlay, or run API-only task server for existing apps |\n| `vibeflow tasks` | List, filter, create, edit, and comment on tasks |\n| `vibeflow watch [dir]` | Watch the task store and print ticket details for important updates |\n| `vibeflow telemetry` | Manage CLI usage telemetry (opt-out at any time) |\n\n### `vibeflow kanban [dir]`\n\n```bash\nvibeflow kanban # open Kanban board for current directory\nvibeflow kanban ./my-project # open Kanban for a specific project\n```\n\nThe 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.\n\n### `vibeflow serve [target]`\n\n```bash\nvibeflow serve . # serve all HTML files in current directory\nvibeflow serve dashboard.html # serve a single file\nvibeflow serve -p 4000 . # custom port\nvibeflow serve --no-open . # don't open browser automatically\nvibeflow serve # API-only mode — connects to an existing hosted app\n```\n\nServe HTML prototypes with the annotation overlay — click any element to create a task with its CSS selector, URL, and source location.\n\n### `vibeflow tasks`\n\nFull task management from the command line — designed to be agent-friendly.\n\n```bash\n# Pick the next task (auto-claims a ROOT task in todo)\nvibeflow tasks --next # highest-priority ROOT task in todo\nvibeflow tasks --next --type Bug # next bug ROOT task only\n\n# List tasks\nvibeflow tasks # ROOT tasks only (default: 20 most recent)\nvibeflow tasks --children # include child tasks\nvibeflow tasks --limit 0 # show all tasks (no limit)\nvibeflow tasks --json # machine-readable JSON output\n\n# Filter\nvibeflow tasks --status todo # by status\nvibeflow tasks --type Bug # by type (Task, Bug, Feature, Enhancement, Research)\nvibeflow tasks --user dev@example.com # by author email\nvibeflow tasks --tag frontend --tag urgent # by tags (AND matching)\n\n# Get full details of a single task\nvibeflow tasks --get # supports partial ID prefix\n\n# Create a task\nvibeflow tasks --add --title \"Fix header\" --description \"Button overflows on mobile\"\n\n# Edit a task\nvibeflow tasks --edit --set-status in-progress\nvibeflow tasks --edit --title \"Updated title\" --description \"More detail\"\n\n# Mark as review (requires implementation report)\nvibeflow tasks --edit --set-status review \\\n --commit-message \"fix: header layout\" \\\n --comment \"Fixed the alignment issue by adjusting flex-wrap\"\n```\n\n**Task types:** Task · Bug · Feature · Enhancement · Research \n**Task statuses:** backlog → todo → in-progress → review → done \n**Priorities:** Critical · High · Medium · Low\n\n#### Root and child tasks\n\nA task with a `parent` link is a **child**; a task without one is a **root**. The CLI hands an agent\nwhole units of work, so both listing and claiming operate on roots:\n\n- `vibeflow tasks` lists **root tasks only**. A child belongs to its parent and is rendered inside\n that parent's card on the board, so listing it as a peer would contradict the board. The footer\n reports how many children the query matched — `· 3 child tasks hidden (use --children)` — so they\n are never hidden silently. Pass `--children` to include them.\n- `vibeflow tasks --next` claims **only a root whose own status is `todo`**, and never a child. The\n result carries that root's children with their ids, titles and statuses, so the agent sees what\n remains without a second call. Claiming a root does **not** cascade to its children — the agent\n walks them.\n- `vibeflow tasks --get ` is deliberately **unfiltered**: it resolves any task, child or root,\n so a child is always reachable by id.\n\n```bash\n# A root with children, claimed as one unit of work\nvibeflow tasks --next\n# ▶ NEXT TASK — Status moved to in-progress. Implement this now:\n# [in-progress] Rebuild the settings page\n# ↓ 2 child tasks (1 done)\n# [done] a1b2c3d4 Remove the legacy toggle\n# [todo] e5f6a7b8 Add the keyboard shortcut\n```\n\nBecause `--next` only considers roots whose own status is `todo`, a child in `todo` whose parent is\nin `backlog`, `in-progress` or `done` is not returned by `--next`. Move the root to `todo` to make the\nwhole unit claimable.\n\n### `vibeflow watch [dir]`\n\n```bash\nvibeflow watch # watch the current directory's task store\nvibeflow watch ./my-project # watch a specific project\n```\n\nRuns until interrupted (Ctrl+C) and prints full ticket details whenever a task is\nnewly created or moved back to `todo` — handy as a driver for AI-agent loops that\nreact to new work.\n\n### `vibeflow telemetry`\n\n```bash\nvibeflow telemetry # show current status\nvibeflow telemetry --disable # opt out of usage tracking\nvibeflow telemetry --enable # opt back in\n```\n\nNo PII is ever collected. User identity is hashed.\n\n**What is collected.** One `command_run` event per invocation with a small,\ncoarse property set:\n\n- `command` — the top-level command (`tasks`, `serve`, `kanban`, …)\n- `subcommand` — the mode within a command that has one: `tasks` emits\n `list` / `get` / `add` / `edit` / `next` / `reindex`, `serve` emits `api`\n (API-only task server) or `prototype` (an HTML target was given)\n- `from_status` / `to_status` — on `tasks --edit` only: the task's status\n before and after the edit, drawn from\n `backlog | todo | in-progress | review | done`, so status transitions are\n queryable as a funnel\n\nNever collected: task ids, titles, descriptions, file paths, selectors, URLs,\nor any other task content.\n\n---\n\n## Browser Overlay\n\nThe overlay is a Shadow DOM panel injected into any page — HTML prototypes or live apps:\n\n- **Click-to-annotate** — click any element to open a task form, pre-filled with CSS selector, URL, and source location\n- **Task sidebar** — lists open tasks with status badges; click to jump to the annotated element\n- **Task indicators** — numbered markers on annotated elements\n- **Real-time sync** — over WebSocket with live file watching\n- **Screenshot capture** — attach screenshots to tasks via the overlay\n- **Dark theme** — polished dark UI, no configuration needed\n- **Keyboard shortcut** — `Alt+A` to toggle annotation mode\n- **CSP-safe injection** — bookmarklet bypasses `script-src` restrictions\n\n### Injection Methods\n\nThe overlay can be injected into any page three ways:\n\n| Method | Best for | CSP-safe |\n| -------- | ---------- | ---------- |\n| **Bookmarklet** (recommended) | Any page, including production apps | Yes |\n| **Script tag** | Pages you control the HTML of | No |\n| **DevTools console** | Quick one-off sessions | Yes |\n\nVisit `/inject` on your running server for ready-to-use bookmarklets and snippets.\n\n---\n\n## How It Works\n\n```\nYou browse your app → click to annotate → task created with context\n ↑ ↓\n browser reloads ← agent implements ← vibeflow tasks --next\n```\n\n1. **Overlay** — embed the bookmarklet or script into your app, click any element to annotate\n2. **Kanban** — open the board to see all tasks at a glance, create new ones directly\n3. **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\n4. **Iterate** — agent implements, browser reloads, annotate again\n\n---\n\n## Writing Prototypes\n\nEach HTML file is one screen. Use Tailwind CSS, Lucide icons, and Google Fonts via CDN — the annotation contract tells your LLM to use exactly these libraries.\n\n**Rules:**\n\n- One file per screen — name after the route (`login.html`, `dashboard.html`)\n- Every meaningful element gets a `data-vibeflow-id` — kebab-case, globally unique\n- Navigate between pages with relative links: ``\n- Repeat navigation on every page (no shared includes)\n\n```html\n\n\n\n \n \n App — Dashboard\n \n \n \n \n\n\n

Dashboard

\n \n\n\n```\n\n---\n\n## Agent Integration\n\nVibeflow tasks are formatted for AI agents with full context:\n\n- **CSS selectors** — exact element targeting, no guesswork\n- **Source locations** — file, line, and column where the element is defined\n- **Screenshots** — visual context attached to tasks\n- **Comments** — threaded discussions on each task\n- **File attachments** — research reports, specs, and reference materials\n- **Git commits** — changes linked back to tasks via `[proto:task-id]` in commit messages\n\nAgents 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.\n\n---\n\n## MCP Server\n\nVibeflow 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.\n\nThe 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).\n\n### Install and run\n\n```bash\nnpm install -g @vibeflow-tools/cli\nvibeflow mcp --project /path/to/project\n```\n\n`--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.\n\n### Client configuration\n\n**Claude Desktop** — add to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"vibeflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@vibeflow-tools/cli\", \"mcp\", \"--project\", \"/path/to/project\"]\n }\n }\n}\n```\n\n**Cursor** — the same block goes in `.cursor/mcp.json` in your project:\n\n```json\n{\n \"mcpServers\": {\n \"vibeflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@vibeflow-tools/cli\", \"mcp\", \"--project\", \"/path/to/project\"]\n }\n }\n}\n```\n\n### Tools\n\n| Tool | What it does |\n| ---- | ------------ |\n| `list_tasks` | List tasks with optional filters (root tasks only unless `children`) |\n| `get_task` | One task by ID, with comments and files |\n| `get_project` | The resolved project this server is attached to — root, branch, mode |\n| `create_task` | Create a task, optionally annotated with a URL and selector |\n| `update_task` | Edit a task: status, title, links, and the verification verdict |\n| `claim_next_task` | Claim the highest-priority root task in `todo` as `in-progress` |\n| `add_comment` | Comment on a task |\n| `attach_file` | Attach a file (base64); a `.md` satisfies the research-report gate |\n| `export_prompt` | Export one or more tasks as a formatted LLM prompt |\n| `verify_task` | Run visual verification for an annotated task |\n| `start_kanban` | Start the local Kanban board server and return its URLs |\n| `get_integration_guide` | The overlay/bookmarklet integration instructions |\n\nThe 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.\n\n### Authentication\n\n**None required.** Vibeflow is local-first: no login, no account, no API key. Every task is a file in your repo.\n\nAn HTTP transport also exists (`vibeflow serve`, MCP endpoint at `/api/mcp`), but it is a local loopback server rather than a public one.\n\nFor the full protocol reference — result envelope shape, refusal codes, `notices`, and the `dryRun` preview — see the [CLI package README](https://github.com/zorcec/vibeflow/blob/main/packages/cli/README.md#mcp-server).\n\n---\n\n## API\n\nA REST API and tRPC router are available at `http://localhost:3700` for integrations and the browser overlay. Key endpoints:\n\n- `/kanban` — live Kanban board\n- `GET/POST /api/tasks` — list and create tasks\n- `GET/PATCH/DELETE /api/tasks/:id` — manage individual tasks\n- `GET/POST /api/tasks/:id/comments` — task comments\n- `GET/POST/DELETE /api/tasks/:id/files` — file attachments\n- `POST /api/agent/run` — spawn an AI agent for a task\n- `/inject` — overlay injection helper page\n\nSee `src/server/server.ts` for the full API.\n\n---\n\n## Installation\n\n```bash\nnpm install -g @vibeflow-tools/cli\n```\n\nOr run without installing:\n\n```bash\nnpx @vibeflow-tools/cli kanban\n```\n\n**Requirements:** Node.js >= 22\n\n---\n\n## Contributing\n\n```bash\npnpm install # install dependencies\npnpm build:cli # build CLI\npnpm test # unit tests\npnpm test:e2e # end-to-end tests\n```\n\n---\n\n## License\n\n[Apache-2.0](https://github.com/zorcec/vibeflow/blob/main/LICENSE) — see [NOTICE](https://github.com/zorcec/vibeflow/blob/main/NOTICE) for third-party attributions.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt",1791405202000,"priceCents","trialDays","iconType","svg","upstream",{"_147":148,"_120":121,"_149":150,"_151":152,"_140":141,"_124":153},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_145":44,"_146":44},"card",{"_20":22,"_98":24,"_99":26,"_18":19,"_100":28,"_84":85,"_101":102,"_103":37,"_104":-5,"_105":106,"_107":108,"_109":110,"_111":-5,"_112":44,"_113":60,"_49":114,"_115":116,"_117":-5,"_118":119},"name","description","iconUrl","kind","server","hosting","provenance","safety",{"_101":144},"capability","unknown","access",{"_143":30,"_130":131},"contents","priceMicro","stars","2026-10-07T20:30:09.000Z","problems",[],"nsfw","details",{"_73":74,"_120":121,"_122":123,"_124":125,"_126":44,"_127":44,"_47":128},"license","Apache-2.0","links",[136,137,138],"packages",[129],"forks","openIssues","2026-05-22T20:11:29Z",{"_130":131,"_98":132,"_73":74,"_133":134,"_104":135},"registry","npm","@vibeflow-tools/cli","weeklyDownloads",750,false,{"_101":142,"_139":68},{"_101":140,"_139":141},{"_101":130,"_139":54},"href","homepage","https://www.vibeflow.tools","repo","via","unassessed","ratingAvg","reviewCount","topics",[157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176],"language","TypeScript","registryName","io.github.zorcec/vibeflow",[154],{"_155":131,"_156":132,"_73":74},"registryType","identifier","agents","ai","ai-agents","annotation","browser-automation","cli","developer-tools","devtools","express","kanban","llm","mcp","model-context-protocol","nodejs","playwright","prompt-engineering","screenshot","task-management","typescript","websocket","ENV",{"_179":180,"_181":182,"_183":184,"_185":-7},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272","SENTRY_ENABLE_LOCAL"]