{"id":51936416,"url":"https://github.com/hcompai/holo-desktop-cli","last_synced_at":"2026-07-28T15:01:47.356Z","repository":{"id":371506614,"uuid":"1274106865","full_name":"hcompai/holo-desktop-cli","owner":"hcompai","description":"Desktop agent built on H Company's Holo3 vision-language models","archived":false,"fork":false,"pushed_at":"2026-07-23T09:18:17.000Z","size":1036,"stargazers_count":36,"open_issues_count":2,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T11:07:27.589Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hcompai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-06-19T07:23:20.000Z","updated_at":"2026-07-22T12:01:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hcompai/holo-desktop-cli","commit_stats":null,"previous_names":["hcompai/holo-desktop-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hcompai/holo-desktop-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fholo-desktop-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fholo-desktop-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fholo-desktop-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fholo-desktop-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hcompai","download_url":"https://codeload.github.com/hcompai/holo-desktop-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fholo-desktop-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35996998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"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-07-28T15:01:45.543Z","updated_at":"2026-07-28T15:01:47.306Z","avatar_url":"https://github.com/hcompai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/hcompai/holo-desktop-cli/blob/main/assets/banner-dark.gif?raw=true\" /\u003e\n    \u003cimg src=\"https://github.com/hcompai/holo-desktop-cli/blob/main/assets/banner-light.gif?raw=true\" alt=\"HoloDesktop CLI\" width=\"800\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hcompai/holo-desktop-cli/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/hcompai/holo-desktop-cli/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/hcompai/holo-desktop-cli\"\u003e\u003cimg src=\"https://codecov.io/gh/hcompai/holo-desktop-cli/branch/main/graph/badge.svg\" alt=\"Coverage\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache--2.0-blue.svg\" alt=\"License: Apache-2.0\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nTell your computer what to do. Holo gets it done. `holo-desktop-cli` is the open-source client for [Holo3](https://huggingface.co/Hcompany/Holo3-35B-A3B), H Company's open-weight vision-language model. It launches the agent and fronts it as a CLI, MCP, ACP, and A2A surface. Use the hosted API, or run everything on your own machine for full privacy.\n\n**Docs:** The [HoloDesktop CLI docs](https://hub.hcompany.ai/holo-desktop-cli) cover setup guides, run examples, debugging advice, integration guides, and the full CLI reference.\n\n## What's open, what's closed\n\nHolo is three parts:\n\n- **This repo, `holo-desktop-cli`,** is the [Apache-2.0-licensed](LICENSE) client: the CLI plus the MCP / ACP / A2A surfaces. It launches the agent and drives it over loopback.\n- **The agent** runs inside H Company's `hai-agent-runtime` binary. That binary is closed-source and downloads itself on first run (sha256-verified).\n- **The contract between them** is the open [`hai-agent-api`](https://pypi.org/project/hai-agent-api/) package, so what the client sends is fully inspectable.\n\nPoint it at the hosted [Holo3](https://huggingface.co/Hcompany/Holo3-35B-A3B) models, or at [your own server](docs/self-hosting.md) where nothing leaves your machine.\n\n## Quickstart\n\nInstall Holo with the consumer installer:\n\n```bash\ncurl -fsSL https://install.hcompany.ai/install.sh | bash\nholo login\nholo run \"Open Calculator and compute 2+2\"\n```\n\nOn Windows x86_64:\n\n```powershell\nirm https://install.hcompany.ai/install.ps1 | iex\nholo login\nholo run \"Open Calculator and compute 2+2\"\n```\n\nOn first run:\n\n1. The installer sets up a private Holo toolchain under `~/.holo/` and exposes `holo` on your shell `PATH`.\n2. The `hai-agent-runtime` binary downloads itself to `~/.holo/runtime/` (sha256-verified). Developers can skip this by putting `hai-agent-runtime` (or a wrapper script) on `PATH`.\n3. Your browser opens to sign in at [portal.hcompany.ai](https://portal.hcompany.ai). Skip with `--base-url` for a local model.\n4. macOS only: grant the agent runtime *Accessibility* and *Screen Recording* in *System Settings → Privacy \u0026 Security* when prompted.\n\n## Four ways to use Holo\n\n| Surface | Command | When |\n| ------- | ------- | ---- |\n| CLI     | `holo run \"task\"` | One-shot tasks from your terminal |\n| MCP     | `holo install`, or `holo mcp` in your host's config | Delegate from Claude Code, Cursor, Codex, ... |\n| ACP     | `holo acp` | [ACP](https://agentclientprotocol.com) hosts (Hermes, OpenClaw, Zed, ...) |\n| A2A     | `holo serve` | An [A2A](https://a2a-protocol.org) HTTP server on `127.0.0.1` for your own agents |\n\nSee the [CLI reference](https://hub.hcompany.ai/holo-desktop-cli/reference/cli) or `holo run --help` for all flags.\n\n## Stopping the agent (kill switch)\n\nOnce the agent is driving the screen it's hard to take back control. Holo gives you an out-of-band panic stop: **press `Esc` twice quickly** and the current turn pauses, then cancels.\n\n| Where you're running | What watches for the double-`Esc` |\n| -------------------- | --------------------------------- |\n| `holo run` (interactive terminal) | A listener embedded in the run; armed automatically (first use prompts for macOS Input Monitoring). |\n| `holo mcp` / `holo acp` / `holo serve` (headless) | The always-on `holo guard`, installed by `holo install` and launched by the OS so it has its own permission identity. |\n\nYou can also stop without the keyboard:\n\n```bash\nholo stop          # ask the running turn to pause then cancel (same as double-Esc)\nholo stop --force  # additionally SIGKILL the runtime — instant, but ends the session outright\nholo guard         # run the listener yourself in the foreground (e.g. if you skipped holo install)\n```\n\nGood to know:\n\n- **The stop is step-bounded.** It halts the *next* action; the runtime still finishes the action already in flight. `holo stop --force` is the only instant stop.\n- **`holo stop --force` kills the runtime but leaves a headless host running with a dead backend.** `holo serve` / `holo mcp` / `holo acp` spawn their runtime once at startup and keep pointing at it, so after a force-kill the host process stays up but every later task fails (its requests hit a runtime that no longer exists) until you restart the host. Prefer plain `holo stop` there; reserve `--force` for `holo run` or a wedged runtime.\n- **The guard only inspects `Esc` timing**, never keystroke content — but it does hold Input Monitoring continuously while installed. Disable the embedded listener for a single run with `holo run --no-kill-switch`.\n- **`holo stop --force` reads a pid file and does not yet verify process identity.** A runtime that exited uncleanly can leave a stale `~/.holo/agent-pid-\u003cport\u003e` behind, so a force-kill may target a recycled pid. Robust start-time matching is tracked as follow-up.\n- **Wayland (Linux) has no global key listener.** Use `holo stop` instead, bound to a compositor hotkey.\n\n### How the stop signal works\n\nThe trigger and the lever are decoupled through a single one-line file, `~/.holo/stop`, holding a **wall-clock timestamp**:\n\n- **Writing it (the trigger):** `holo stop`, the `holo run` listener, and `holo guard` all write `time.time()` to that file. They're separate processes, so a wall-clock value is what lets them and the running turn agree on ordering.\n- **Reading it (the lever):** every turn records its own `started_at` and, while running, polls the file ~4×/s. It acts **only if the file's timestamp is newer than its `started_at`** — then it pauses, then cancels at the next action boundary.\n- **Clearing it:** the file is *never deleted*. It's cleared by time — the next turn starts later, so a leftover request is automatically stale and can't kill it. This is also why a `holo stop` fired *before* a run begins is ignored: nothing was running to stop.\n\n`holo stop --force` is the exception to the step-bounded model: it reads the runtime's pid file (`~/.holo/agent-pid-\u003cport\u003e`) and SIGKILLs the process directly, so it doesn't wait for an action boundary.\n\n## Use from Python\n\n`holo_desktop.agent_client` is the same client every CLI surface is built on: it spawns (or attaches to) the `hai-agent-runtime` binary on loopback and drives sessions over the agent API.\n\n```python\nimport asyncio\n\nfrom holo_desktop.agent_client import AgentApiClient, SpawnConfig, ensure_running\nfrom holo_desktop.agent_client.requests import build_session_request\n\n\nasync def main() -\u003e None:\n    daemon = await ensure_running(SpawnConfig(port=18795))\n    try:\n        async with AgentApiClient(daemon.base_url, daemon.token) as client:\n            request = build_session_request(\n                task=\"Tell me how many unread emails I have\", max_steps=None, max_time_s=None\n            )\n            stream = client.stream(await client.create_session(request))\n            async for event in stream.events():\n                print(event.type)\n            print(stream.answer)\n    finally:\n        await daemon.aclose()\n\n\nasyncio.run(main())\n```\n\n`AgentApiClient` also exposes `pause` / `resume` / `cancel` and mid-run `send_message` for interactive embedding.\n\n## Models\n\nHolo defaults to the [H Company Models API](https://hcompany.ai/holo-models-api). Your first `holo run` opens your browser, signs you in at [portal.hcompany.ai](https://portal.hcompany.ai), and saves a key to `~/.holo/.env`. Run `holo login` to do this ahead of time. Holo3-35B is on the free tier; the 122B requires a paid plan.\n\nTo run on your own hardware instead, point `--base-url` at any OpenAI-compatible server. No `holo login` needed, and no screenshots, keystrokes, or app content leave your machine.\n\n```bash\nholo run --base-url http://localhost:8000/v1 \"Open Safari and go to hcompany.ai\"\n```\n\nHardware notes and ready-to-run vLLM and llama.cpp configs are in [docs/self-hosting.md](docs/self-hosting.md).\n\n## Use inside another agent\n\nHolo runs as a sub-agent of Claude Code, Cursor, Codex, and other [MCP](https://modelcontextprotocol.io) / [ACP](https://agentclientprotocol.com) hosts. When your main agent needs to read a screen or click through an app, it delegates to Holo and gets the answer back.\n\nOne command wires Holo into every supported host on your machine:\n\n```bash\nholo install               # everything detected\nholo install cursor        # one host\nholo install list          # see what's available\n```\n\nEach host gets the MCP server in its config, plus a [Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) (where supported) that teaches the parent when to delegate to Holo.\n\n\u003e **Interrupting a running task:** over MCP a Holo task blocks until it finishes — stopping the turn in the host (Cursor, Codex, ...) does not abort the run already executing on your machine; it keeps clicking until it completes, times out, or the host kills the server process. Use [ACP](#acp) if you need a host-driven cancel.\n\n| id              | host                                                            | skill auto-load              |\n| --------------- | --------------------------------------------------------------- | ---------------------------- |\n| `antigravity`   | [Antigravity](https://antigravity.google) (Google)              | —                            |\n| `claude-code`   | [Claude Code](https://docs.anthropic.com/en/docs/claude-code)   | `~/.claude/skills/`          |\n| `claude-desktop`| [Claude Desktop](https://claude.ai/download)                    | —                            |\n| `codex`         | [Codex](https://github.com/openai/codex)                        | `~/.agents/skills/`          |\n| `copilot`       | [GitHub Copilot CLI](https://github.com/github/copilot-cli)     | —                            |\n| `cursor`        | [Cursor](https://cursor.com)                                    | —                            |\n| `grok-build`    | [Grok Build](https://github.com/xai-org/grok-build) (xAI)       | `~/.grok/skills/`            |\n| `hermes`        | [Hermes](https://nousresearch.com)                              | —                            |\n| `nemoclaw`      | NemoClaw (sandbox bridge)                                       | —                            |\n| `openclaw`      | [OpenClaw](https://github.com/openclaw/openclaw)                | `~/.openclaw/skills/`        |\n| `opencode`      | [OpenCode](https://opencode.ai)                                 | `~/.config/opencode/skills/` |\n\n### ACP\n\n\u003e **Beta.** ACP support is still stabilising — interfaces and behaviour may change. `holo acp` prints this notice to stderr on startup.\n\n`holo acp` runs Holo as an [ACP](https://agentclientprotocol.com) sub-agent over stdio. Unlike MCP, ACP hosts can cancel an in-flight task.\n\n**Hermes** ([NousResearch](https://github.com/NousResearch/hermes-agent)):\n\n```python\ndelegate_task(acp_command=\"holo acp\", task=\"Open Authy and grab my AWS 2FA code\")\n```\n\n**OpenClaw** — `~/.openclaw/openclaw.json`:\n\n```json\n{ \"runtimes\": { \"holo\": { \"runtime\": \"acp-standard\", \"command\": \"holo\", \"args\": [\"acp\"] } } }\n```\n\n## Develop\n\nAll dependencies resolve from PyPI (the agent-API wire types come from `hai-agent-api`), so a plain checkout is all you need:\n\n```bash\ngit clone https://github.com/hcompai/holo-desktop-cli \u0026\u0026 cd holo-desktop-cli\nmake setup\nuv run holo run \"Open Calculator and compute 2+2\"\nmake check   # ruff + mypy + pytest\n```\n\nIf you want a global command while developing, install the checkout in editable tool mode:\n\n```bash\nmake install-dev\nholo --help\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## License\n\nThe `holo-desktop-cli` client (this repository) is [Apache-2.0-licensed](LICENSE). The `hai-agent-runtime` binary it downloads and drives is closed-source and distributed under H Company's own terms; the wire contract between the two is the open [`hai-agent-api`](https://pypi.org/project/hai-agent-api/) package.\n\n## Resources\n\n- Models: [Holo3-35B-A3B](https://huggingface.co/Hcompany/Holo3-35B-A3B) · [Holo3-122B-A10B](https://huggingface.co/Hcompany/Holo3-122B-A10B)\n- Docs: [Quickstart](https://hub.hcompany.ai/quickstart) · [Models API](https://hcompany.ai/holo-models-api)\n- [H Company](https://hcompany.ai)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fholo-desktop-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcompai%2Fholo-desktop-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fholo-desktop-cli/lists"}