Skip to content
aos

Quickstart

  1. Install.

    Terminal window
    go install github.com/muthuishere/aos/cmd/aos@latest

    Needs Go 1.26+. One static binary, no runtime and no package manager of its own. The macOS window backend is CoreGraphics through cgo, so a Mac build needs CGO_ENABLED=1 — the default when building natively. Linux and Windows are pure Go and cross-compile from anywhere.

    Prefer not to build? Every release also ships prebuilt binaries for macOS, Linux and Windows — the latest release.

  2. Ask the machine what works.

    Terminal window
    $ aos doctor
    ok   registry     97 of 99 commands available on darwin
    ok   telemetry    recording to /Users/you/.local/state/aos/telemetry
    ok   display      available; GUI commands will run
    ok   permissions  accessibility and screen capture granted
    ok   windows      16 windows visible
    ok   screenshot   captured 2895667 bytes
    ok   clipboard    round trip succeeded
    ok   packages     homebrew
    ok   plugins      0 external commands across 37 directories

    doctor does not check whether binaries are on PATH. It round-trips the clipboard, captures a real screenshot and inspects the bytes, asks the window backend for a list, and checks the permissions macOS needs. Anything not ok prints what to run to fix it.

  3. Run something.

    Terminal window
    $ aos system info
    arch        arm64
    cpu         Apple M5 Pro
    host        your-machine.local
    os          macOS
    os_version  26.4
    platform    darwin
    Terminal window
    aos window move Chrome --zone=1B
    aos capture screenshot --app=Chrome --out=/tmp/shot.png
    aos pkg install ripgrep

  4. Hand it to an agent — the skill first.

    Terminal window
    aos skill install

    It writes the agent skill bundled inside the binary to ~/.claude/skills/ and ~/.agents/skills/, so the instructions an agent reads can never describe a different version than the one installed. skill show prints it without installing; skill uninstall removes it.

    That is the whole integration. The agent already has a shell, and now it knows this CLI exists, what the exit codes mean, and which commands need a screen — so it runs aos the way you do. Nothing to start, nothing listening, and it works over SSH into any machine that has the binary.

  5. Or serve it over MCP, if your agent prefers tools.

    Terminal window
    $ aos serve mcp
    aos mcp  http://127.0.0.1:14320/mcp
    token    9c23b0efb0a002fe536a579adfd7cdb1
    Terminal window
    claude mcp add --transport http aos http://127.0.0.1:14320/mcp \
      --header "Authorization: Bearer 9c23b0efb0a002fe536a579adfd7cdb1"

    Every non-hidden, non-blocking command available on this machine becomes one MCP tool, running the identical code path. The token is minted per run and required — see using it from an agent.

Where to go next

Section titled “Where to go next”