Skip to Content
Connect an AgentClaude Code

Claude Code

Claude Code is Autonomy’s proof integration for the “default agent” path described in Overview: a standard CLI agent, pre-wired to the Autonomy MCP server and a plugin full of rules, rather than a custom runtime Autonomy maintains. If you already run Claude Code, this is the fastest way to get a screen-off-capable, consent-aware agent talking through a user’s actual accessibility setup instead of guessing at coordinates on screen.

This page covers what the Claude Code plugin gives you, how to install it, and the operating rules Claude follows once connected. If you’re building a different MCP host instead, skip to Bring your own agent — the underlying daemon and tool catalog are identical either way.

What the plugin gives Claude

plugins/autonomy/.claude-plugin/plugin.json declares two things. The Codex plugin at plugins/autonomy/.codex-plugin/plugin.json declares the identical two things through its own manifest shape — same relative skills/ and .mcp.json pointers, just a different wrapper Codex knows how to read:

{
  "name": "autonomy",
  "version": "0.4.0",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

Both resolve to the same plugins/autonomy/skills/ tree and the same plugins/autonomy/.mcp.json — the behavior lives in Autonomy’s plugin layer once, not reinvented per host:

  • Tools — the autonomy MCP server (screen_*, browser_*, speak_text, accessibility_state, consent_*, and the rest of the catalog — see MCP tool catalog), auto-discovered from the plugin’s shared .mcp.json.
  • Rules — the consent-first, accessibility-native behaviors shipped as skills: consent approvals, keyboard/Switch Control navigation, VoiceOver review, low-vision verification, screen-off access, and subagent routing. Claude follows these through its own skill mechanism instead of Autonomy hardcoding them app-side.

Install

Build the app bundle

This provides the signed macOS identity the MCP server launches under, so Accessibility and Screen Recording permissions attach to a stable app rather than a dev binary:

plugins/autonomy/scripts/build-app.sh

Add the plugin marketplace and install

/plugin marketplace add juniorlovestmh/autonomy
/plugin install autonomy@autonomy

A local checkout works too: /plugin marketplace add /path/to/autonomy.

Confirm the connection

Claude Code auto-discovers the plugin’s .mcp.json and skills/ — nothing else to configure by hand. Confirm it:

claude mcp list

You should see autonomy reporting healthy. If it doesn’t, see MCP tools not visible.

Operating rules Claude follows

The plugin doc (plugins/autonomy/docs/claude-code-plugin.md) sets a few rules worth knowing before you start a session:

  • Use the plugin-provided server, not a second one. Don’t add a separate user-scoped autonomy MCP registration when the plugin-scoped server is already available — you’d end up with two daemons and no clear source of truth for consent state.
  • Speech goes through Autonomy’s transport, not raw TTS. For spoken updates, Claude calls voiceover_transport_announce and lets Autonomy’s session policy own voice, rate, cue sounds, fallback, and serialization. It should not call say, osascript, or pick an Apple voice directly — see Consent & safety for why a single owned lane matters when more than one agent might be talking.
  • Different voices per agent are policy, not per-call choice. Voice assignment lives in Autonomy policy keyed by agent identity; Claude identifies itself, Autonomy picks the delivery lane.
  • Agent Mail is a development tool, not an Autonomy dependency. If this repo’s external multi-agent coordination MCP (http://127.0.0.1:8765/mcp/) is active, it’s for coordinating parallel contributors during development — codenames, bead-thread messages, file reservations. It is not part of Autonomy’s runtime, install path, or user-facing speech lane, and it must never be confused with the autonomy MCP server itself.

Mental model: plugin as rulebook, daemon as engine

It helps to keep these as two separate layers. The daemon (a7y-mcp) is the engine — one process, one tool catalog, one consent ledger, indifferent to which agent is calling. The plugin (skills/, plugin.json) is the rulebook Claude specifically reads to decide how to use that engine: check readiness first, prefer semantic actions over pixels, ask before acting on anything in the elevated/critical safety band. Swap Claude for Codex and the engine doesn’t change — only the rulebook’s delivery mechanism does. Codex doesn’t get a rewritten AGENTS.md either — Autonomy’s own plugin docs are explicit that AGENTS.md stays user-owned; instead a Codex session-start hook advertises the identical skills/ tree Claude reads.

If you’re extending Autonomy’s tool surface and want Claude Code to route work to a narrow domain specialist instead of holding all ~170 tool schemas in one context, see the subagent roster shipped under plugins/autonomy/agents/ (autonomy:high-consent-guard, autonomy:voiceover-form-review, and others) — covered in MCP tool catalog.

Pitfalls

  • Don’t hand-edit .mcp.json per project. The path to the app bundle is intentionally fixed (/Applications/autonomy (a7y).app/...) so permission grants survive updates. A relative or per-checkout path will pass locally and then silently lose permissions the next time macOS re-evaluates the app identity.
  • A passing claude mcp list doesn’t mean speech was heard. Delivery evidence (voiceover_direct_requested, tts_fallback_used, user_heard_unverified, …) only proves a channel was used — never report a spoken update as confirmed heard without the user saying so.
  • The plugin only proves the Claude Code + Codex path today. Other hosts listed in this repo’s root *.mcp.json files (Cursor, Windsurf, Gemini) are wired to the unrelated Agent Mail dev tool, not to Autonomy — don’t assume those hosts have a maintained Autonomy plugin yet.
Last updated on
OverviewBring your own agent