Skip to content
aosThe hands your agent needs

Quickstart

  1. Install.

    macOS / Linux:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/muthuishere/aos/main/install.sh | sh

    Windows (cmd or PowerShell):

    Terminal window
    curl -fsSL -o install.cmd https://raw.githubusercontent.com/muthuishere/aos/main/install.cmd && install.cmd

    One binary, no root or administrator. See installing for --version, --dir and offline installs with --from.

  2. Check the machine.

    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 real work: it round-trips the clipboard, takes a screenshot, lists windows, and checks permissions. Anything not ok prints what to run to fix it.

    aos doctor with every check ok
    aos doctor

  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
    aos exec capture -- git status

    Every group and command has --help. aos commands lists what this machine can run.

  4. Hand it to an agent.

    You already did. The first aos command wrote the bundled agent skill to ~/.claude/skills/ and ~/.agents/skills/. An agent with a shell now knows the CLI exists, what the exit codes mean, and which commands need a screen. Nothing is listening and nothing needs to start. It also works over SSH into any machine that has the binary.

    To install the skill by hand, or to remove it:

    Terminal window
    aos skill install
    aos skill uninstall

  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           YOUR_TOKEN
    tools           96
    connect         claude mcp add --transport http aos http://127.0.0.1:14320/mcp \
                      --header "Authorization: Bearer YOUR_TOKEN"

    Run the printed connect line. Every command becomes one MCP tool. The token is minted per run and required. See using it from an agent (MCP).

Where to go next

Section titled “Where to go next”