Use HoloDesktop CLI from an agent host

Coding assistants and agent hosts can delegate desktop work to Holo over MCP. holo mcp is a stdio MCP server with one tool, holo_desktop. Where the host loads skills, holo install also adds a holo-desktop skill: MCP tells the host how to reach Holo, and the skill tells it when to.

Before you start

Run one task from a terminal, and sign in there: hosts launch the CLI non-interactively, so they cannot complete browser sign-in.

holo login
holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"

Running your own model server? Give the host HAI_AGENT_RUNTIME_BASE_URL and HAI_AGENT_RUNTIME_MODEL instead. See Run the model yourself.

Install into a host

holo install list      # supported hosts, and which are detected
holo install cursor    # one host
holo install           # every detected host

Host ID	Host	Skill
`claude-code`	Claude Code	`~/.claude/skills/holo-desktop`
`claude-desktop`	Claude Desktop
`codex`	Codex	`~/.agents/skills/holo-desktop`
`cursor`	Cursor
`grok-build`	Grok Build	`~/.grok/skills/holo-desktop`
`opencode`	OpenCode	`~/.config/opencode/skills/holo-desktop`
`openclaw`	OpenClaw	`~/.openclaw/skills/holo-desktop`
`hermes`	Hermes
`copilot`	GitHub Copilot CLI
`antigravity`	Antigravity

holo install calls the host’s own MCP CLI (Claude Code at user scope, so every project sees it) or merges an entry into its config file, keeping your other keys and saving the original as <file>.bak. It writes the absolute path to holo, so GUI hosts do not depend on your shell PATH. It also registers the double-Esc kill switch to start at login. Restart the host afterwards. For file-backed hosts such as Cursor, the entry looks like this. Add the env block to use your own model server:

{
  "mcpServers": {
    "holo": {
      "type": "stdio",
      "command": "/absolute/path/to/holo",
      "args": ["mcp"],
      "env": {
        "HAI_AGENT_RUNTIME_BASE_URL": "http://localhost:8000/v1",
        "HAI_AGENT_RUNTIME_MODEL": "holo4-35b-a3b"
      }
    }
  }
}

What the host gets

holo_desktop(task: str) -> str

Holo does not see the host conversation, so each call must be self-contained: the app, workspace, account, person, and success condition.

# Good
Open Slack in the Acme workspace and send a DM to Sarah Chen saying "on my way". Return "sent" after the message appears.

# Too vague
Tell Sarah.

The skill teaches the host exactly this: hand off screen-bound work (native apps, system UI, the user’s logged-in browser, 2FA prompts, UI checks), keep the rest, and write a self-contained task. A skill is guidance, not a safety boundary. For actions the user might regret, such as sending, deleting, paying, or changing settings, the host should confirm first or ask Holo to observe and report.

Stop a run

Stopping the turn in the host may not stop the desktop run: some hosts do not send a cancellation. Press Esc twice, or run holo stop from any terminal.

Check it worked

Restart the host, then ask:

Use HoloDesktop CLI to open TextEdit and write a short note saying it is connected. Return "done" when the note is visible.

If the host cannot find or start Holo:

Run holo install list, then holo install <host-id> again.
For Claude Code, check claude mcp get holo.
Check that the host process sees HAI_API_KEY, or your model server settings.
Check ~/.hai/agent-runtime/logs/ for runtime startup errors.

More in Troubleshoot. Worked example: Fix a UI bug with Claude Code.

Get started

Guides

Reference

Examples

Use HoloDesktop CLI from an agent host

Before you start

Install into a host

What the host gets

Stop a run

Check it worked

​Before you start

​Install into a host

​What the host gets

​Stop a run

​Check it worked

Before you start

Install into a host

What the host gets

Stop a run

Check it worked