![\"Annotask\"](\"annotask-logo.png\"){kind=logo}
\n \n
\n Annotate the UI of your running web app. AI agents apply the changes back to source.\n
\n\n\n Landing & demo → ·\n Setup ·\n CLI ·\n API ·\n Skills\n
\n\n\n ![\"Annotate](\"docs/media/hero.png\")
\n
\n 90-second demo: watch on the landing page · inline GIF\n
\n\nAnnotask is a dev-only tool. You open `/__annotask/` next to your running app, mark up the UI, and the tool produces structured tasks. An AI coding agent reads those tasks over MCP, CLI, or HTTP, applies code changes to source, and ships them back for accept/deny in the browser.\n\nSupports Vue, React, Svelte, SolidJS, Astro, plain HTML, and htmx on Vite. Webpack support is available through `AnnotaskWebpackPlugin` for the non-Astro integration path.\n\n## The loop\n\n```text\nYou in the browser Your coding agent\n------------------ -----------------\nOpen /__annotask/\nAnnotate, inspect, edit,\nor create audit fixes --> Reads tasks over MCP / CLI / HTTP\n Locks task: in_progress\n Pulls extra context only when needed\n Applies code changes\n Marks task review-ready\n\nReview in the task drawer <--> Answers questions / retries denied work\nAccept or deny changes\n```\n\nThe coding agent can be **external** (your editor's agent, reading tasks over MCP/CLI/HTTP) or **embedded** — see below.\n\n## Embedded agents\n\nAnnotask can run a coding agent in-shell. Point it at a local CLI (claude, codex,\nopencode, copilot) or an HTTP provider (Anthropic, OpenAI-compatible, OpenRouter)\nin Settings, and the agent applies tasks without leaving the browser. Runs stream\ninto a per-task conversation thread (persisted to `.annotask/conversations/`),\nare gated to the same origin/port, respect an optional `ANNOTASK_MAX_PERMISSION`\nceiling, and are bounded by idle/duration watchdogs. The agent — never the tool —\nwrites application source.\n\n## Wireframing\n\nFreeze the current route into a manipulable snapshot canvas, then sketch: drag,\nresize, multi-select and nudge, soft-delete, duplicate, drop palette components\n(configured in place with props), and draw sections with a markdown spec. Hit **Implement\nthis wireframe** and Annotask diffs the sketch into anchored directions, snapshots\nevery file it touches, and drives the embedded agent through the apply loop —\nspatial relations are the contract, pixels are hints. **Undo last apply**\nrestores that batch's pre-apply bytes and **Discard session** restores every\ntouched file to its session base, both hash-guarded so a file you edited\noutside Annotask is never clobbered. In git projects the reversal is byte-exact\nacross the whole apply footprint — the engine baselines off `git stash-create`,\nauto-extends via `git show`, and recreates agent-deleted files — while non-git\nprojects fall back to reverting the predicted anchor files only.\n\n## What it does\n\nAnnotask has three user-facing surfaces.\n\n- **Annotate**: pins, arrows, text highlights, screenshots, route-aware tasks, viewport capture. (Sections are wireframe sketch material — draw them on the wireframe canvas.)\n- **Design**: tokens, live inspector, layout overlay, detected component catalogs, in-repo component examples.\n- **Audit**: accessibility, data sources, API schemas, detected data/state libraries, performance findings, console errors.\n\nTasks can carry grounded context when available:\n\n- source file and line\n- component references and examples\n- viewport and route\n- screenshots\n- color-scheme detection\n- interaction history\n- element context\n- data context and API schema links\n\n## Quick start\n\nInstall:\n\n```bash\nnpm install -D annotask\n```\n\nVite:\n\n```ts\nimport { defineConfig } from 'vite'\nimport vue from '@vitejs/plugin-vue'\nimport { annotask } from 'annotask'\n\nexport default defineConfig({\n plugins: [vue(), annotask()],\n})\n```\n\nWebpack:\n\n```ts\nimport { AnnotaskWebpackPlugin } from 'annotask/webpack'\n\nexport default {\n plugins: [new AnnotaskWebpackPlugin()],\n}\n```\n\nStart your dev server, then open `http://localhost:5173/__annotask/`.\n\nConnect an agent over MCP:\n\n```bash\nnpx annotask init-mcp --editor=claude\n```\n\nOr install the bundled skills:\n\n```bash\nnpx annotask init-skills\n```\n\n## Agent surfaces\n\n- **MCP**: `POST /__annotask/mcp` with 28 tools for tasks, design spec, components, screenshots, code context, data context, data sources, API schemas, runtime endpoints, interaction history, rendered HTML, playbooks, and per-task conversations.\n- **CLI**: `annotask status`, `tasks`, `task`, `design-spec`, `components`, `component-examples`, `data-context`, `data-sources`, `runtime-endpoints`, `interaction-history`, `rendered-html`, `api-schemas`, `resolve-endpoint`, `source-excerpt`, `playbook`, `agent-directions`, `init-mcp`, `init-skills`, `mcp`, and more.\n- **HTTP + WebSocket**: local API under `/__annotask/api/*` and live updates on `/__annotask/ws`.\n\n## Task model\n\nCanonical task types live in `src/schema.ts`:\n\n- `annotation`\n- `section_request`\n- `style_update`\n- `theme_update`\n- `a11y_fix`\n- `error_fix`\n- `perf_fix`\n- `wireframe_apply` — wireframe palette placements (\"Build this route\"); `context.wireframe` carries `{ route, instances[] }` with a per-instance `anchor` (`file`, `line`, `position`, `component`, `targetTag`) and `inserted` payload (`tag`, `componentName`, `library`, `module`, `props`, `classes`, `text_content`)\n\nStatuses:\n\n- `pending`\n- `in_progress`\n- `applied`\n- `review`\n- `accepted`\n- `denied`\n- `needs_info`\n- `blocked`\n\nTypical path:\n\n```text\npending -> in_progress -> review -> accepted | denied\n \\-> needs_info\n \\-> blocked\n```\n\n`applied` exists as an optional intermediate automation state and is accepted by the API, CLI, and MCP layers.\n\n## Current highlights\n\n- Embedded agent mode — apply tasks in-shell via a local CLI or HTTP provider, with a per-task conversation thread\n- Snapshot wireframing with byte-exact, hash-guarded undo/discard of every agent apply\n- Route-aware task filtering and editable route bar\n- Screenshot uploads and automatic cleanup on acceptance\n- Variant-aware design spec with `themes[]`, `defaultTheme`, and per-theme token values\n- Workspace-aware scanning across monorepos and MFEs\n- MFE filters in the shell's Components and Audit data views\n- Component examples from real in-repo usage\n- Data-source discovery, binding analysis, and endpoint-to-schema resolution\n- Runtime endpoint monitoring — the iframe's actual fetch/XHR/beacon calls\n surface as a runtime catalog alongside the static scan\n- Local `axe-core` accessibility scanning\n- Performance snapshots, findings, and session recording\n- Console error and warning capture with one-click fix tasks\n- Always-captured interaction history and rendered-HTML sidecars per task\n- 18 built-in shell themes plus custom theme editing across 62 CSS variables\n\n## Framework support\n\n| Framework | Vite | Webpack |\n|-----------|------|---------|\n| Vue 3 | Yes | Yes |\n| React | Yes | Yes |\n| Svelte | Yes | Yes |\n| SolidJS | Yes | Yes |\n| Plain HTML | Yes | No |\n| Astro | Yes | No |\n| htmx | Yes | No |\n\nAnnotask is dev-only. It does not run in production builds.\n\n## Security\n\nAnnotask runs an **unauthenticated** dev API on your local server, and the embedded agent can write source files and run shell commands at your project root. By default there is no permission ceiling. Treat it like any other local dev tool:\n\n- Run it only on code (and dependencies) you trust — same-origin app code can reach the API.\n- Don't expose the dev server beyond `localhost`. `vite --host` opens it to your LAN; prefer an SSH tunnel, and Annotask prints a loud warning when it binds non-loopback.\n- In shared / CI / locked-down setups, set `ANNOTASK_MAX_PERMISSION=plan` (read-only) or `default` to cap what a spawned agent can do.\n\nSee [SECURITY.md](./SECURITY.md) for the full model.\n\n## Monorepos and MFEs\n\nAnnotask is workspace-aware. When the project lives inside a pnpm, npm, Yarn, Bun, or Lerna workspace, server-side scanners can walk sibling packages for:\n\n- component libraries used by adjacent MFEs\n- project data sources and bindings\n- API schemas\n- workspace package metadata and MFE ids\n\nFor MFE setups, child apps can point at a root Annotask server with `annotask({ mfe, server })` or `new AnnotaskWebpackPlugin({ mfe, server })`.\n\n## Docs\n\n- [SETUP.md](SETUP.md)\n- [docs/setup.md](docs/setup.md)\n- [docs/cli.md](docs/cli.md)\n- [docs/api.md](docs/api.md)\n- [docs/skills.md](docs/skills.md)\n- [docs/component-discovery.md](docs/component-discovery.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/development.md](docs/development.md)\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm dev:vue-vite\npnpm typecheck\npnpm test\npnpm test:e2e\n```\n\nUseful extras:\n\n- `pnpm dev:shell` for standalone shell UI work\n- `pnpm test:e2e:stress` for the stress-test environment\n- `pnpm stress-test:up` / `pnpm stress-test:down` for Docker-based stress services\n\n## Project structure\n\n- `src/plugin/` - Vite integration and transform pipeline\n- `src/server/` - HTTP API, WebSocket server, persistence, scanners\n- `src/mcp/` - embedded MCP server\n- `src/webpack/` - Webpack plugin and loader\n- `src/shell/` - Vue shell UI served at `/__annotask/`\n- `src/cli/` - `annotask` CLI\n- `src/schema.ts` - canonical task, report, design-spec, and context types\n- `skills/` - bundled `/annotask-init` and `/annotask-apply` skills\n- `playgrounds/simple/` - single-framework demos\n- `playgrounds/stress-test/` - multi-MFE, multi-service stress lab\n","readmeFilename":"README.md"}![inline GIF](\"docs/media/demo.gif\"){kind=link}