Annotask

Annotate the UI of your running web app. AI agents apply the changes back to source.

Landing & demo → · Setup · CLI · API · Skills

90-second demo: watch on the landing page · inline GIF

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

Supports Vue, React, Svelte, SolidJS, Astro, plain HTML, and htmx on Vite. Webpack support is available through AnnotaskWebpackPlugin for the non-Astro integration path.

The loop

You in the browser                    Your coding agent
------------------                    -----------------
Open /__annotask/
Annotate, inspect, edit,
or create audit fixes           -->   Reads tasks over MCP / CLI / HTTP
                                      Locks task: in_progress
                                      Pulls extra context only when needed
                                      Applies code changes
                                      Marks task review-ready

Review in the task drawer        <--> Answers questions / retries denied work
Accept or deny changes

The coding agent can be external (your editor's agent, reading tasks over MCP/CLI/HTTP) or embedded — see below.

Embedded agents

Annotask can run a coding agent in-shell. Point it at a local CLI (claude, codex, opencode, copilot) or an HTTP provider (Anthropic, OpenAI-compatible, OpenRouter) in Settings, and the agent applies tasks without leaving the browser. Runs stream into a per-task conversation thread (persisted to .annotask/conversations/), are gated to the same origin/port, respect an optional ANNOTASK_MAX_PERMISSION ceiling, and are bounded by idle/duration watchdogs. The agent — never the tool — writes application source.

Wireframing

Freeze the current route into a manipulable snapshot canvas, then sketch: drag, resize, multi-select and nudge, soft-delete, duplicate, drop palette components (configured in place with props), and draw sections with a markdown spec. Hit Implement this wireframe and Annotask diffs the sketch into anchored directions, snapshots every file it touches, and drives the embedded agent through the apply loop — spatial relations are the contract, pixels are hints. Undo last apply restores that batch's pre-apply bytes and Discard session restores every touched file to its session base, both hash-guarded so a file you edited outside Annotask is never clobbered. In git projects the reversal is byte-exact across the whole apply footprint — the engine baselines off git stash-create, auto-extends via git show, and recreates agent-deleted files — while non-git projects fall back to reverting the predicted anchor files only.

What it does

Annotask has three user-facing surfaces.

• Annotate: pins, arrows, text highlights, screenshots, route-aware tasks, viewport capture. (Sections are wireframe sketch material — draw them on the wireframe canvas.)
• Design: tokens, live inspector, layout overlay, detected component catalogs, in-repo component examples.
• Audit: accessibility, data sources, API schemas, detected data/state libraries, performance findings, console errors.

Tasks can carry grounded context when available:

• source file and line
• component references and examples
• viewport and route
• screenshots
• color-scheme detection
• interaction history
• element context
• data context and API schema links

Quick start

Install:

npm install -D annotask

Vite:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { annotask } from 'annotask'

export default defineConfig({
  plugins: [vue(), annotask()],
})

Webpack:

import { AnnotaskWebpackPlugin } from 'annotask/webpack'

export default {
  plugins: [new AnnotaskWebpackPlugin()],
}

Start your dev server, then open http://localhost:5173/__annotask/.

Connect an agent over MCP:

npx annotask init-mcp --editor=claude

Or install the bundled skills:

npx annotask init-skills

Agent surfaces

• 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.
• 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.
• HTTP + WebSocket: local API under /__annotask/api/* and live updates on /__annotask/ws.

Task model

Canonical task types live in src/schema.ts:

• annotation
• section_request
• style_update
• theme_update
• a11y_fix
• error_fix
• perf_fix
• 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)

Statuses:

• pending
• in_progress
• applied
• review
• accepted
• denied
• needs_info
• blocked

Typical path:

pending -> in_progress -> review -> accepted | denied
                     \-> needs_info
                     \-> blocked

applied exists as an optional intermediate automation state and is accepted by the API, CLI, and MCP layers.

Current highlights

• Embedded agent mode — apply tasks in-shell via a local CLI or HTTP provider, with a per-task conversation thread
• Snapshot wireframing with byte-exact, hash-guarded undo/discard of every agent apply
• Route-aware task filtering and editable route bar
• Screenshot uploads and automatic cleanup on acceptance
• Variant-aware design spec with themes[], defaultTheme, and per-theme token values
• Workspace-aware scanning across monorepos and MFEs
• MFE filters in the shell's Components and Audit data views
• Component examples from real in-repo usage
• Data-source discovery, binding analysis, and endpoint-to-schema resolution
• Runtime endpoint monitoring — the iframe's actual fetch/XHR/beacon calls surface as a runtime catalog alongside the static scan
• Local axe-core accessibility scanning
• Performance snapshots, findings, and session recording
• Console error and warning capture with one-click fix tasks
• Always-captured interaction history and rendered-HTML sidecars per task
• 18 built-in shell themes plus custom theme editing across 62 CSS variables

Framework support

Framework	Vite	Webpack
Vue 3	Yes	Yes
React	Yes	Yes
Svelte	Yes	Yes
SolidJS	Yes	Yes
Plain HTML	Yes	No
Astro	Yes	No
htmx	Yes	No

Annotask is dev-only. It does not run in production builds.

Security

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

• Run it only on code (and dependencies) you trust — same-origin app code can reach the API.
• 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.
• In shared / CI / locked-down setups, set ANNOTASK_MAX_PERMISSION=plan (read-only) or default to cap what a spawned agent can do.

See SECURITY.md for the full model.

Monorepos and MFEs

Annotask is workspace-aware. When the project lives inside a pnpm, npm, Yarn, Bun, or Lerna workspace, server-side scanners can walk sibling packages for:

• component libraries used by adjacent MFEs
• project data sources and bindings
• API schemas
• workspace package metadata and MFE ids

For MFE setups, child apps can point at a root Annotask server with annotask({ mfe, server }) or new AnnotaskWebpackPlugin({ mfe, server }).

Docs

• SETUP.md
• docs/setup.md
• docs/cli.md
• docs/api.md
• docs/skills.md
• docs/component-discovery.md
• docs/architecture.md
• docs/development.md

Development

pnpm install
pnpm build
pnpm dev:vue-vite
pnpm typecheck
pnpm test
pnpm test:e2e

Useful extras:

• pnpm dev:shell for standalone shell UI work
• pnpm test:e2e:stress for the stress-test environment
• pnpm stress-test:up / pnpm stress-test:down for Docker-based stress services

Project structure

• src/plugin/ - Vite integration and transform pipeline
• src/server/ - HTTP API, WebSocket server, persistence, scanners
• src/mcp/ - embedded MCP server
• src/webpack/ - Webpack plugin and loader
• src/shell/ - Vue shell UI served at /__annotask/
• src/cli/ - annotask CLI
• src/schema.ts - canonical task, report, design-spec, and context types
• skills/ - bundled /annotask-init and /annotask-apply skills
• playgrounds/simple/ - single-framework demos
• playgrounds/stress-test/ - multi-MFE, multi-service stress lab