Agentation Documentation

The Two-Session Self-Driving Workflow enables full autonomous design reviews by splitting tasks between two agents: a Critic that identifies issues via a browser and a Fixer that applies code changes.

Prerequisites

• Agentation toolbar installed on the target page.
• MCP server running and connected (toolbar must show "MCP Connected").
• agent-browser skill installed.

Workflow Steps

1. Start the Fixer (Terminal 2) first: This ensures the agent is ready to receive annotations as they are generated.
2. Start the Critic (Terminal 1): This agent will navigate the browser and add annotations.
3. Observe the loop: The Critic adds annotations, which are sent via MCP to the Fixer. The Fixer processes them one by one and resolves them.

### Terminal 1 — The Critic
```bash
claude
> /agentation-self-driving

Terminal 2 — The Fixer

claude
> Watch for agentation annotations and fix each one. Use agentation_watch_annotations
> in a loop. For each annotation: read the target code, make the fix, then call
> agentation_resolve with a summary of what you changed.

The Agentation Hook automatically injects pending UI annotations into Claude's context whenever you send a message. You can install it using one of three methods depending on your needs.

Option 1: One-liner (Recommended)

Add the following configuration to your project's .claude/settings.json file. This method uses a curl command and a Python one-liner to fetch and format annotations directly.

Option 2: Shell Script

For more detailed or custom output, create a shell script (e.g., check-agentation.sh) and reference its path in your .claude/settings.json under the UserPromptSubmit hook.

Option 3: Global Settings

To enable Agentation for all projects, add the configuration to your global Claude settings file at ~/.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']}\n    {a['comment']}\n\")for i,a in enumerate(d['annotations'])],print('=== END ===\n')]\" 2>/dev/null;exit 0"
      }
    ]
  }
}

Standard @ref clicks do not trigger Agentation annotation dialogs because the overlay intercepts pointer events at the coordinate level. To trigger a dialog, you must use a sequence of mouse events at the element's center coordinates.

Workflow:

1. Take an interactive snapshot (agent-browser snapshot -i) to find the element and its CSS selector.
2. Scroll the element into view using eval with scrollIntoView (do not use scrollintoview @ref).
3. Get the bounding box via eval with getBoundingClientRect (do not use get box @ref).
4. Calculate the center coordinates: centerX = x + width/2, centerY = y + height/2.
5. Execute: mouse move <centerX> <centerY>, mouse down left, and mouse up left.
6. Use snapshot -i to find the @ref for the annotation textbox and submit button at the bottom of the output.
7. Fill the text and click the add button using @ref syntax.

# Example workflow for an <h1> element
agent-browser eval "document.querySelector('h1').scrollIntoView({block:'center'})"
agent-browser eval "((r) => r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('h1').getBoundingClientRect())"
# (Parse output, e.g., "383,245,200,40")

agent-browser mouse move 483 265
agent-browser mouse down left
agent-browser mouse up left

# Use refs found in the full snapshot for the dialog
agent-browser fill @<textboxRef> "Your critique here"
agent-browser click @<addRef>