agentyc

agentyc

Deterministic, MCP-first browser automation for coding agents.
No API key needed. No LLM fallback. Just CDP, stdio MCP, live HUD surfaces, and 77 tools.

---

What Is It

agentyc ships a public stdio MCP server for browser automation. It speaks CDP directly — no Playwright, no Puppeteer, no LLM fallback. Every tool is deterministic, every response is compact, and the default path works with zero API keys.

For coding agents that need to read a page, click a button, fill a form, or extract a table — agentyc is the browser backend.

uv tool install agentyc
agentyc                          # Starts the MCP server — that's it

---

How It Compares

agentyc is not a testing framework or an autonomous agent loop. It is a browser MCP: launch it, give your agent 77 tools, let it inspect and interact — deterministically, compactly, without an LLM in the critical path.

---

Quick Start

# 1. Install
uv tool install agentyc

# 2. Run the MCP server
agentyc

# 3. Configure your agent
agentyc init     # writes agentyc-skill.md — point Claude Code/Cursor at it

Add to opencode.json:

{
  "mcp": {
    "agentyc": {
      "type": "local",
      "command": ["uv", "run", "agentyc", "mcp"]
    }
  }
}

From source:

uv venv --python 3.11
source .venv/bin/activate
uv sync --dev

---

Bootstrap Your Agent

agentyc init                      # writes agentyc-skill.md
agentyc init --output .agent.md   # custom path
agentyc init --print              # stdout
agentyc init --force              # overwrite

The skills guide covers: read→ref→act loop, tool-selection rules, since_hash polling, shared-browser reuse with --reuse-local-browser / AGENTYC_REUSE_LOCAL_BROWSER, same-browser versus same-tab safety, frame listing and frame HTML inspection, storage and cookie workflows, precise network waits, network entry inspection and replay, narrow network mocks, per-tab offline/throttling controls, right-click / double-click / drag flows, debug bundles, dynamic-text waits, error recovery, long-page search, multi-tab handoff, extraction routes, auth persistence, parallel agents, headless release-readiness flows (viewport, DOM stability, downloads, trace/log hygiene, PDF export), dialog acknowledgments after auto-handled prompts, JS evaluation, and a fuller quick-reference tool list.

---

Live HUD

When BrowserProfile(demo_mode=True) is enabled, Agentyc injects a high-visibility HUD into the controlled browser page. It shows the current step, a short recent timeline, a DETAILS toggle with sanitized tool/session/argument context, and a REPORT menu that copies sanitized context before opening the repo's bug-report, feature-request, or private security flow.

For local operator visibility outside the browser, agentyc mcp --hud-overlay opens a small transparent desktop HUD window that mirrors the same sanitized activity stream. Agents can also call browser_set_intent to push a short human-readable status label into both HUD surfaces.

---

MCP Surface: 77 Tools

Navigation & State (15 tools)

Interaction (14 tools)

Inspection & Extraction (7 tools)

Frames & Storage (5 tools)

Tabs & Session State (17 tools)

Observability, Network Control & Lifecycle (19 tools)

---

State & Element Targeting

browser_get_state is the primary inspection primitive.

• Stable refs: Elements get e123 refs derived from backend node IDs — survive re-renders.
• since_hash: Poll unchanged pages with changed=false — zero element payload sent.
• In min mode: elements within 2× viewport height get a proximity score boost.
• Unchanged responses: still return url, title, state_hash, current_tab_id, scroll position.
• Shared-browser tabs: tabs stays flat for compatibility, and tab_groups groups tabs by owning agent/runtime by default.
• Screenshots: delivered as MCP image content, not embedded base64. Screenshot format, size, quality, and grayscale are configurable via BrowserSession constructor parameters (see LLM Screenshot Optimization).

Best practice: Start with mode="min", use since_hash for follow-up reads, escalate to mode="full" only when compact payload omitted something you need.

---

LLM Screenshot Optimization

Screenshots are the dominant token cost in browser automation. Agentyc automatically resizes and compresses screenshots before delivering them to the LLM, reducing token consumption by about 8.3× on the benchmark fixture with no measured regression in the validated headless flows.

Set these via the BrowserSession constructor:

session = BrowserSession(
    llm_screenshot_size=(480, 270),
    llm_screenshot_format='webp',
    llm_screenshot_quality=85,
)

Benchmark (1280×720 viewport, 3-run median):

All resize/encode operations complete in 30–50ms — negligible compared to CDP capture time.

---

Deterministic Extraction

browser_extract_content is deterministic-only — no LLM fallback, no API key required.

Supported route families:

• output_schema works when the query matches a deterministic route.
• Unrecognized queries return an explicit error with examples — no silent degradation.
• Responses include <extraction_metadata> with route and truncation info.

---

Shared Browser & Parallel Agents

# Start a browser for sharing
agentyc browser --port 9222 --detach
# → ws://127.0.0.1:9222/devtools/browser/...

# Reuse the latest locally launched Agentyc browser automatically
agentyc mcp --reuse-local-browser

# Attach MCP servers to it
agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/...

Parallel automation flow:

1. Primary agent starts a shared browser with agentyc browser --detach
2. Each subagent either spawns agentyc mcp --cdp-url <url> or uses agentyc mcp --reuse-local-browser / AGENTYC_REUSE_LOCAL_BROWSER=1 — Agentyc claims a dedicated collaboration tab in the shared browser profile
3. Subagents can immediately navigate and work in that owned tab; browser_new_tab is only needed when one subagent wants an additional tab of its own
4. Subagents operate independently — refs, network logs, and console logs stay scoped to the owned tab, while auth/cookies/local storage remain shared with the browser profile
5. Primary coordinates and collects results

When multiple runtimes share one browser, Agentyc surfaces a grouped tab view by default so developers can quickly see which agent owns how many tabs.

Collaboration flags:

• --runtime-label — human-readable ownership label
• --runtime-role — primary / assistant
• --shared-browser-mode — tab (default) or window
• --shared-browser-focus-policy — preserve or activate
• --shared-browser-window-bounds — JSON bounds for window mode
• --reuse-local-browser — auto-attach to the latest locally launched Agentyc browser without copying a CDP URL around

Shared-browser reuse means the same browser process and profile. Each runtime still claims its own collaboration tab or window; Chrome does not provide a safe public contract for multiple agents to co-own the exact same tab.

---

Debugging Loops

• browser_export_debug_bundle returns one compact artifact with current state, recent console logs, recent network activity, pending requests, trace summary, optional scoped HTML, and an optional screenshot.
• browser_wait_for_request / browser_wait_for_response are the precise sync primitives for API-heavy apps when generic networkidle is too blunt.
• browser_inspect_network_entry / browser_replay_request turn captured traffic into a concrete request/response artifact with optional bodies, then let agents reissue the same call with narrow overrides.
• browser_add_network_mock / browser_set_network_conditions provide deterministic per-tab stubbing, offline mode, and throttling without switching to a separate test runner abstraction.
• Network waits, inspection, replay, and mocks all build on the same CDP capture/interception layer, so agents can wait for a specific call and then inspect or control the matching traffic immediately.

---

Perceived Speed

agentyc helps separate browser work from agent thinking time:

• MCP log notifications — emit start/completion/error tool-phase messages through MCP logging when the client enables them.
• Tool timing — every result includes _meta.agentyc/browser_duration_ms and agentyc/tool_phase.
• Since-hash polling — unchanged pages avoid resending interactive-element payloads.
• Compact mode — mode="min" surfaces the 30 most actionable elements with proximity scoring.
• Agent narration — agents should narrate intent briefly before a likely pause: "Waiting for validation to finish."

---

Benchmarks

Measured by the release-gate benchmark suite (scripts/benchmark_mcp_runtime.py --preset dogfood --release-gate). The values below are the median of two confirmed headless runs on current HEAD:

Confirmed headless stdio tool-surface median across two runs (scripts/benchmark_mcp_stdio_e2e.py --targets source --minimum-total-calls 100):

• success / accuracy / precision: 1.0 / 1.0 / 1.0
• total duration: 24140.0 ms
• average / p95 tool latency: 43.3 ms / 161.6 ms

---

Python Surface

from agentyc import AgentycServer, BrowserSession, BrowserProfile, Tools

server = AgentycServer(session_timeout_minutes=20)
await server.run()

The primary public story is MCP-first. Direct Python imports are available for embedding or lower-level control.

---

Configuration

BrowserSession config

Environment variables

AGENTYC_HEADLESS, AGENTYC_HUD_OVERLAY, AGENTYC_ALLOWED_DOMAINS, AGENTYC_ACTION_TIMEOUT_S, AGENTYC_PROXY_*, AGENTYC_LOGGING_LEVEL.

Browser defaults

headless=false, downloads_path=~/Downloads/agentyc-mcp, user_data_dir=~/.config/agentyc/profiles/default.

---

Development

source .venv/bin/activate
./scripts/lint.sh     # ruff
./scripts/test.sh     # pytest + pytest-asyncio
uv run pyright        # static types
uv build              # package

---

Docs

• Overview
• Features
• Architecture
• API Reference
• Configuration
• Tech Stack
• Release Gate

---

License

MIT — see LICENSE.