{"id":51061832,"url":"https://github.com/bleugreen/axon","last_synced_at":"2026-06-23T03:01:10.573Z","repository":{"id":357693459,"uuid":"1237327515","full_name":"bleugreen/axon","owner":"bleugreen","description":"local macOS accessibility service for agents","archived":false,"fork":false,"pushed_at":"2026-05-23T01:58:52.000Z","size":777,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T03:26:07.056Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bleugreen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T04:46:34.000Z","updated_at":"2026-05-23T01:58:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bleugreen/axon","commit_stats":null,"previous_names":["bleugreen/axon"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bleugreen/axon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Faxon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Faxon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Faxon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Faxon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bleugreen","download_url":"https://codeload.github.com/bleugreen/axon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Faxon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34673437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-23T03:01:08.808Z","updated_at":"2026-06-23T03:01:10.541Z","avatar_url":"https://github.com/bleugreen.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Axon\n\nAxon is a local macOS accessibility service that gives agents a typed, composable path into running apps. It is the connective layer between an agent's intent and an app's UI — semantic locators over coordinates, a flat set of primitive actions, honest results, and recordable sessions that replay as plain text files.\n\nIt runs as a menu bar service, exposes a small JSON-RPC command surface over a Unix socket, and provides an MCP stdio facade for agent clients. The core loop is:\n\n1. look at app state\n2. find an honest target\n3. perform a primitive action\n4. record the call so it can be replayed\n\n## Quick Start\n\n```sh\nbrew install --cask bleugreen/tap/axon\naxon\nclaude mcp add axon -- axon mcp   # or: codex mcp add axon -- axon mcp\n```\n\n`axon` with no arguments launches `Axon.app`, checks the socket, and requests Accessibility permission if it is missing. Approve `Axon.app` in **System Settings → Privacy \u0026 Security → Accessibility**. Once accessibility is trusted, the setup output prints the register-with-MCP commands shown above.\n\n## Why Axon\n\nComputer Use APIs ship as closed-source pixel-pushing services. Axon takes the opposite stance: it is a small, local, open-source utility layer over the macOS Accessibility API. Nothing about it is gated, hosted, or proprietary. AX is public-by-mandate; this is just the thing that makes everything downstream easier.\n\nThe unit of memory is the **`.axn` file** (axon // action) — a saved sequence of past tool calls that an agent or user can replay, edit, and share. Sessions become re-runnable artifacts rather than ephemeral chat history. If an axon is a neuron's path to muscle, a `.axn` is a myelinated one: a route taken often enough that it gets wrapped in insulation and becomes a reflex.\n\nThe four guarantees Axon tries to make:\n\n- **Semantic targets, not coordinates.** Locators match AX role, label, identifier, actions, and ancestry. Point targets are an escape hatch.\n- **Honest results.** Dispatch success and goal success are distinct. A click that posted but produced no UI change does not return \"success.\"\n- **Stable contracts.** The JSON-RPC socket protocol and the `.axn` file format are intended as durable shapes that downstream tools can build on.\n- **Local and inspectable.** The service is a menu bar app you can see, quit, restart, and approve. `.axn` files are human-readable text.\n\n## Documentation\n\n- [Install and Operations](docs/install.md) — build, daemon lifecycle, MCP setup, logs, troubleshooting\n- [Tool Surface](docs/tool-surface.md) — MCP/CLI commands, target shapes, screenshots, action semantics\n- [Action Batches and `.axn` Files](docs/plans.md) — batch schema, history export, replay\n- [Design](docs/design.md) — architecture and long-term direction\n- [Decision Log](docs/decision-log.md) — durable decisions made while shaping the project\n- [Open Issues](docs/issues) — known gaps and active follow-up work\n\n## Current Shape\n\n- signed `Axon.app` menu bar service with bundled `axon` CLI, installed via Homebrew cask\n- compact app snapshots with per-snapshot handles\n- opt-in embedded screenshots returned as MCP image content\n- locator resolution over role, subrole, title, value, description, identifier, actions, and ancestors\n- primitive actions: `click`, `type`, `keyboard`, `scroll`, `drag`, `invoke`\n- coarse `look(since:)` checks backed by observer hints plus fresh app/window signatures\n- `run` and `.axn` files: ordered tool-call sequences, replayable from CLI or MCP\n- `save`: turn recorded session history into an editable `.axn` file\n\nScroll is intentionally AX-native: Axon resolves an offscreen descendant in the requested direction and requests `AXScrollToVisible`. Drag is still an escape-hatch pointer primitive; see [Drag Targeting and Verification](docs/issues/2026-05-12-drag-targeting-and-verification.md) for the next shape.\n\n## Building from Source\n\n```sh\nmake build\nmake test\nmake package-app\n```\n\nSee [Install and Operations](docs/install.md) for signing, notarization, and the development socket workflow.\n\n## Contributing\n\nBug reports, fixture apps, and locator-quality improvements are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the stability contracts to be aware of.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleugreen%2Faxon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbleugreen%2Faxon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleugreen%2Faxon/lists"}