agentation - AI智能体可视化UI反馈工具，连接人眼与代码的桥梁

agentation by supercent-io/skills-template

5,400 周安装量

88 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/supercent-io/skills-template --skill agentation

AI/机器学习开发用户体验

🇨🇳中文介绍

agentation — 面向 AI 智能体的可视化 UI 反馈桥梁

连接人眼与智能体代码的缺失环节。

无需描述“侧边栏中的蓝色按钮”，您可以直接将 .sidebar > button.primary 交给智能体。它可以直接 grep 这个选择器。

何时使用此技能

用户需要指向 UI 元素并提供反馈，而无需编写选择器
在用户与编码智能体之间运行迭代式 UI/UX 审查循环
构建一个监控循环，让智能体自动修复用户留下的每条批注
捕获 CSS 选择器、边界框和 React 组件树，以实现精确的代码定位
通过 agent-browser + 自动驾驶模式进行自主设计评审
将视觉反馈集成到智能体钩子中，使批注自动出现在智能体上下文中

1. 架构

    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 工具

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

模式	工作原理
复制粘贴	用户批注 → 点击复制 → 将 Markdown 粘贴到智能体聊天中
智能体同步	`endpoint` 属性将工具栏连接到 MCP 服务器 → 智能体使用 `agentation_watch_annotations` 循环

2.1 React 组件 (工具栏)

    npm install agentation -D
    # 或: pnpm add agentation -D  /  yarn add agentation -D  /  bun add agentation -D

要求：React 18+，桌面浏览器，除 React 外零运行时依赖（仅限桌面端 — 不支持移动端）

🔗 设计上本地优先：批注存储在本地，并在连接到 MCP 服务器时自动同步。

离线操作 — 无需服务器即可创建批注

会话连续性 — 页面刷新后同一会话持续存在，无重复

智能体优先 — 由智能体处理解决/驳回操作

2.2 MCP 服务器 — 通用设置 (推荐)

最快的方法 — 自动检测所有已安装的智能体并进行配置（Claude Code、Cursor、Codex、Windsurf 以及 9+ 其他智能体）：

    npx add-mcp "npx -y agentation-mcp server"

    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 — 官方技能 (最简设置)

推荐给 Claude Code 用户 — 自动处理框架检测、包安装和布局集成：

    npx skills add benjitaylor/agentation
    # 然后在 Claude Code 中：
    /agentation

3. React 组件设置

基础 (复制粘贴模式 — 无需服务器)

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

    // 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

    // 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" />
          )}
        </>
      );
    }

属性	类型	默认值	描述
`endpoint`	`string`	—	用于智能体同步模式的 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 服务器设置 — 所有平台

最快的方法 — 通用 (自动检测 9+ 智能体)：

    npx add-mcp "npx -y agentation-mcp server"

add-mcp 自动检测 Claude Code、Cursor、Codex、Windsurf 等，并直接写入正确的配置。

启动服务器 / 验证：

    npx agentation-mcp server          # HTTP :4747 + MCP stdio
    npx agentation-mcp server --port 8080   # 自定义端口
    npx agentation-mcp doctor          # 验证设置

Claude Code (`.claude/`)

最简设置 — 官方 Claude Code 技能 (推荐)：

    npx skills add benjitaylor/agentation
    # 在 Claude Code 中：
    /agentation

通用 MCP 自动设置 (Claude Code + 9+ 智能体)：

    npx add-mcp "npx -y agentation-mcp server"

交互式向导 (仅限 Claude Code)：

    npx agentation-mcp init

选项 A — CLI (推荐)：

    claude mcp add agentation -- npx -y agentation-mcp server

选项 B — 配置文件 (~/.claude/claude_desktop_config.json 用于全局，或 .claude/mcp.json 用于项目级)：

    {
      "mcpServers": {
        "agentation": {
          "command": "npx",
          "args": ["-y", "agentation-mcp", "server"]
        }
      }
    }

交互式向导 (仅限 Claude Code)：

    npx agentation-mcp init

UserPromptSubmit 钩子 — 在每条消息上自动注入待处理的批注。添加到 .claude/settings.json (项目) 或 ~/.claude/settings.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/config.toml：

    # Agentation MCP Server
    [[mcp_servers]]
    name = "agentation"
    command = "npx"
    args = ["-y", "agentation-mcp", "server"]
    
    # 可选：教导 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.
    """

编辑 config.toml 后重启 Codex CLI。

Gemini CLI (`~/.gemini/`)

选项 A — CLI：

    gemini mcp add agentation npx -y agentation-mcp server
    # 或使用显式作用域
    gemini mcp add -s user agentation npx -y agentation-mcp server

选项 B — 配置文件 (~/.gemini/settings.json 用于全局，.gemini/settings.json 用于项目)：

    {
      "mcpServers": {
        "agentation": {
          "command": "npx",
          "args": ["-y", "agentation-mcp", "server"]
        }
      }
    }

AfterAgent 钩子 — 在每次智能体回合后触发批注检查：

    {
      "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/`)

添加到 ~/.config/opencode/opencode.json：

    {
      "mcp": {
        "agentation": {
          "type": "local",
          "command": ["npx", "-y", "agentation-mcp", "server"]
        }
      }
    }

使用环境变量：

    {
      "mcp": {
        "agentation": {
          "type": "local",
          "command": ["npx", "-y", "agentation-mcp", "server"],
          "environment": {
            "AGENTATION_STORE": "sqlite",
            "AGENTATION_EVENT_RETENTION_DAYS": "7"
          }
        }
      }
    }

编辑后重启 OpenCode。MCP 工具 (agentation_*) 将立即可用。

通用 (npx add-mcp)

适用于任何兼容 MCP 的智能体：

    npx add-mcp "npx -y agentation-mcp server"

保存并运行 bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]：

    #!/usr/bin/env bash
    # setup-agentation-mcp.sh — 为所有智能体平台注册 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"]}'
    
    # 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
    
    # 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
    
    # 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
    
    # 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"

5. MCP 工具 (智能体 API)

工具	参数	描述
`agentation_list_sessions`	无	列出所有活动的批注会话
`agentation_get_session`	`sessionId: string`	获取包含所有批注的会话
`agentation_get_pending`	`sessionId: string`	获取会话的待处理批注
`agentation_get_all_pending`	无	获取所有会话中待处理的批注
`agentation_acknowledge`	`annotationId: string`	将批注标记为已确认（智能体正在处理）
`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)`	阻塞直到新批注到达 — 核心监控循环工具

模式 1: 复制粘贴 (最简单，无需服务器)

    1. 用户在浏览器中打开应用
    2. 点击 agentation 工具栏 → 激活
    3. 点击元素 → 添加评论 → 点击复制
    4. 将 Markdown 输出粘贴到智能体聊天中
    5. 智能体接收 CSS 选择器、elementPath、boundingBox
    6. 智能体使用选择器进行 grep/编辑代码

模式 2: MCP 监控循环 (推荐用于迭代式审查)

    智能体: agentation_watch_annotations (最多阻塞 120 秒)
      → 用户在浏览器中添加批注
      → 智能体立即接收批注批次
      → 智能体: agentation_acknowledge(annotationId)
      → 智能体使用 elementPath 作为 grep 目标进行代码更改
      → 智能体: agentation_resolve(annotationId, "将按钮颜色更改为 #3b82f6")
      → 智能体: agentation_watch_annotations (再次循环)

CLAUDE.md / GEMINI.md / Codex developer_instructions — 为自动化监控添加：

    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.

模式 3: 平台特定钩子 (被动注入)

第 4 节中的钩子会自动将待处理批注附加到每条智能体消息 — 无需“监控模式”。适用于所有平台。

模式 4: 自主自动驾驶评审

双智能体设置，用于完全自主的 UI 评审循环：

会话 1 (评审者 — 使用 agent-browser):

    # 启动指向开发服务器的有头浏览器
    agent-browser open http://localhost:3000
    agent-browser snapshot -i
    # 智能体通过 agentation 工具栏导航、点击元素、添加评审意见
    # 批注自动流向 agentation MCP 服务器

会话 2 (修复者 — 监控 MCP):

    agentation_watch_annotations → 接收评审意见 → 确认 → 编辑 → 解决 → 循环

模式 5: Webhook 集成

    <Agentation webhookUrl="https://your-server.com/webhook" />
    # 或环境变量：
    # AGENTATION_WEBHOOK_URL=https://your-server.com/webhook

7. 批注类型 (完整模式)

    type Annotation = {
      // 核心
      id: string;
      x: number;            // 视口宽度的百分比 (0-100)
      y: number;            // 距离文档顶部的像素值
      comment: string;      // 用户的反馈文本
      element: string;      // 标签名称: "button", "div" 等
      elementPath: string;  // CSS 选择器: "body > main > button.cta"  ← grep 目标
      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"  ← 组件 grep 目标
      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";
    };

批注生命周期：

    pending → acknowledged → resolved
                          ↘ dismissed (requires reason)

8. HTTP REST API (端口 4747)

    # 会话
    POST   /sessions                     # 创建会话
    GET    /sessions                     # 列出所有会话
    GET    /sessions/:id                 # 获取会话 + 批注
    
    # 批注
    POST   /sessions/:id/annotations     # 添加批注
    GET    /annotations/:id              # 获取批注
    PATCH  /annotations/:id              # 更新批注
    DELETE /annotations/:id              # 删除批注
    GET    /sessions/:id/pending         # 会话的待处理批注
    GET    /pending                      # 所有会话中的待处理批注
    
    # 事件 (SSE 流)
    GET    /sessions/:id/events          # 会话流
    GET    /events                       # 全局流 (?domain=filter)
    
    # 健康检查
    GET    /health
    GET    /status

变量	描述	默认值
`AGENTATION_STORE`	`memory` 或 `sqlite`	`sqlite`
`AGENTATION_WEBHOOK_URL`	单个 webhook URL	—
`AGENTATION_WEBHOOKS`	逗号分隔的 webhook URL 列表	—
`AGENTATION_EVENT_RETENTION_DAYS`	保留事件的天数	`7`

SQLite 存储：~/.agentation/store.db

10. 编程工具函数

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

11. 平台支持矩阵

平台	配置文件	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"`)	技能系统 (无需钩子)
Cursor / Windsurf	`.cursor/mcp.json` / `.windsurf/mcp.json`	`mcpServers`	—

始终用 NODE_ENV === 'development' 来限制 <Agentation> — 切勿发布到生产环境
对于迭代循环，使用 MCP 监控循环而非复制粘贴 — 消除上下文切换
开始修复时立即调用 agentation_acknowledge — 向用户发出信号
在 agentation_resolve 中包含 summary — 为用户提供可追溯性
在监控循环中优先处理 severity: "blocking" 的批注
使用 elementPath 作为代码中的主要 grep/搜索目标 — 它是一个有效的 CSS 选择器
当代码库是 React 时，使用 reactComponents 字段 — 直接匹配组件名称
为您的平台添加适当的钩子（第 4 节），以实现零摩擦的被动注入
对于自主自动驾驶，在挂载了 agentation 的有头模式下使用 agent-browser

12. jeo 集成 (annotate 关键字)

agentation 集成为 jeo 技能的 VERIFY_UI 阶段。这遵循与在 planui / ExitPlanMode 中运行的 plannotator 相同的模式。annotate 是主要关键字。agentui 作为向后兼容的别名保留。

    plannotator (planui):         agentation (annotate):
    Write plan.md                   在应用 UI 中挂载 <Agentation>
        ↓ blocking                       ↓ blocking
    Run plannotator             agentation_watch_annotations
        ↓                              ↓
    Approve/Feedback in UI        在 UI 中创建批注
        ↓                              ↓
    Confirm approved:true         批注 确认→修复→解决
        ↓                              ↓
    Enter EXECUTE                 下一步或循环

关键字	平台	动作
`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` 相同

与 jeo 一起使用

    # 1. 安装 jeo 时自动注册 agentation
    bash .agent-skills/jeo/scripts/install.sh --with-agentation
    # 或完整安装：
    bash .agent-skills/jeo/scripts/install.sh --all
    
    # 2. 在应用中挂载 agentation 组件
    # app/layout.tsx 或 pages/_app.tsx:
    #   <Agentation endpoint="http://localhost:4747" />
    
    # 3. 启动 MCP 服务器
    npx agentation-mcp server
    
    # 4. 在智能体中输入 annotate 关键字 → 监控循环启动 (agentui 也可作为向后兼容的别名)
    # Claude Code: 直接 MCP 工具调用
    # Codex: 输出 ANNOTATE_READY (或 AGENTUI_READY) → notify 钩子自动轮询
    # Gemini: GEMINI.md HTTP 轮询模式
    # OpenCode: /jeo-annotate 斜杠命令 (或 /jeo-agentui — 已弃用)

与 plannotator 的分离 (阶段守卫)

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 钩子中同时运行。

进入 VERIFY_UI 前的 3 步检查：

服务器状态：GET /health — agentation-mcp 服务器是否正在运行
会话存在：GET /sessions — <Agentation> 组件是否已挂载
待处理批注：GET /pending — 要处理的批注数量

通过后，将 jeo-state.json 中的 phase 设置为 "verify_ui"，并将 agentation.active 设置为 true。

    # 运行 agentation 监控循环集成测试
    bash .agent-skills/agentation/scripts/verify-loop.sh
    
    # 快速测试 (跳过错误情况)
    bash .agent-skills/agentation/scripts/verify-loop.sh --quick

4 步验证：服务器健康 → 批注 CRUD → ACK-RESOLVE 循环 → 错误情况

评估流程 (jeo VERIFY_UI 阶段)

    jeo "<task>"
        │
    [1] PLAN (plannotator 循环)    ← 批准 plan.md
    [2] EXECUTE (team/bmad)
    [3] VERIFY
        ├─ agent-browser 快照
        ├─ 飞行前检查 (服务器 + 会话 + 待处理)
        └─ annotate → VERIFY_UI (agentation 循环)   ← 此阶段 (agentui 也向后兼容)
            ├─ ACK → FIND → FIX → RESOLVE
            ├─ 重新快照 (agent-browser)  ← 修复后重新检查
            └─ 更新 jeo-state.json 中的 agentation 字段
    [4] CLEANUP

有关详细的 jeo 集成：请参阅 jeo SKILL.md 第 3.3.1 节详细工作流

版本: 1.1.0
来源: benjitaylor/agentation (PolyForm Shield 1.0.0)
包: agentation@2.2.1, agentation-mcp@1.2.0
最后更新: 2026-03-05
范围: 用于人机智能体反馈循环的 UI 批注桥梁 — Claude Code、Codex、Gemini CLI、OpenCode

🇺🇸English

agentation — Visual UI Feedback Bridge for AI Agents

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.

When to use this 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

1. Architecture

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:

Mode	How it works
Copy-Paste	Human annotates → clicks Copy → pastes markdown into agent chat
Agent Sync	`endpoint` prop connects toolbar to MCP server → agent uses `agentation_watch_annotations` loop

2. Installation

2.1 React Component (toolbar)

npm install agentation -D
# or: 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

2.2 MCP Server — Universal Setup (Recommended)

Fastest method — Auto-detects all installed agents and configures them (Claude Code, Cursor, Codex, Windsurf, and 9+ more agents):

npx add-mcp "npx -y agentation-mcp server"

Or install manually:

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

2.3 Claude Code — Official Skill (Minimal Setup)

Recommended for Claude Code users — automatically handles framework detection, package installation, and layout integration:

npx skills add benjitaylor/agentation
# then in Claude Code:
/agentation

3. React Component Setup

Basic (Copy-Paste mode — no server needed)

import { Agentation } from 'agentation';

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

Next.js App Router

// 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

// 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

Prop	Type	Default	Description
`endpoint`	`string`	—	MCP server URL for Agent Sync mode
`sessionId`	`string`	—	Pre-existing session ID to join
`onAnnotationAdd`	`(a: Annotation) => void`	—

4. MCP Server Setup — All Platforms

Fastest method — Universal (auto-detects 9+ agents):

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:

npx agentation-mcp server          # HTTP :4747 + MCP stdio
npx agentation-mcp server --port 8080   # custom port
npx agentation-mcp doctor          # verify setup

Claude Code (`.claude/`)

Minimal setup — Official Claude Code Skill (Recommended):

npx skills add benjitaylor/agentation
# In Claude Code:
/agentation

Universal MCP auto-setup (Claude Code + 9+ agents):

npx add-mcp "npx -y agentation-mcp server"

Interactive wizard (Claude Code only):

npx agentation-mcp init

Option A — CLI (recommended):

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

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

Interactive wizard (Claude Code only):

npx agentation-mcp init

UserPromptSubmit hook — auto-inject pending annotations on every message. Add to .claude/settings.json (project) or ~/.claude/settings.json (global):

{
  "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/`)

Add to ~/.codex/config.toml:

# Agentation MCP Server
[[mcp_servers]]
name = "agentation"
command = "npx"
args = ["-y", "agentation-mcp", "server"]

# Optional: teach Codex about watch-loop
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.

Gemini CLI (`~/.gemini/`)

Option A — CLI:

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

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

AfterAgent hook — trigger annotation check after each agent turn:

{
  "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/`)

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}

With environment variables:

{
  "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.

Universal (npx add-mcp)

Works for any MCP-compatible agent:

npx add-mcp "npx -y agentation-mcp server"

Quick-Setup Script

Save and run bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]:

#!/usr/bin/env bash
# setup-agentation-mcp.sh — Register agentation MCP for all agent platforms

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
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
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
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
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"

5. MCP Tools (Agent API)

Tool	Parameters	Description
`agentation_list_sessions`	none	List 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`

6. Workflow Patterns

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

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

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

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:

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.

Pattern 3: Platform-Specific Hook (Passive Injection)

The hook from Section 4 auto-appends pending annotations to every agent message — no "watch mode" needed. Works across all platforms.

Pattern 4: Autonomous Self-Driving Critique

Two-agent setup for fully autonomous UI review cycles:

Session 1 (Critic — usesagent-browser):

# Start headed browser pointing at your dev server
agent-browser open http://localhost:3000
agent-browser snapshot -i
# Agent navigates, clicks elements via agentation toolbar, adds critique
# Annotations flow to agentation MCP server automatically

Session 2 (Fixer — watches MCP):

agentation_watch_annotations → receives critique → acknowledge → edit → resolve → loop

Pattern 5: Webhook Integration

<Agentation webhookUrl="https://your-server.com/webhook" />
# or env var:
# AGENTATION_WEBHOOK_URL=https://your-server.com/webhook

7. Annotation Type (Full Schema)

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)

8. HTTP REST API (port 4747)

# Sessions
POST   /sessions                     # Create session
GET    /sessions                     # List all sessions
GET    /sessions/:id                 # Get session + annotations

# 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

# Events (SSE streaming)
GET    /sessions/:id/events          # Session stream
GET    /events                       # Global stream (?domain=filter)

# Health
GET    /health
GET    /status

9. Environment Variables

Variable	Description	Default
`AGENTATION_STORE`	`memory` or `sqlite`	`sqlite`
`AGENTATION_WEBHOOK_URL`	Single webhook URL	—
`AGENTATION_WEBHOOKS`	Comma-separated webhook URLs	—
`AGENTATION_EVENT_RETENTION_DAYS`

SQLite storage: ~/.agentation/store.db

10. Programmatic Utilities

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

11. Platform Support Matrix

Platform	Config File	MCP Key	Hook
Claude Code	`~/.claude/claude_desktop_config.json`	`mcpServers`	`hooks.UserPromptSubmit` in `settings.json`
Codex CLI	`~/.codex/config.toml`	`[[mcp_servers]]` (TOML)	`developer_instructions` +

Best practices

Always gate <Agentation> with NODE_ENV === 'development' — never ship to production
Use MCP watch-loop over copy-paste for iterative cycles — eliminates context switching
Call agentation_acknowledge immediately when starting a fix — signals human
Include a summary in agentation_resolve — gives human traceability
Process severity: "blocking" annotations first in the watch loop
Use elementPath as the primary grep/search target in code — it's a valid CSS selector
Use reactComponents field when the codebase is React — matches component names directly
Add the appropriate hook for your platform (Section 4) for zero-friction passive injection
For autonomous self-driving, use in headed mode with mounted

12. jeo Integration (annotate keyword)

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.

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

Trigger Keywords

Keyword	Platform	Action
`annotate`	Claude Code	`agentation_watch_annotations` MCP blocking call
`annotate`	Codex	`ANNOTATE_READY` signal → `jeo-notify.py` HTTP polling
`annotate`	Gemini	GEMINI.md instruction: HTTP REST polling pattern
`/jeo-annotate`

Using with jeo

# 1. agentation auto-registered when installing jeo
bash .agent-skills/jeo/scripts/install.sh --with-agentation
# Or full install:
bash .agent-skills/jeo/scripts/install.sh --all

# 2. Mount agentation component in app
# app/layout.tsx or pages/_app.tsx:
#   <Agentation endpoint="http://localhost:4747" />

# 3. Start MCP server
npx agentation-mcp server

# 4. Enter annotate keyword in agent → watch loop starts (agentui also works as backward-compatible alias)
# Claude Code: direct MCP tool call
# Codex: output ANNOTATE_READY (or AGENTUI_READY) → notify hook auto-polls
# Gemini: GEMINI.md HTTP polling pattern
# OpenCode: /jeo-annotate slash command (or /jeo-agentui — deprecated)

Separation from plannotator (Phase Guard)

plannotator and agentation use the same blocking loop pattern but only operate in different phases :

Tool	Allowed phase	Hook 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.

Pre-flight Check

3-step check before entering VERIFY_UI:

Server status : GET /health — whether agentation-mcp server is running
Session exists : GET /sessions — whether <Agentation> component is mounted
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.

Loop Verification Test

# Run agentation watch loop integration test
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

Evaluation Flow (jeo VERIFY_UI phase)

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

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

Weekly Installs

5.4K

Repository

supercent-io/sk…template

GitHub Stars

First Seen

Mar 4, 2026

Security Audits

Gen Agent Trust HubFail SocketWarn SnykWarn

Installed on

gemini-cli5.3K

codex5.3K

opencode5.3K

github-copilot5.2K

cursor5.2K

cline5.2K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

105,000 周安装

agentation - AI智能体可视化UI反馈工具，连接人眼与代码的桥梁

🇨🇳中文介绍

agentation — 面向 AI 智能体的可视化 UI 反馈桥梁

何时使用此技能

1. 架构

相关 Skills

2. 安装

2.1 React 组件 (工具栏)

2.2 MCP 服务器 — 通用设置 (推荐)

2.3 Claude Code — 官方技能 (最简设置)

3. React 组件设置

基础 (复制粘贴模式 — 无需服务器)

Next.js App Router

Next.js Pages Router

完整属性参考

4. MCP 服务器设置 — 所有平台

Claude Code (.claude/)

Codex CLI (~/.codex/)

Gemini CLI (~/.gemini/)

OpenCode (~/.config/opencode/)

通用 (npx add-mcp)

快速设置脚本

5. MCP 工具 (智能体 API)

6. 工作流模式

模式 1: 复制粘贴 (最简单，无需服务器)

模式 2: MCP 监控循环 (推荐用于迭代式审查)

模式 3: 平台特定钩子 (被动注入)

模式 4: 自主自动驾驶评审

模式 5: Webhook 集成

7. 批注类型 (完整模式)

8. HTTP REST API (端口 4747)

9. 环境变量

10. 编程工具函数

11. 平台支持矩阵

最佳实践

12. jeo 集成 (annotate 关键字)

工作原理

触发关键字

与 jeo 一起使用

与 plannotator 的分离 (阶段守卫)

飞行前检查

循环验证测试

评估流程 (jeo VERIFY_UI 阶段)

参考

元数据

🇺🇸English

agentation — Visual UI Feedback Bridge for AI Agents

When to use this skill

1. Architecture

2. Installation

2.1 React Component (toolbar)

2.2 MCP Server — Universal Setup (Recommended)

2.3 Claude Code — Official Skill (Minimal Setup)

3. React Component Setup

Basic (Copy-Paste mode — no server needed)

Next.js App Router

Next.js Pages Router

Full Props Reference

4. MCP Server Setup — All Platforms

Claude Code (.claude/)

Codex CLI (~/.codex/)

Gemini CLI (~/.gemini/)

OpenCode (~/.config/opencode/)

Universal (npx add-mcp)

Quick-Setup Script

5. MCP Tools (Agent API)

6. Workflow Patterns

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

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

Pattern 3: Platform-Specific Hook (Passive Injection)

Pattern 4: Autonomous Self-Driving Critique

Pattern 5: Webhook Integration

7. Annotation Type (Full Schema)

8. HTTP REST API (port 4747)

9. Environment Variables

10. Programmatic Utilities

11. Platform Support Matrix

Best practices

12. jeo Integration (annotate keyword)

How it works

Claude Code (`.claude/`)

Codex CLI (`~/.codex/`)

Gemini CLI (`~/.gemini/`)

OpenCode (`~/.config/opencode/`)

Claude Code (`.claude/`)

Codex CLI (`~/.codex/`)

Gemini CLI (`~/.gemini/`)

OpenCode (`~/.config/opencode/`)