Skip to content

README.md

Latest commit

 

History

History
392 lines (286 loc) · 13.7 KB

README.md

File metadata and controls

392 lines (286 loc) · 13.7 KB
Raw

Agentation

한국어

AI-powered UI feedback system. Annotate webpage elements and send feedback directly to OpenCode sessions via MCP sampling.

Inspired by benjitaylor/agentation — the original visual feedback tool for AI agents. See my proposal for a Chrome Extension version.

💡 Quick Start: Extension Only

No setup required for basic usage!

The Chrome Extension works standalone — just load it and use Copy to Clipboard. Paste into ChatGPT, Claude, or any AI chat.

MCP setup is only needed for Send to AI (direct OpenCode integration).

Feature Extension Only With MCP Setup
Annotate elements ✅ ✅
Copy to Clipboard ✅ ✅
Send to AI (direct) ❌ ✅

Extension-only install:

git clone https://github.com/GutMutCode/agentation.git
# Then: chrome://extensions/ → Developer mode → Load unpacked → packages/extension

Why This Fork?

Original This Project
Type React component Chrome Extension
Usage npm install in your app Works on any website
Output Copy to clipboard Direct to AI via MCP
Integration Manual paste to AI Auto-sends to OpenCode session

Installation

git clone https://github.com/GutMutCode/agentation.git && cd agentation && ./setup.sh

Then load Chrome extension: chrome://extensions/ → Developer mode → Load unpacked → packages/extension

Note: The --recursive flag is only needed if you want to build OpenCode from source (./setup.sh --source). By default, setup.sh downloads pre-built binaries.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│  ┌─────────────┐     WebSocket      ┌─────────────┐     MCP Sampling   │
│  │   Chrome    │ ◄──────────────►  │  Agentation  │ ◄────────────────► │
│  │  Extension  │    localhost:19989 │  MCP Server  │                    │
│  └─────────────┘                    └─────────────┘                    │
│        │                                   │                            │
│        │ User annotations                  │ sampling/createMessage     │
│        ▼                                   ▼                            │
│  ┌─────────────┐                    ┌─────────────┐                    │
│  │  Web Page   │                    │  OpenCode   │ ──► LLM Session    │
│  │  (target)   │                    │   (fork)    │                    │
│  └─────────────┘                    └─────────────┘                    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Prerequisites

  • Node.js 20+
  • pnpm or npm (pnpm recommended: npm install -g pnpm)
  • Chrome browser
  • bun - Only if building OpenCode from source (curl -fsSL https://bun.sh/install | bash)

Note: Windows support is experimental. macOS and Linux are fully supported.

Package Manager: Examples use pnpm, but npm works too. Replace pnpm with npm in commands.

Setup Options

./setup.sh              # Download pre-built binary (default)
./setup.sh --source     # Build OpenCode from source (requires bun)
./setup.sh --force      # Re-download/rebuild even if already installed

Updating

Agentation auto-updates on every startup. Both the agentation code and OpenCode binary are automatically checked and updated.

For existing users (installed before auto-update feature):

cd agentation
git pull
./setup.sh --force      # Regenerate wrapper script with auto-update

Manual update (if needed):

./update.sh             # Check and update now
./update.sh --force     # Force re-download even if up-to-date

Manual Setup

Click to expand manual setup instructions

1. Clone

# For pre-built binary (recommended)
git clone https://github.com/GutMutCode/agentation.git
cd agentation

# For building from source (requires bun)
git clone --recursive https://github.com/GutMutCode/agentation.git
cd agentation

2. Build Agentation

pnpm install
pnpm build

3. Install OpenCode Fork

Option A: Download pre-built binary

Download from OpenCode Fork Releases:

Platform File
macOS Apple Silicon opencode-darwin-arm64.tar.gz
Linux x64 opencode-linux-x64.tar.gz
Linux ARM64 opencode-linux-arm64.tar.gz
Windows x64 opencode-windows-x64.zip 
# Example for macOS Apple Silicon
tar -xzf opencode-darwin-arm64.tar.gz
mv opencode-darwin-arm64 external/opencode/packages/opencode/dist/

# Example for Windows (PowerShell)
Expand-Archive -Path opencode-windows-x64.zip -DestinationPath external/opencode/packages/opencode/dist/

Note: macOS Intel users must build from source (Option B).

Option B: Build from source

cd external/opencode/packages/opencode && bun run build && cd ../../../..

4. Configure Agentation

Create ~/.config/opencode/agentation.json:

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["node", "AGENTATION_PATH/packages/mcp-server/dist/cli.js"]
    }
  },
  "sampling": {
    "agentation": {
      "mode": "auto",
      "maxTokens": 4096
    }
  }
}

Replace AGENTATION_PATH with your actual path:

pwd  # Example output: /Users/yourname/agentation

Note: This config is separate from opencode.json. When running agentation, it will be merged with your existing OpenCode settings (plugins, providers, etc.).

Sampling modes:

Mode Behavior
auto Auto-approve all requests (default)
prompt Ask for approval each time
deny Block all requests

Security Note: If you want manual approval for each AI request, change "mode": "auto" to "mode": "prompt". This shows an Allow/Deny dialog before processing each feedback.

5. Load Chrome Extension

  1. Open chrome://extensions/
  2. Enable Developer mode (top right toggle)
  3. Click Load unpacked
  4. Select packages/extension folder

Start

agentation

Note: If agentation is not found, add ~/.local/bin to your PATH (setup.sh shows instructions).

Usage

Important: Agentation must be running before using the extension.

  1. Start Agentation
  2. Open any webpage in Chrome
  3. Find Agentation toolbar (floating button, bottom-right corner)
  4. Enable annotation mode (click the toggle icon)
  5. Click any element to add feedback annotation
  6. Enter your feedback in the popup
  7. Click "AI에게 지시하기" (Send to AI)
  8. In OpenCode TUI: Approve the sampling request (Allow/Deny dialog)
  9. Continue conversation in the OpenCode session

Design Terms

When annotating elements, you can select design terms to communicate your design intent more precisely.

How to Use

  1. Click on an element to open the annotation popup
  2. Click "Choose Design Style" button
  3. Browse categories: Layout, Interaction, Feedback, Visual, Animation, Concept
  4. Hover over a term to see a live preview demo
  5. Click to select (multiple selections allowed)
  6. Selected terms appear as chips below the button
  7. Send feedback — design terms are included automatically

Available Terms (40 total)

Category Examples
Layout GNB, Sticky Header, Hero Section, Card Grid, Masonry
Interaction Hover Effect, Drag & Drop, Infinite Scroll, Pull to Refresh
Feedback Toast, Skeleton Loading, Progress Bar, Empty State
Visual Glassmorphism, Neumorphism, Gradient, Blur Effect
Animation Fade, Slide, Bounce, Morph, Parallax
Concept Dark Mode, Responsive, Accessibility, Micro-interaction

Example Output

When you select design terms, they appear in the AI prompt:

**Design References:**

- Glassmorphism - Frosted glass effect (blur + transparency)
- Skeleton Screen - Loading placeholder UI

**Feedback:**
Make this card look more modern

Troubleshooting

WebSocket not connected

  • Check if OpenCode is running
  • Check if agentation MCP server is loaded: Press Ctrl+M in OpenCode TUI

Sampling request not appearing

  • Verify sampling config in opencode.json
  • Check mode is not deny

Extension not showing toolbar

  • Refresh the webpage
  • Check extension is enabled in chrome://extensions/

Multiple browser tabs

Using Agentation on multiple browser tabs simultaneously is fully supported. Each tab maintains its own connection, and feedback is routed back to the correct tab.

Running multiple OpenCode instances

Only one Agentation session can run at a time (port 19989 is shared). If you try to start a second instance, it will fail to bind to the port. Close the first session before starting another.

Packages

Package Description
packages/extension Chrome extension for UI annotation
packages/mcp-server MCP server with WebSocket + sampling
packages/shared Shared types
external/opencode OpenCode fork (submodule)

Uninstall

./uninstall.sh              # Remove binaries and build artifacts
./uninstall.sh --keep-project  # Only remove wrapper scripts

Note: This removes agentation.json only. Your opencode.json settings are untouched.

Then manually remove Chrome extension: chrome://extensions/ → Find Agentation → Remove

Recommended: Use with Playwriter

For the best experience, use Agentation together with Playwriter — a browser automation MCP that controls your existing Chrome.

Tool Role
Agentation Annotate UI elements → Send feedback to AI
Playwriter AI controls browser → Test, verify, interact

Why Playwriter?

Feature Playwright MCP Playwriter
Browser Spawns new Chrome Uses your Chrome
Login state Fresh (logged out) Already logged in
Extensions None Your existing ones
Bot detection Always detected Can bypass
Context usage Screenshots (100KB+) A11y snapshots (5-20KB)

Setup

  1. Install Playwriter Chrome Extension
  2. Click extension icon on a tab (turns green when connected)
  3. Add to ~/.config/opencode/agentation.json:
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["node", "AGENTATION_PATH/packages/mcp-server/dist/cli.js"]
    },
    "playwriter": {
      "type": "local",
      "command": ["npx", "-y", "playwriter@latest"],
      "environment": {
        "PLAYWRITER_AUTO_ENABLE": "1"
      }
    }
  },
  "sampling": {
    "agentation": {
      "mode": "auto",
      "maxTokens": 4096
    }
  }
}

Note: PLAYWRITER_AUTO_ENABLE=1 auto-creates a tab when needed (no manual extension click required).

Workflow Example

1. Browse website → spot UI issue
2. Use Agentation to annotate the problem
3. Click "Send to AI" → AI receives visual feedback
4. AI uses Playwriter to interact with the page and fix/verify

Development

pnpm dev        # Watch mode
pnpm typecheck  # Type check

Acknowledgments

License

MIT — See LICENSE

This project is an independent implementation inspired by benjitaylor/agentation. No code was copied from the original project.