Back to Details

agentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

agentation — Visual UI Feedback Bridge for AI Agents

agentation — 面向AI Agent的可视化UI反馈桥梁

The missing link between human eyes and agent code.
Instead of describing "the blue button in the sidebar," you hand the agent 
.sidebar > button.primary
. It can 
grep
for that directly.
连接人眼和Agent代码的缺失环节。
你无需描述“侧边栏里的蓝色按钮”，直接把 
.sidebar > button.primary
交给Agent即可，它可以直接用该选择器搜索代码。

When to use this skill

何时使用该Skill

  • Human needs to point at a UI element and give feedback — without writing selectors
  • Running iterative UI/UX review cycles between human and coding agent
  • Building a watch-loop where agent auto-fixes every annotation a human leaves
  • Capturing CSS selectors, bounding boxes, and React component trees for precise code targeting
  • Autonomous design critique via 
    agent-browser
    + self-driving pattern
  • Integrating visual feedback into agent hooks so annotations auto-appear in agent context
  • 人工需要指向UI元素给出反馈，无需手动编写选择器
  • 人工和代码Agent之间运行迭代式UI/UX评审周期
  • 搭建监听循环，让Agent自动修复人工留下的所有标注
  • 采集CSS选择器、边界框、React组件树，实现精准的代码定位
  • 通过
    agent-browser
    +自驱模式实现自主设计评审
  • 将可视化反馈集成到Agent钩子中，让标注自动出现在Agent上下文中

Scripts (Automated Patterns)

脚本（自动化模式）

Prefer the bundled scripts in this skill before copying long config blocks by hand.
ScriptPatternUsage
scripts/setup-agentation-mcp.sh
MCP registrationRegister 
agentation-mcp
for Claude Code, Codex, Gemini CLI, and OpenCode
scripts/verify-loop.sh
Watch-loop verificationValidate health, annotation CRUD, and ACK → RESOLVE flow before starting watch mode
请优先使用该Skill内置的脚本，不要手动复制冗长的配置块。
脚本模式用法
scripts/setup-agentation-mcp.sh
MCP注册为Claude Code、Codex、Gemini CLI、OpenCode注册
agentation-mcp
scripts/verify-loop.sh
监听循环验证在启动监听模式前验证服务健康度、标注CRUD、ACK → RESOLVE流程是否正常

1. Architecture

1. 架构

agentation (monorepo)
├── agentation          → npm: agentation (React toolbar component)
│   └── src/index.ts   → exports Agentation component + types + utilities
└── agentation-mcp      → npm: agentation-mcp (MCP server + CLI)
    ├── src/cli.ts      → agentation-mcp CLI (init, server, doctor)
    └── src/server/     → HTTP REST API (port 4747) + SSE events + MCP stdio tools
Two modes of operation:
ModeHow it works
Copy-PasteHuman annotates → clicks Copy → pastes markdown into agent chat
Agent Sync
endpoint
prop connects toolbar to MCP server → agent uses 
agentation_watch_annotations
loop
agentation (monorepo)
├── agentation          → npm: agentation (React工具栏组件)
│   └── src/index.ts   → 导出Agentation组件 + 类型定义 + 工具函数
└── agentation-mcp      → npm: agentation-mcp (MCP服务端 + CLI)
    ├── src/cli.ts      → agentation-mcp CLI (init, server, doctor)
    └── src/server/     → HTTP REST API (端口4747) + SSE事件 + MCP stdio工具
两种运行模式：
模式工作原理
复制粘贴人工标注 → 点击复制 → 将markdown粘贴到Agent聊天窗口
Agent同步通过
endpoint
属性将工具栏连接到MCP服务端 → Agent使用
agentation_watch_annotations
循环

2. Installation

2. 安装

2.1 React Component (toolbar)

2.1 React组件（工具栏）

bash
npm install agentation -D
bash
npm install agentation -D

or: pnpm add agentation -D / yarn add agentation -D / bun add agentation -D

或: pnpm add agentation -D / yarn add agentation -D / bun add agentation -D


**Requirements**: React 18+, desktop browser, zero runtime deps beyond React (desktop only — no mobile)

> 🔗 **Local-first by design**: Annotations are stored locally and auto-sync when connected to the MCP server.
> - **Offline operation** — Annotations can be created without a server
> - **Session continuity** — Same session persists after page refresh, no duplicates
> - **Agent-first** — resolve/dismiss is handled by the agent

**依赖要求**: React 18+、桌面端浏览器，除React外无额外运行时依赖（仅支持桌面端，不支持移动端）

> 🔗 **设计上优先本地**: 标注存储在本地，连接到MCP服务端时会自动同步
> - **离线可用** — 无需服务端也可创建标注
> - **会话连续性** — 页面刷新后同一会话仍然保留，无重复标注
> - **Agent优先** — 标注的解决/驳回由Agent处理

2.2 MCP Server — Universal Setup (Recommended)

2.2 MCP服务端 — 通用安装（推荐）

Fastest method — Auto-detects all installed agents and configures them (Claude Code, Cursor, Codex, Windsurf, and 9+ more agents):
bash
npx add-mcp "npx -y agentation-mcp server"
Or install manually:
bash
npm install agentation-mcp -D
npx agentation-mcp server          # HTTP :4747 + MCP stdio
npx agentation-mcp server --port 8080   # custom port
npx agentation-mcp doctor          # verify setup
最快安装方式 — 自动检测所有已安装的Agent并完成配置（Claude Code、Cursor、Codex、Windsurf等9+款Agent）:
bash
npx add-mcp "npx -y agentation-mcp server"
也可手动安装:
bash
npm install agentation-mcp -D
npx agentation-mcp server          # HTTP端口:4747 + MCP stdio
npx agentation-mcp server --port 8080   # 自定义端口
npx agentation-mcp doctor          # 验证安装配置

2.3 Claude Code — Official Skill (Minimal Setup)

2.3 Claude Code — 官方Skill（最简安装）

Recommended for Claude Code users — automatically handles framework detection, package installation, and layout integration:
bash
npx skills add benjitaylor/agentation
推荐Claude Code用户使用 — 自动处理框架检测、包安装和布局集成:
bash
npx skills add benjitaylor/agentation

then in Claude Code:

然后在Claude Code中执行:

/agentation

---
/agentation

---

3. React Component Setup

3. React组件配置

Basic (Copy-Paste mode — no server needed)

基础配置（复制粘贴模式 — 无需服务端）

tsx
import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Agentation />}
    </>
  );
}
tsx
import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Agentation />}
    </>
  );
}

Next.js App Router

Next.js App Router 配置

tsx
// app/layout.tsx
import { Agentation } from 'agentation';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && (
          <Agentation endpoint="http://localhost:4747" />
        )}
      </body>
    </html>
  );
}
tsx
// app/layout.tsx
import { Agentation } from 'agentation';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && (
          <Agentation endpoint="http://localhost:4747" />
        )}
      </body>
    </html>
  );
}

Next.js Pages Router

Next.js Pages Router 配置

tsx
// pages/_app.tsx
import { Agentation } from 'agentation';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === 'development' && (
        <Agentation endpoint="http://localhost:4747" />
      )}
    </>
  );
}
tsx
// pages/_app.tsx
import { Agentation } from 'agentation';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === 'development' && (
        <Agentation endpoint="http://localhost:4747" />
      )}
    </>
  );
}

Full Props Reference

完整属性参考

PropTypeDefaultDescription
endpoint
string
—MCP server URL for Agent Sync mode
sessionId
string
—Pre-existing session ID to join
onAnnotationAdd
(a: Annotation) => void
—Callback when annotation created
onAnnotationDelete
(a: Annotation) => void
—Callback when annotation deleted
onAnnotationUpdate
(a: Annotation) => void
—Callback when annotation edited
onAnnotationsClear
(a: Annotation[]) => void
—Callback when all cleared
onCopy
(markdown: string) => void
—Callback with markdown on copy
onSubmit
(output: string, annotations: Annotation[]) => void
—On "Send Annotations" click
copyToClipboard
boolean
true
Set false to suppress clipboard write
onSessionCreated
(sessionId: string) => void
—Called on new session creation
webhookUrl
string
—Webhook URL to receive annotation events
属性类型默认值描述
endpoint
string
—Agent同步模式下的MCP服务端URL
sessionId
string
—要加入的已有会话ID
onAnnotationAdd
(a: Annotation) => void
—标注创建时的回调
onAnnotationDelete
(a: Annotation) => void
—标注删除时的回调
onAnnotationUpdate
(a: Annotation) => void
—标注编辑时的回调
onAnnotationsClear
(a: Annotation[]) => void
—所有标注清空时的回调
onCopy
(markdown: string) => void
—点击复制时返回markdown内容的回调
onSubmit
(output: string, annotations: Annotation[]) => void
—点击“发送标注”时的回调
copyToClipboard
boolean
true
设为false可禁止写入剪贴板
onSessionCreated
(sessionId: string) => void
—新会话创建时的回调
webhookUrl
string
—接收标注事件的Webhook URL

4. MCP Server Setup — All Platforms

4. MCP服务端配置 — 全平台支持

Fastest method — Universal (auto-detects 9+ agents):
bash
npx add-mcp "npx -y agentation-mcp server"
add-mcp auto-detects Claude Code, Cursor, Codex, Windsurf, and more, writing directly to the correct config.
Start server / verify:
bash
npx agentation-mcp server          # HTTP :4747 + MCP stdio
npx agentation-mcp server --port 8080   # custom port
npx agentation-mcp doctor          # verify setup
最快方式 — 通用配置（自动检测9+款Agent）:
bash
npx add-mcp "npx -y agentation-mcp server"
add-mcp 可自动检测Claude Code、Cursor、Codex、Windsurf等工具，直接写入正确的配置文件。
启动服务/验证配置:
bash
npx agentation-mcp server          # HTTP端口:4747 + MCP stdio
npx agentation-mcp server --port 8080   # 自定义端口
npx agentation-mcp doctor          # 验证安装配置

Claude Code (
.claude/
)

Claude Code (
.claude/
)

Minimal setup — Official Claude Code Skill (Recommended):
bash
npx skills add benjitaylor/agentation
最简配置 — 官方Claude Code Skill（推荐）:
bash
npx skills add benjitaylor/agentation

In Claude Code:

在Claude Code中执行:

/agentation

**Universal MCP auto-setup (Claude Code + 9+ agents):**
```bash
npx add-mcp "npx -y agentation-mcp server"
Interactive wizard (Claude Code only):
bash
npx agentation-mcp init
Option A — CLI (recommended):
bash
claude mcp add agentation -- npx -y agentation-mcp server
Option B — config file (
~/.claude/claude_desktop_config.json
for global, or 
.claude/mcp.json
for project-level):
json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
Interactive wizard (Claude Code only):
bash
npx agentation-mcp init
UserPromptSubmit hook — auto-inject pending annotations on every message. Add to 
.claude/settings.json
(project) or 
~/.claude/settings.json
(global):
json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d['count'];exit(0)if c==0 else[print(f'\\n=== AGENTATION: {c} UI annotations ===\\n'),*[print(f\\\"[{i+1}] {a['element']} ({a['elementPath']})\\n    {a['comment']}\\n\\\")for i,a in enumerate(d['annotations'])],print('=== END ===\\n')]\" 2>/dev/null;exit 0"
      }
    ]
  }
}
/agentation

**通用MCP自动配置（支持Claude Code + 9+款Agent）:**
```bash
npx add-mcp "npx -y agentation-mcp server"
交互式向导（仅支持Claude Code）:
bash
npx agentation-mcp init
选项A — CLI（推荐）:
bash
claude mcp add agentation -- npx -y agentation-mcp server
选项B — 配置文件（全局配置为
~/.claude/claude_desktop_config.json
，项目级配置为
.claude/mcp.json
）:
json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
交互式向导（仅支持Claude Code）:
bash
npx agentation-mcp init
UserPromptSubmit钩子 — 每次发送消息时自动注入待处理标注。添加到
.claude/settings.json
（项目配置）或
~/.claude/settings.json
（全局配置）:
json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d['count'];exit(0)if c==0 else[print(f'\\n=== AGENTATION: {c} UI annotations ===\\n'),*[print(f\\\"[{i+1}] {a['element']} ({a['elementPath']})\\n    {a['comment']}\\n\\\")for i,a in enumerate(d['annotations'])],print('=== END ===\\n')]\" 2>/dev/null;exit 0"
      }
    ]
  }
}

Codex CLI (
~/.codex/
)

Codex CLI (
~/.codex/
)

Add to 
~/.codex/config.toml
:
toml
undefined
添加到
~/.codex/config.toml
:
toml
undefined

Agentation MCP Server

Agentation MCP Server

[[mcp_servers]] name = "agentation" command = "npx" args = ["-y", "agentation-mcp", "server"]
[[mcp_servers]] name = "agentation" command = "npx" args = ["-y", "agentation-mcp", "server"]

Optional: teach Codex about watch-loop

可选: 让Codex了解监听逻辑

developer_instructions = """ When user says "watch mode" or "agentation watch", call agentation_watch_annotations in a loop. For each annotation: acknowledge it, fix the code using the elementPath CSS selector, resolve with summary. """

Restart Codex CLI after editing `config.toml`.

---
developer_instructions = """ 当用户说"watch mode"或"agentation watch"时，循环调用agentation_watch_annotations。 对每个标注：先确认收到，使用elementPath CSS选择器修复代码，返回修复摘要标记为已解决。 """

编辑`config.toml`后重启Codex CLI生效。

---

Gemini CLI (
~/.gemini/
)

Gemini CLI (
~/.gemini/
)

Option A — CLI:
bash
gemini mcp add agentation npx -y agentation-mcp server
选项A — CLI:
bash
gemini mcp add agentation npx -y agentation-mcp server

or with explicit scope

或指定作用域

gemini mcp add -s user agentation npx -y agentation-mcp server

**Option B — config file** (`~/.gemini/settings.json` for global, `.gemini/settings.json` for project):
```json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
AfterAgent hook — trigger annotation check after each agent turn:
json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  },
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d.get('count',0);[print(f'[agentation] {c} pending annotations'),exit(1)]if c>0 else exit(0)\" 2>/dev/null;exit 0",
            "description": "Check for pending agentation annotations"
          }
        ]
      }
    ]
  }
}
gemini mcp add -s user agentation npx -y agentation-mcp server

**选项B — 配置文件**（全局配置为`~/.gemini/settings.json`，项目级配置为`.gemini/settings.json`）:
```json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
AfterAgent钩子 — 每次Agent响应后触发标注检查:
json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  },
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d.get('count',0);[print(f'[agentation] {c} pending annotations'),exit(1)]if c>0 else exit(0)\" 2>/dev/null;exit 0",
            "description": "Check for pending agentation annotations"
          }
        ]
      }
    ]
  }
}

OpenCode (
~/.config/opencode/
)

OpenCode (
~/.config/opencode/
)

Add to 
~/.config/opencode/opencode.json
:
json
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}
With environment variables:
json
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"],
      "environment": {
        "AGENTATION_STORE": "sqlite",
        "AGENTATION_EVENT_RETENTION_DAYS": "7"
      }
    }
  }
}
Restart OpenCode after editing. MCP tools (
agentation_*
) will be available immediately.
添加到
~/.config/opencode/opencode.json
:
json
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}
带环境变量配置:
json
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"],
      "environment": {
        "AGENTATION_STORE": "sqlite",
        "AGENTATION_EVENT_RETENTION_DAYS": "7"
      }
    }
  }
}
编辑后重启OpenCode即可立即使用MCP工具(
agentation_*
)。

Universal (npx add-mcp)

通用安装（npx add-mcp）

Works for any MCP-compatible agent:
bash
npx add-mcp "npx -y agentation-mcp server"
适用于所有兼容MCP的Agent:
bash
npx add-mcp "npx -y agentation-mcp server"

Quick-Setup Script

快速安装脚本

Save and run 
bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]
:
bash
#!/usr/bin/env bash
保存并执行
bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]
:
bash
#!/usr/bin/env bash

setup-agentation-mcp.sh — Register agentation MCP for all agent platforms

setup-agentation-mcp.sh — 为所有Agent平台注册agentation MCP

set -euo pipefail SETUP_CLAUDE=false; SETUP_CODEX=false; SETUP_GEMINI=false; SETUP_OPENCODE=false
while [[ $# -gt 0 ]]; do case "$1" in --claude) SETUP_CLAUDE=true ;; --codex) SETUP_CODEX=true ;; --gemini) SETUP_GEMINI=true ;; --opencode) SETUP_OPENCODE=true ;; --all) SETUP_CLAUDE=true; SETUP_CODEX=true; SETUP_GEMINI=true; SETUP_OPENCODE=true ;; esac shift done [[ "$SETUP_CLAUDE$SETUP_CODEX$SETUP_GEMINI$SETUP_OPENCODE" == "falsefalsefalsefalse" ]] &&
SETUP_CLAUDE=true && SETUP_CODEX=true && SETUP_GEMINI=true && SETUP_OPENCODE=true
MCP_JSON='"agentation": {"command": "npx", "args": ["-y", "agentation-mcp", "server"]}'
set -euo pipefail SETUP_CLAUDE=false; SETUP_CODEX=false; SETUP_GEMINI=false; SETUP_OPENCODE=false
while [[ $# -gt 0 ]]; do case "$1" in --claude) SETUP_CLAUDE=true ;; --codex) SETUP_CODEX=true ;; --gemini) SETUP_GEMINI=true ;; --opencode) SETUP_OPENCODE=true ;; --all) SETUP_CLAUDE=true; SETUP_CODEX=true; SETUP_GEMINI=true; SETUP_OPENCODE=true ;; esac shift done [[ "$SETUP_CLAUDE$SETUP_CODEX$SETUP_GEMINI$SETUP_OPENCODE" == "falsefalsefalsefalse" ]] &&
SETUP_CLAUDE=true && SETUP_CODEX=true && SETUP_GEMINI=true && SETUP_OPENCODE=true
MCP_JSON='"agentation": {"command": "npx", "args": ["-y", "agentation-mcp", "server"]}'

Claude Code

Claude Code

if [[ "$SETUP_CLAUDE" == "true" ]]; then mkdir -p /.claude CFG=/.claude/claude_desktop_config.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Claude Code: $CFG" fi
if [[ "$SETUP_CLAUDE" == "true" ]]; then mkdir -p /.claude CFG=/.claude/claude_desktop_config.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Claude Code: $CFG" fi

Codex CLI

Codex CLI

if [[ "$SETUP_CODEX" == "true" ]]; then mkdir -p /.codex CFG=/.codex/config.toml if ! grep -q "agentation" "$CFG" 2>/dev/null; then printf '\n[[mcp_servers]]\nname = "agentation"\ncommand = "npx"\nargs = ["-y", "agentation-mcp", "server"]\n' >> "$CFG" fi echo "✅ Codex CLI: $CFG" fi
if [[ "$SETUP_CODEX" == "true" ]]; then mkdir -p /.codex CFG=/.codex/config.toml if ! grep -q "agentation" "$CFG" 2>/dev/null; then printf '\n[[mcp_servers]]\nname = "agentation"\ncommand = "npx"\nargs = ["-y", "agentation-mcp", "server"]\n' >> "$CFG" fi echo "✅ Codex CLI: $CFG" fi

Gemini CLI

Gemini CLI

if [[ "$SETUP_GEMINI" == "true" ]]; then mkdir -p /.gemini CFG=/.gemini/settings.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Gemini CLI: $CFG" fi
if [[ "$SETUP_GEMINI" == "true" ]]; then mkdir -p /.gemini CFG=/.gemini/settings.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Gemini CLI: $CFG" fi

OpenCode

OpenCode

if [[ "$SETUP_OPENCODE" == "true" ]]; then mkdir -p /.config/opencode CFG=/.config/opencode/opencode.json ENTRY='"agentation": {"type": "local", "command": ["npx", "-y", "agentation-mcp", "server"]}' if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcp += {$ENTRY}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcp": {$ENTRY}}" > "$CFG" fi echo "✅ OpenCode: $CFG" fi
echo "" echo "Done. Restart your agent(s) and run: npx agentation-mcp server"

---
if [[ "$SETUP_OPENCODE" == "true" ]]; then mkdir -p /.config/opencode CFG=/.config/opencode/opencode.json ENTRY='"agentation": {"type": "local", "command": ["npx", "-y", "agentation-mcp", "server"]}' if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcp += {$ENTRY}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcp": {$ENTRY}}" > "$CFG" fi echo "✅ OpenCode: $CFG" fi
echo "" echo "安装完成。重启你的Agent并执行: npx agentation-mcp server"

---

5. MCP Tools (Agent API)

5. MCP工具（Agent API）

ToolParametersDescription
agentation_list_sessions
noneList all active annotation sessions
agentation_get_session
sessionId: string
Get session with all annotations
agentation_get_pending
sessionId: string
Get pending annotations for a session
agentation_get_all_pending
noneGet pending annotations across ALL sessions
agentation_acknowledge
annotationId: string
Mark annotation as acknowledged (agent is working on it)
agentation_resolve
annotationId: string, summary?: string
Mark as resolved with optional summary
agentation_dismiss
annotationId: string, reason: string
Dismiss with required reason
agentation_reply
annotationId: string, message: string
Add reply to annotation thread
agentation_watch_annotations
sessionId?: string, batchWindowSeconds?: number (default 10, max 60), timeoutSeconds?: number (default 120, max 300)
Block until new annotations arrive — core watch-loop tool
工具参数描述
agentation_list_sessions
无列出所有活跃的标注会话
agentation_get_session
sessionId: string
获取指定会话的所有标注
agentation_get_pending
sessionId: string
获取指定会话的待处理标注
agentation_get_all_pending
无获取所有会话的待处理标注
agentation_acknowledge
annotationId: string
将标注标记为已确认（Agent正在处理）
agentation_resolve
annotationId: string, summary?: string
将标注标记为已解决，可附修复摘要
agentation_dismiss
annotationId: string, reason: string
驳回标注，必须提供理由
agentation_reply
annotationId: string, message: string
在标注线程中添加回复
agentation_watch_annotations
sessionId?: string, batchWindowSeconds?: number (默认10, 最大60), timeoutSeconds?: number (默认120, 最大300)
阻塞直到新标注到达 — 核心监听循环工具

6. Workflow Patterns

6. 工作流模式

Pattern 1: Copy-Paste (Simplest, No Server)

模式1: 复制粘贴（最简单，无需服务端）

1. Human opens app in browser
2. Clicks agentation toolbar → activates
3. Clicks element → adds comment → clicks Copy
4. Pastes markdown output into agent chat
5. Agent receives CSS selectors, elementPath, boundingBox
6. Agent greps/edits code using selector
1. 人工在浏览器中打开应用
2. 点击agentation工具栏激活
3. 点击元素 → 添加评论 → 点击复制
4. 将markdown输出粘贴到Agent聊天窗口
5. Agent收到CSS选择器、elementPath、boundingBox
6. Agent使用选择器搜索/编辑代码

Pattern 2: MCP Watch Loop (Recommended for iterative review)

模式2: MCP监听循环（推荐用于迭代评审）

Agent: agentation_watch_annotations (blocks up to 120s)
  → Human adds annotation in browser
  → Agent receives batch immediately
  → Agent: agentation_acknowledge(annotationId)
  → Agent makes code changes using elementPath as grep target
  → Agent: agentation_resolve(annotationId, "Changed button color to #3b82f6")
  → Agent: agentation_watch_annotations (loops again)
CLAUDE.md / GEMINI.md / Codex developer_instructions — add for automated watch:
markdown
When I say "watch mode" or "agentation watch", call agentation_watch_annotations in a loop.
For each annotation received:
  1. Call agentation_acknowledge(annotationId)
  2. Use elementPath to locate the code: Grep(elementPath) or search codebase for CSS class
  3. Make the minimal change described in the comment
  4. Call agentation_resolve(annotationId, "<brief summary of what was changed>")
Continue watching until I say stop, or until timeout.
Agent: 调用agentation_watch_annotations（最长阻塞120秒）
  → 人工在浏览器中添加标注
  → Agent立即收到批量标注
  → Agent: 调用agentation_acknowledge(annotationId)
  → Agent使用elementPath作为搜索目标修改代码
  → Agent: 调用agentation_resolve(annotationId, "已将按钮颜色改为#3b82f6")
  → Agent: 再次调用agentation_watch_annotations（循环）
CLAUDE.md / GEMINI.md / Codex developer_instructions — 添加配置实现自动监听:
markdown
当我说"watch mode"或"agentation watch"时，循环调用agentation_watch_annotations。
对收到的每个标注:
  1. 调用agentation_acknowledge(annotationId)
  2. 使用elementPath定位代码: Grep(elementPath)或在代码库中搜索CSS类
  3. 按照评论描述做最小改动
  4. 调用agentation_resolve(annotationId, "<修改内容的简短摘要>")
持续监听直到我说停止，或超时。

Pattern 3: Platform-Specific Hook (Passive Injection)

模式3: 平台专属钩子（被动注入）

The hook from Section 4 auto-appends pending annotations to every agent message — no "watch mode" needed. Works across all platforms.
第4节中的钩子会自动将待处理标注追加到每条Agent消息中 — 无需手动开启“监听模式”，全平台可用。

Pattern 4: Autonomous Self-Driving Critique

模式4: 自主自驱式评审

Two-agent setup for fully autonomous UI review cycles:
Session 1 (Critic — uses 
agent-browser
):
bash
undefined
双Agent配置实现完全自主的UI评审周期:
会话1（评审者 — 使用
agent-browser
）:
bash
undefined

Start headed browser pointing at your dev server

启动有头浏览器指向你的开发服务

agent-browser open http://localhost:3000 agent-browser snapshot -i
agent-browser open http://localhost:3000 agent-browser snapshot -i

Agent navigates, clicks elements via agentation toolbar, adds critique

Agent导航页面，通过agentation工具栏点击元素，添加评审意见

Annotations flow to agentation MCP server automatically

标注自动同步到agentation MCP服务端


**Session 2 (Fixer — watches MCP):**
agentation_watch_annotations → receives critique → acknowledge → edit → resolve → loop
undefined

**会话2（修复者 — 监听MCP）:**
agentation_watch_annotations → 收到评审意见 → 确认 → 修改代码 → 标记解决 → 循环
undefined

Pattern 5: Webhook Integration

模式5: Webhook集成

tsx
<Agentation webhookUrl="https://your-server.com/webhook" />
tsx
<Agentation webhookUrl="https://your-server.com/webhook" />

or env var:

或通过环境变量配置:

AGENTATION_WEBHOOK_URL=https://your-server.com/webhook

AGENTATION_WEBHOOK_URL=https://your-server.com/webhook


---

---

7. Annotation Type (Full Schema)

7. 标注类型（完整Schema）

typescript
type Annotation = {
  // Core
  id: string;
  x: number;            // % of viewport width (0-100)
  y: number;            // px from document top
  comment: string;      // User's feedback text
  element: string;      // Tag name: "button", "div", etc.
  elementPath: string;  // CSS selector: "body > main > button.cta"  ← grep target
  timestamp: number;

  // Context
  selectedText?: string;
  boundingBox?: { x: number; y: number; width: number; height: number };
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  reactComponents?: string;  // "App > Dashboard > Button"  ← component grep target
  isMultiSelect?: boolean;
  isFixed?: boolean;

  // Lifecycle (server-synced)
  sessionId?: string;
  url?: string;
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];
  createdAt?: string;
  updatedAt?: string;
  resolvedAt?: string;
  resolvedBy?: "human" | "agent";
};
Annotation lifecycle:
pending → acknowledged → resolved
                      ↘ dismissed (requires reason)
typescript
type Annotation = {
  // 核心字段
  id: string;
  x: number;            // 视口宽度百分比 (0-100)
  y: number;            // 距文档顶部的像素值
  comment: string;      // 用户的反馈文本
  element: string;      // 标签名: "button", "div"等
  elementPath: string;  // CSS选择器: "body > main > button.cta"  ← 搜索代码的目标
  timestamp: number;

  // 上下文字段
  selectedText?: string;
  boundingBox?: { x: number; y: number; width: number; height: number };
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  reactComponents?: string;  // "App > Dashboard > Button"  ← 组件搜索目标
  isMultiSelect?: boolean;
  isFixed?: boolean;

  // 生命周期字段（服务端同步）
  sessionId?: string;
  url?: string;
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];
  createdAt?: string;
  updatedAt?: string;
  resolvedAt?: string;
  resolvedBy?: "human" | "agent";
};
标注生命周期:
待处理 → 已确认 → 已解决
                      ↘ 已驳回（需提供理由）

8. HTTP REST API (port 4747)

8. HTTP REST API（端口4747）

bash
undefined
bash
undefined

Sessions

会话相关

POST /sessions # Create session GET /sessions # List all sessions GET /sessions/:id # Get session + annotations
POST /sessions # 创建会话 GET /sessions # 列出所有会话 GET /sessions/:id # 获取会话+标注

Annotations

标注相关

POST /sessions/:id/annotations # Add annotation GET /annotations/:id # Get annotation PATCH /annotations/:id # Update annotation DELETE /annotations/:id # Delete annotation GET /sessions/:id/pending # Pending for session GET /pending # ALL pending across sessions
POST /sessions/:id/annotations # 添加标注 GET /annotations/:id # 获取标注 PATCH /annotations/:id # 更新标注 DELETE /annotations/:id # 删除标注 GET /sessions/:id/pending # 获取指定会话的待处理标注 GET /pending # 获取所有会话的待处理标注

Events (SSE streaming)

事件（SSE流）

GET /sessions/:id/events # Session stream GET /events # Global stream (?domain=filter)
GET /sessions/:id/events # 会话事件流 GET /events # 全局事件流 (?domain=过滤)

Health

健康检查

GET /health GET /status

---
GET /health GET /status

---

9. Environment Variables

9. 环境变量

VariableDescriptionDefault
AGENTATION_STORE
memory
or 
sqlite
sqlite
AGENTATION_WEBHOOK_URL
Single webhook URL—
AGENTATION_WEBHOOKS
Comma-separated webhook URLs—
AGENTATION_EVENT_RETENTION_DAYS
Days to keep events
7
SQLite storage: 
~/.agentation/store.db
变量描述默认值
AGENTATION_STORE
memory
或
sqlite
sqlite
AGENTATION_WEBHOOK_URL
单个Webhook URL—
AGENTATION_WEBHOOKS
逗号分隔的多个Webhook URL—
AGENTATION_EVENT_RETENTION_DAYS
事件保留天数
7
SQLite存储路径: 
~/.agentation/store.db

10. Programmatic Utilities

10. 编程式工具函数

typescript
import {
  identifyElement, identifyAnimationElement,
  getElementPath, getNearbyText, getElementClasses,
  isInShadowDOM, getShadowHost, closestCrossingShadow,
  loadAnnotations, saveAnnotations, getStorageKey,
  type Annotation, type Session, type ThreadMessage,
} from 'agentation';
typescript
import {
  identifyElement, identifyAnimationElement,
  getElementPath, getNearbyText, getElementClasses,
  isInShadowDOM, getShadowHost, closestCrossingShadow,
  loadAnnotations, saveAnnotations, getStorageKey,
  type Annotation, type Session, type ThreadMessage,
} from 'agentation';

11. Platform Support Matrix

11. 平台支持矩阵

PlatformConfig FileMCP KeyHook
Claude Code
~/.claude/claude_desktop_config.json
mcpServers
hooks.UserPromptSubmit
in 
settings.json
Codex CLI
~/.codex/config.toml
[[mcp_servers]]
(TOML)
developer_instructions
+ 
notify
Gemini CLI
~/.gemini/settings.json
mcpServers
hooks.AfterAgent
in 
settings.json
OpenCode
~/.config/opencode/opencode.json
mcp
(
type: "local"
)		Skills system (no hook needed)
Cursor / Windsurf
.cursor/mcp.json
/ 
.windsurf/mcp.json
mcpServers
—
平台配置文件MCP配置键钩子
Claude Code
~/.claude/claude_desktop_config.json
mcpServers
settings.json
中的
hooks.UserPromptSubmit
Codex CLI
~/.codex/config.toml
[[mcp_servers]]
(TOML格式)
developer_instructions
+ 
notify
Gemini CLI
~/.gemini/settings.json
mcpServers
settings.json
中的
hooks.AfterAgent
OpenCode
~/.config/opencode/opencode.json
mcp
(
type: "local"
)		Skill系统（无需额外钩子）
Cursor / Windsurf
.cursor/mcp.json
/ 
.windsurf/mcp.json
mcpServers
—

Best practices

最佳实践

  1. Always gate 
    <Agentation>
    with 
    NODE_ENV === 'development'
    — never ship to production
  2. Use MCP watch-loop over copy-paste for iterative cycles — eliminates context switching
  3. Call 
    agentation_acknowledge
    immediately when starting a fix — signals human
  4. Include a 
    summary
    in 
    agentation_resolve
    — gives human traceability
  5. Process 
    severity: "blocking"
    annotations first in the watch loop
  6. Use 
    elementPath
    as the primary grep/search target in code — it's a valid CSS selector
  7. Use 
    reactComponents
    field when the codebase is React — matches component names directly
  8. Add the appropriate hook for your platform (Section 4) for zero-friction passive injection
  9. For autonomous self-driving, use 
    agent-browser
    in headed mode with 
    agentation
    mounted
  1. 始终用
    NODE_ENV === 'development'
    包裹
    <Agentation>
    — 永远不要发布到生产环境
  2. 迭代周期优先使用MCP监听循环而非复制粘贴 — 减少上下文切换
  3. 开始修复标注时立即调用
    agentation_acknowledge
    — 通知人工正在处理
  4. 在
    agentation_resolve
    中包含
    summary
    — 让人工可追溯修改内容
  5. 监听循环中优先处理
    severity: "blocking"
    的标注
  6. 优先使用
    elementPath
    作为代码搜索目标 — 它是合法的CSS选择器
  7. React代码库可使用
    reactComponents
    字段 — 直接匹配组件名
  8. 为你的平台添加对应钩子（第4节）实现零成本被动注入
  9. 实现自主自驱评审时，搭配有头模式的
    agent-browser
    和已挂载的
    agentation
    使用

12. jeo Integration (annotate keyword)

12. jeo集成（annotate关键词）

agentation integrates as the VERIFY_UI phase of the jeo skill. This follows the same pattern as plannotator operating in 
planui
/ 
ExitPlanMode
. 
annotate
is the primary keyword. 
agentui
is kept as a backward-compatible alias.
agentation作为jeo Skill的VERIFY_UI阶段集成，和plannotator在
planui
/
ExitPlanMode
下的运行模式一致。 
annotate
是核心触发关键词，
agentui
作为向后兼容的别名保留。

How it works

工作原理

plannotator (planui):         agentation (annotate):
Write plan.md                   Mount <Agentation> in app UI
    ↓ blocking                       ↓ blocking
Run plannotator             agentation_watch_annotations
    ↓                              ↓
Approve/Feedback in UI        Create annotation in UI
    ↓                              ↓
Confirm approved:true          annotation ack→fix→resolve
    ↓                              ↓
Enter EXECUTE                 Next step or loop
plannotator (planui):         agentation (annotate):
编写plan.md                   在应用UI中挂载<Agentation>
    ↓ 阻塞                          ↓ 阻塞
运行plannotator             调用agentation_watch_annotations
    ↓                               ↓
在UI中批准/给出反馈           在UI中创建标注
    ↓                               ↓
确认approved:true             标注确认→修复→解决
    ↓                               ↓
进入执行阶段                进入下一步或循环

Trigger Keywords

触发关键词

KeywordPlatformAction
annotate
Claude Code
agentation_watch_annotations
MCP blocking call
annotate
Codex
ANNOTATE_READY
signal → 
jeo-notify.py
HTTP polling
annotate
GeminiGEMINI.md instruction: HTTP REST polling pattern
/jeo-annotate
OpenCodeopencode.json 
mcp.agentation
+ instructions
agentui
(deprecated)		All platformsSame behavior as above — backward-compatible alias
UI review
All platformsSame as 
annotate
关键词平台动作
annotate
Claude Code阻塞调用
agentation_watch_annotations
MCP工具
annotate
Codex发送
ANNOTATE_READY
信号 → 
jeo-notify.py
HTTP轮询
annotate
Gemini按GEMINI.md指令执行HTTP REST轮询
/jeo-annotate
OpenCode调用opencode.json中
mcp.agentation
+ 指令
agentui
(已废弃)		全平台行为同上 — 向后兼容别名
UI review
全平台行为同
annotate

Using with jeo

配合jeo使用

bash
undefined
bash
undefined

1. agentation auto-registered when installing jeo

1. 安装jeo时会自动注册agentation

bash .agent-skills/jeo/scripts/install.sh --with-agentation
bash .agent-skills/jeo/scripts/install.sh --with-agentation

Or full install:

或完整安装:

bash .agent-skills/jeo/scripts/install.sh --all
bash .agent-skills/jeo/scripts/install.sh --all

2. Mount agentation component in app

2. 在应用中挂载agentation组件

app/layout.tsx or pages/_app.tsx:

app/layout.tsx 或 pages/_app.tsx中添加:

<Agentation endpoint="http://localhost:4747" />

<Agentation endpoint="http://localhost:4747" />

3. Start MCP server

3. 启动MCP服务端

npx agentation-mcp server
npx agentation-mcp server

4. Enter annotate keyword in agent → watch loop starts (agentui also works as backward-compatible alias)

4. 在Agent中输入触发关键词 → 启动监听循环（agentui作为兼容别名也可使用）

Claude Code: direct MCP tool call

Claude Code: 直接调用MCP工具

Codex: output ANNOTATE_READY (or AGENTUI_READY) → notify hook auto-polls

Codex: 输出ANNOTATE_READY（或AGENTUI_READY）→ 通知钩子自动轮询

Gemini: GEMINI.md HTTP polling pattern

Gemini: 按GEMINI.md HTTP轮询模式执行

OpenCode: /jeo-annotate slash command (or /jeo-agentui — deprecated)

OpenCode: 执行/jeo-annotate斜杠命令（或已废弃的/jeo-agentui）

undefined
undefined

Separation from plannotator (Phase Guard)

和plannotator的隔离（阶段保护）

plannotator and agentation use the same blocking loop pattern but only operate in different phases:
ToolAllowed phaseHook Guard
plannotator
plan
only
jeo-state.json
→ 
phase === "plan"
agentation
verify
/ 
verify_ui
only
jeo-state.json
→ 
phase === "verify_ui"
Each platform's hook script checks the 
phase
field in 
jeo-state.json
to prevent execution in the wrong phase. Without this guard, both tools could run simultaneously in Gemini's 
AfterAgent
hook.
plannotator和agentation使用相同的阻塞循环模式，但仅在不同阶段运行:
工具允许阶段钩子保护
plannotator仅
plan
阶段
jeo-state.json
→ 
phase === "plan"
agentation仅
verify
/
verify_ui
阶段
jeo-state.json
→ 
phase === "verify_ui"
各平台的钩子脚本会检查
jeo-state.json
中的
phase
字段，避免在错误阶段执行。如果没有该保护，两个工具可能会在Gemini的
AfterAgent
钩子中同时运行。

Pre-flight Check

预检查

3-step check before entering VERIFY_UI:
  1. Server status: 
    GET /health
    — whether agentation-mcp server is running
  2. Session exists: 
    GET /sessions
    — whether 
    <Agentation>
    component is mounted
  3. Pending annotations: 
    GET /pending
    — number of annotations to process
After passing, set 
phase
in 
jeo-state.json
to 
"verify_ui"
and 
agentation.active
to 
true
.
进入VERIFY_UI阶段前的3步检查:
  1. 服务状态: 
    GET /health
    — 检查agentation-mcp服务是否运行
  2. 会话存在: 
    GET /sessions
    — 检查
    <Agentation>
    组件是否已挂载
  3. 待处理标注: 
    GET /pending
    — 统计待处理的标注数量
检查通过后，将
jeo-state.json
中的
phase
设为
"verify_ui"
，
agentation.active
设为
true
。

Loop Verification Test

循环验证测试

bash
undefined
bash
undefined

Run agentation watch loop integration test

运行agentation监听循环集成测试

bash .agent-skills/agentation/scripts/verify-loop.sh
bash .agent-skills/agentation/scripts/verify-loop.sh

Quick test (skip error cases)

快速测试（跳过错误场景）

bash .agent-skills/agentation/scripts/verify-loop.sh --quick

4-step verification: Server Health → Annotation CRUD → ACK-RESOLVE Cycle → Error Cases
bash .agent-skills/agentation/scripts/verify-loop.sh --quick

4步验证: 服务健康 → 标注CRUD → ACK-RESOLVE流程 → 错误场景处理

Evaluation Flow (jeo VERIFY_UI phase)

评审流程（jeo VERIFY_UI阶段）

jeo "<task>"
    │
[1] PLAN (plannotator loop)    ← approve plan.md
[2] EXECUTE (team/bmad)
[3] VERIFY
    ├─ agent-browser snapshot
    ├─ Pre-flight check (server + session + pending)
    └─ annotate → VERIFY_UI (agentation loop)   ← this phase (agentui also backward-compatible)
        ├─ ACK → FIND → FIX → RESOLVE
        ├─ RE-SNAPSHOT (agent-browser)  ← re-check after fix
        └─ update agentation fields in jeo-state.json
[4] CLEANUP
For detailed jeo integration: see jeo SKILL.md Section 3.3.1 detailed workflow
jeo "<任务>"
    │
[1] 规划阶段 (plannotator循环)    ← 批准plan.md
[2] 执行阶段 (team/bmad)
[3] 验证阶段
    ├─ agent-browser快照
    ├─ 预检查（服务+会话+待处理标注）
    └─ 触发annotate → 进入VERIFY_UI（agentation循环）   ← 当前阶段（兼容agentui别名）
        ├─ 确认 → 定位 → 修复 → 解决
        ├─ 重新快照（agent-browser）  ← 修复后重新检查
        └─ 更新jeo-state.json中的agentation字段
[4] 清理阶段
详细的jeo集成说明: 参考jeo SKILL.md第3.3.1节的详细工作流

References

参考资料

Metadata

元数据

  • Version: 1.1.0
  • Source: benjitaylor/agentation (PolyForm Shield 1.0.0)
  • Packages: 
    agentation@2.2.1
    , 
    agentation-mcp@1.2.0
  • Last updated: 2026-03-05
  • Scope: UI annotation bridge for human-agent feedback loops — Claude Code, Codex, Gemini CLI, OpenCode
  • 版本: 1.1.0
  • 来源: benjitaylor/agentation (PolyForm Shield 1.0.0许可)
  • 包版本: 
    agentation@2.2.1
    , 
    agentation-mcp@1.2.0
  • 最后更新: 2026-03-05
  • 适用范围: 人工-Agent反馈循环的UI标注桥梁 — 支持Claude Code、Codex、Gemini CLI、OpenCode