Skip to content
aos

What it is

One CLI over the machine that an agent drives the same way you do. 100 commands across 33 groups: windows, input, screen capture, files, processes, shell commands, packages, network, audio, clipboard and services.

One surface, two callers

Section titled “One surface, two callers”

An agent gets in through the skill — it already has a shell, so it runs the same commands you do, with nothing listening and nothing to start. MCP is the second way in, for agents that want typed tools.

Both resolve the same route and invoke the same Runner. There is no second implementation behind the protocol.

Terminal window
aos window move Chrome --zone=1B     # you, at a terminal
{ "name": "window_move", "arguments": { "app": "Chrome", "zone": "1B" } }

Those two lines are the same work. What you test by hand is what the agent gets, and a bug you reproduce in a shell is the bug the agent hit.

Three platforms, verified

Section titled “Three platforms, verified”

macOS, Windows and Linux — all three tested by a suite that drives the built binaries on real machines, locally, over SSH and through an agentbus node, including a headless Linux server. The macOS window backend is CoreGraphics through cgo; Windows is Win32; Linux is wmctrl and xdotool.

Safety as structure

Section titled “Safety as structure”

The refusals are part of the design, not a disclaimer in a README.

  • Commands that need a screen are refused with a reason instead of failing deep inside a display-server call.
  • file delete will not touch a filesystem root, $HOME, or a system directory.
  • serve binds loopback.
  • Services are namespaced aos.<name>, so removing one cannot reach a system service.
  • Telemetry records how many arguments a command got, never what they were.
Terminal window
$ aos file delete /
aos: refusing to delete /
$ aos file delete $HOME
aos: refusing to delete /Users/muthuishere

The safety model page has the rest.

One verb set that means the same thing everywhere

Section titled “One verb set that means the same thing everywhere”
Terminal window
aos pkg install ripgrep    # brew · winget · scoop · choco · apt · pacman · yay · dnf
aos window move Chrome --zone=1B
aos capture screenshot --app=Chrome --out=/tmp/shot.png

--app=Chrome matches the same window on all three platforms. That took fixing Windows and working around Linux to make true, which is the sort of work a single verb set is for.

Extensible without forking

Section titled “Extensible without forking”

A JSON file in ~/.config/aos/adapters/ adds a group. An executable named aos-<group>-<name> on PATH adds a command. Both become MCP tools on exactly the same terms as a built-in — and neither can shadow one. See extending it.

Where the shape came from

Section titled “Where the shape came from”

The command shape — <group> <command> routes resolved by longest prefix, discoverable help, a machine-readable index, drop-in plugins — is borrowed from the omarchy CLI. The implementation is Go, on three platforms. Everything outside that map — window, mouse, key, exec, file, serve — is new here: the parts an agent needs that a desktop CLI never had.