> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> H Platform has three products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). The `holo` CLI (`pip install "hai-agents[cli]"`) runs Agents API agents from a terminal, drives the user's own desktop with `-a h/holo-desktop`, and serves coding agents through `holo mcp`.
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `holo`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Integrate with coding agents

> Let Claude Code, Cursor, Codex, and other coding agents run H agents through the local holo mcp bridge, including on this machine, and write SDK code with the hai-agents skill.

Two ways to plug H into a coding agent:

| | What the coding agent gets | Set up with |
| - | - | - |
| [Holo MCP bridge](#local-server) | `run_agent` and `list_agents`, over stdio. Runs any agent, including `h/holo-desktop` on this machine | `holo mcp install` |
| [Coding skill](#coding-skill) | Reference docs, so it writes working SDK code | A plugin or skill folder |

For cloud agents with no local install, connect the coding agent to the [MCP server](https://hub.hcompany.ai/agents-api/mcp.md) instead.

## Holo MCP bridge

`holo mcp` is a local MCP server in the [`holo` CLI](https://hub.hcompany.ai/agents-api/cli). The host starts it over stdio and calls it to run any agent the way `holo run` does, including `h/holo-desktop` on this machine.

### Install into a host

Sign in first. Hosts start `holo mcp` in the background, so they cannot open a browser sign-in.

```bash theme={"system"}
holo login
holo mcp install list      # supported hosts, and which are detected
holo mcp install cursor    # one host
holo mcp install           # every detected host
```

Common host IDs: `claude-code`, `claude-desktop`, `codex`, `cursor`, `vscode`, `windsurf`. `holo mcp install list` shows the rest.

The entry it adds uses your saved key. Restart the host. For the US region, install with `holo --base-url https://agp.hcompany.ai mcp install <host>`.

Codex stops a tool call after 60 seconds

Set `tool_timeout_sec = 1800` under `[mcp_servers.holo]` in `~/.codex/config.toml`.

For Cursor and other hosts with a config file, the entry is:

```json theme={"system"}
{
  "mcpServers": {
    "holo": {
      "type": "stdio",
      "command": "/absolute/path/to/holo",
      "args": ["mcp"]
    }
  }
}
```

Settings you add by hand:

* Apps launched from the Dock or Start menu do not inherit shell exports, so set environment variables in the host's MCP `env` block.
* For `local` runs on your own model server, add `HAI_AGENT_RUNTIME_BASE_URL` and `HAI_AGENT_RUNTIME_MODEL` there. See [Run the model yourself](https://hub.hcompany.ai/agents-api/cli.md#run-the-model-yourself).
* Claude Code, Codex, and Grok Build drop these settings when you run `holo mcp install` again. Add them back afterwards.

### Tools

```text theme={"system"}
run_agent(task: str, agent: str = <your default>, local: bool = false, model: str = None) -> str
list_agents(search: str = None) -> str
```

`run_agent` starts a session, reports each step to the host, and returns the answer.

* `agent` is a name from `list_agents`, like `h/web-surfer-pro` for the web or `h/holo-desktop` for this machine.
* `local` runs the agent loop on this machine, like `holo --local`.
* `model` replaces the agent's model, like `-o agent.model=...`.

Your [`~/.holo` files](https://hub.hcompany.ai/agents-api/cli#customize-every-run) apply to every run.

The tool call blocks until the task ends

`run_agent` returns when the task completes or hits its [budget](https://hub.hcompany.ai/agents-api/cli.md#run). The server runs one task at a time, so parallel calls wait.

### Write a good task

The agent does not see the host conversation. Each task must say which app, workspace, account, and person, and when it is done:

```text theme={"system"}
# 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 server gives the host this rule.

### Stop a run

Cancelling the tool call in the host cancels the session, but some hosts never send the cancel. For runs on this machine, use the [kill switch or `holo local stop`](https://hub.hcompany.ai/agents-api/cli#stop-a-run). A run the user stopped tells the host not to retry.

### Check it worked

Restart the host, then ask:

```text theme={"system"}
Use run_agent with the h/holo-desktop agent 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 mcp install list`, then `holo mcp install <host-id>` again.
* For Claude Code, run `claude mcp get holo`.
* Run `holo whoami`. The key must come from `~/.config/hai/.env`, not only from your shell.

See also [Troubleshoot](https://hub.hcompany.ai/agents-api/cli.md#troubleshoot) and the worked example [Fix a UI bug with Claude Code](https://hub.hcompany.ai/agents-api/cli/example-ui-qa.md).

## Coding skill

<video controls playsInline src="https://mintcdn.com/hcompany/NKXrpCWEaWVdSeM0/videos/product-availability.mp4?fit=max&auto=format&n=NKXrpCWEaWVdSeM0&q=85&s=bc45e6aa6ccdace16861b5199d021584" />

The /hai-agents skill writes and runs a TypeScript availability check from one prompt

The `hai-agents` skill teaches your coding assistant H's APIs, so it writes working code for sessions, agents, and environments from a plain prompt. One `SKILL.md` works in Claude Code, Cursor, and Hermes. It loads on its own when you mention H sessions or `hk-...` keys.

Coding skill, not agent skill

This skill runs in your coding assistant. Agents API [skills](https://hub.hcompany.ai/agents-api/skills/overview.md) are instructions you attach to an H agent.

Source: [`computer-use-agents-demos/skills/hai-agents`](https://github.com/hcompai/computer-use-agents-demos/tree/main/skills/hai-agents), also published as a Claude Code plugin in the `hai-skills` marketplace.

### Install the skill

**Claude Code**

Add the marketplace first, otherwise `hai-skills` is unknown. In any Claude Code prompt:

```bash theme={"system"}
/plugin marketplace add hcompai/computer-use-agents-demos
/plugin install hai-agents@hai-skills
```

**Cursor**

Cursor 2.4+ reads skills from `.cursor/skills/` in your project:

```bash theme={"system"}
git clone https://github.com/hcompai/computer-use-agents-demos
mkdir -p .cursor/skills
cp -r computer-use-agents-demos/skills/hai-agents .cursor/skills/hai-agents
```

Then run **Developer: Reload Window** from the command palette.

**Hermes**

Hermes reads skills from `~/.hermes/skills/` on startup:

```bash theme={"system"}
git clone https://github.com/hcompai/computer-use-agents-demos
mkdir -p ~/.hermes/skills
cp -r computer-use-agents-demos/skills/hai-agents ~/.hermes/skills/hai-agents
```

Then restart Hermes.

### Build a use case

Describe the workflow. In Claude Code, use the plugin's slash command. In Cursor or Hermes, a plain prompt loads the skill. The video above came from:

```text theme={"system"}
/hai-agents:hai-agents "Generate TypeScript code that navigates to jacquemus.com, finds the France × Nike football jersey, and checks its availability in sizes S and XXL."
```

The result is [`examples/product_availability/src/index.ts`](https://github.com/hcompai/computer-use-agents-demos/blob/main/examples/product_availability/src/index.ts). More recipes are in the [demos repo](https://github.com/hcompai/computer-use-agents-demos).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.