Adding OpenHands coding agent as a skill

Fixes on record

Merged to main. A stamp counts the issues a fix is linked to.

• #32261 feat(skills): add optional openhands skill — closes #477

  merged to main

  files: optional-skills/autonomous-ai-agents/openhands/SKILL.md, scripts/release.py, website/docs/reference/optional-skills-catalog.md, website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md, website/sidebars.ts

  Show the diff

  • optional-skills/autonomous-ai-agents/openhands/SKILL.md

    @@ -0,0 +1,149 @@
    +---
    +name: openhands
    +description: Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
    +version: 0.1.0
    +author: Tim Koepsel (xzessmedia), Hermes Agent
    +license: MIT
    +platforms: [linux, macos]
    +metadata:
    +  hermes:
    +    tags: [Coding-Agent, OpenHands, Model-Agnostic, LiteLLM]
    +    related_skills: [claude-code, codex, opencode, hermes-agent]
    +---
    +
    +# OpenHands CLI
    +
    +Delegate coding tasks to the [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands) via the `terminal` tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.).
    +
    +This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes.
    +
    +## When to Use
    +
    +- User wants a coding task delegated to OpenHands specifically.
    +- User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills `claude-code` and `codex` are tied to one vendor.
    +- Multi-step file edits + shell commands inside a workspace.
    +
    +For Claude-native, prefer `claude-code`. For OpenAI-native, prefer `codex`. For Hermes-native subagents, use `delegate_task`.
    +
    +## Prerequisites
    +
    +1. Install upstream (requires Python 3.12+ and `uv`):
    +
    +   ```
    +   terminal(command="uv tool install openhands --python 3.12")
    +   ```
    +
    +   Verify: `openhands --version` (currently `OpenHands CLI 1.16.0` / `SDK v1.21.0` at time of writing).
    +
    +2. Pick a model and set env vars for `--override-with-envs`:
    +
    +   ```
    +   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # or any LiteLLM slug
    +   export LLM_API_KEY=[redacted:secret-assignment]
    +   export LLM_BASE_URL=https://openrouter.ai/api/v1     # omit for native OpenAI
    +   ```
    +
    +   `LLM_MODEL` uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`). For native Anthropic: `anthropic/claude-sonnet-4-5`. For native OpenAI: `openai/gpt-4o-mini`.
    +
    +3. Suppress the startup banner so JSON output isn't preceded by ASCII art:
    +
    +   ```
    +   export OPENHANDS_SUPPRESS_BANNER=1
    +   ```
    +
    +## How to Run
    +
    +Always invoke through the `terminal` tool. Always pass `--headless --json --override-with-envs --exit-without-confirmation` for automation.
    +
    +### One-shot task
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=[redacted:secret-assignment] LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'",
    +  workdir="/path/to/project",
    +  timeout=600
    +)
    +```
    +
    +### Background for long tasks
    +
    +```
    +terminal(command="<same as above>", workdir="/path/to/project", background=true, notify_on_complete=true)
    +process(action="poll", session_id="<id>")
    +process(action="log", session_id="<id>")
    +```
    +
    +### Resume a previous conversation
    +
    +OpenHands prints `Conversation ID: <32-hex>` and a `Hint: openhands --resume <dashed-uuid>` line at the end of each run. Use the dashed form to resume:
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume <dashed-uuid> -t 'Now fix the bug you found'",
    +  workdir="/path/to/project"
    +)
    +```
    +
    +## Real Flag List
    +
    +Verified against `openhands --help` (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file.
    +
    +| Flag | Effect |
    +|------|--------|
    +| `--headless` | No UI, requires `-t` or `-f`. Auto-approves all actions (no `--llm-approve` in this mode). |
    +| `--json` | JSONL event stream (requires `--headless`). |
    +| `-t TEXT` | Task prompt. |
    +| `-f PATH` | Read task from file. |
    +| `--resume [ID]` | Resume conversation. No ID → list recent. |
    +| `--last` | Resume most recent (with `--resume`). |
    +| `--override-with-envs` | Apply `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` env vars. Without this, OpenHands uses `~/.openhands/settings.json` and ignores the env. |
    +| `--exit-without-confirmation` | Don't show the "are you sure" exit dialog. |
    +| `--always-approve` / `--yolo` | Auto-approve every action (default in `--headless`). |
    +| `--llm-approve` | LLM-based security gate (interactive only — does NOT work in headless). |
    +| `--version` / `-v` | Print version and exit. |
    +
    +**There is no `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` flag.** Model is `LLM_MODEL`. Workspace is the `workdir` you pass to the `terminal` tool. Sandbox / runtime is the `RUNTIME` and `SANDBOX_VOLUMES` env vars.
    +
    +## JSON Event Schema
    +
    +With `--json --headless`, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (`Initializing agent...`, `Agent is working`, `Agent finished`, the final summary box, `Goodbye!`, `Conversation ID:`, `Hint:`). Filter for lines starting with `{`.
    +
    +Top-level `kind` field discriminates events:
    +
    +- `MessageEvent` — user / agent text turn. `source` is `user` or `agent`.
    +- `ActionEvent` — agent picked a tool. Read `tool_name` (`file_editor`, `terminal`, `finish`) and `action.kind` (`FileEditorAction`, `TerminalAction`, `FinishAction`).
    +- `ObservationEvent` — tool result. `observation.is_error` is the success flag. `source` is `environment`.
    +- `FinishAction` inside an `ActionEvent` carries the agent's final message in `action.message`.
    +
    +The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with `{`.
    +
    +## Pitfalls
    +
    +- **LiteLLM warnings on every invocation.** The CLI prints `bedrock-runtime` and `sagemaker-runtime` warnings to stderr because `botocore` isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to `/dev/null` or filter it out before showing the user.
    +- **Banner spam.** Without `OPENHANDS_SUPPRESS_BANNER=1`, every run starts with a multi-line `+--+` ASCII box advertising the SDK. Always export it.
    +- **`--override-with-envs` is mandatory for automation.** Without it, OpenHands ignores `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` and falls back to `~/.openhands/settings.json`. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup.
    +- **Model slug is LiteLLM's, not the provider's.** `openrouter/openai/gpt-4o-mini` works; `openai/gpt-4o-mini` while pointed at OpenRouter does not. `anthropic/claude-sonnet-4-5` (hyphen) is native Anthropic; `openrouter/anthropic/claude-sonnet-4.5` (dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400.
    +- **`pip install openhands-ai` is the wrong package.** That's the legacy V0 SDK. The new CLI is `uv tool install openhands --python 3.12`. There is no maintained conda package.
    +- **Resume ID format is fiddly.** The CLI ends with `Conversation ID: f46573d9cfdb45e492ca189bde40019b` (no dashes) and then a `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b` (with dashes). Use the dashed form.
    +- **Headless ignores `--llm-approve`.** If you pass it, you get an argparse error. Headless mode hardcodes always-approve.
    +- **No Windows support upstream.** The OpenHands docs require WSL on Windows. This skill is gated `[linux, macos]` accordingly.
    +- **`~/.openhands/conversations/<id>/` accumulates.** Each run persists a trajectory. Clean it up if running batches.
    +- **Heavy install (~200 packages).** Use `uv tool install` (isolated venv) to avoid dependency conflicts with the active project.
    +
    +## Verification
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=[redacted:secret-assignment] LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'",
    +  workdir="/tmp",
    +  timeout=120
    +)
    +```
    +
    +If the JSONL stream ends with a `FinishAction` whose `action.message` mentions `OPENHANDS_OK`, the install is working.
    +
    +## Related
    +
    +- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands)
    +- [OpenHands CLI command reference](https://docs.openhands.dev/openhands/usage/cli/command-reference)
    +- Sibling skills: `claude-code` (Anthropic-only), `codex` (OpenAI-only), `opencode` (multi-provider via OpenCode), `hermes-agent` (Hermes subagents via `delegate_task`).

  • scripts/release.py

    @@ -87,6 +87,7 @@
         "[redacted:email]": "jfuenmayor",
         "[email protected]": "Jiahui-Gu",
         "[redacted:email]": "YLChen-007",
    +    "[email protected]": "xzessmedia",
         "[redacted:email]": "AdamPlatin123",
         "[email protected]": "waefrebeorn",
         "[email protected]": "dusterbloom",

  • website/docs/reference/optional-skills-catalog.md

    @@ -33,6 +33,7 @@ hermes skills uninstall <skill-name>
     |-------|-------------|
     | [**blackbox**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. |
     | [**honcho**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshoo... |
    +| [**openhands**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |
     
     ## blockchain
     

  • website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md

    @@ -0,0 +1,167 @@
    +---
    +title: "Openhands — Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)"
    +sidebar_label: "Openhands"
    +description: "Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)"
    +---
    +
    +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
    +
    +# Openhands
    +
    +Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
    +
    +## Skill metadata
    +
    +| | |
    +|---|---|
    +| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/openhands` |
    +| Path | `optional-skills/autonomous-ai-agents/openhands` |
    +| Version | `0.1.0` |
    +| Author | Tim Koepsel (xzessmedia), Hermes Agent |
    +| License | MIT |
    +| Platforms | linux, macos |
    +| Tags | `Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM` |
    +| Related skills | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
    +
    +## Reference: full SKILL.md
    +
    +:::info
    +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
    +:::
    +
    +# OpenHands CLI
    +
    +Delegate coding tasks to the [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands) via the `terminal` tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.).
    +
    +This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes.
    +
    +## When to Use
    +
    +- User wants a coding task delegated to OpenHands specifically.
    +- User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills `claude-code` and `codex` are tied to one vendor.
    +- Multi-step file edits + shell commands inside a workspace.
    +
    +For Claude-native, prefer `claude-code`. For OpenAI-native, prefer `codex`. For Hermes-native subagents, use `delegate_task`.
    +
    +## Prerequisites
    +
    +1. Install upstream (requires Python 3.12+ and `uv`):
    +
    +   ```
    +   terminal(command="uv tool install openhands --python 3.12")
    +   ```
    +
    +   Verify: `openhands --version` (currently `OpenHands CLI 1.16.0` / `SDK v1.21.0` at time of writing).
    +
    +2. Pick a model and set env vars for `--override-with-envs`:
    +
    +   ```
    +   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # or any LiteLLM slug
    +   export LLM_API_KEY=[redacted:secret-assignment]
    +   export LLM_BASE_URL=https://openrouter.ai/api/v1     # omit for native OpenAI
    +   ```
    +
    +   `LLM_MODEL` uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`). For native Anthropic: `anthropic/claude-sonnet-4-5`. For native OpenAI: `openai/gpt-4o-mini`.
    +
    +3. Suppress the startup banner so JSON output isn't preceded by ASCII art:
    +
    +   ```
    +   export OPENHANDS_SUPPRESS_BANNER=1
    +   ```
    +
    +## How to Run
    +
    +Always invoke through the `terminal` tool. Always pass `--headless --json --override-with-envs --exit-without-confirmation` for automation.
    +
    +### One-shot task
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=[redacted:secret-assignment] LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'",
    +  workdir="/path/to/project",
    +  timeout=600
    +)
    +```
    +
    +### Background for long tasks
    +
    +```
    +terminal(command="<same as above>", workdir="/path/to/project", background=true, notify_on_complete=true)
    +process(action="poll", session_id="<id>")
    +process(action="log", session_id="<id>")
    +```
    +
    +### Resume a previous conversation
    +
    +OpenHands prints `Conversation ID: <32-hex>` and a `Hint: openhands --resume <dashed-uuid>` line at the end of each run. Use the dashed form to resume:
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume <dashed-uuid> -t 'Now fix the bug you found'",
    +  workdir="/path/to/project"
    +)
    +```
    +
    +## Real Flag List
    +
    +Verified against `openhands --help` (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file.
    +
    +| Flag | Effect |
    +|------|--------|
    +| `--headless` | No UI, requires `-t` or `-f`. Auto-approves all actions (no `--llm-approve` in this mode). |
    +| `--json` | JSONL event stream (requires `--headless`). |
    +| `-t TEXT` | Task prompt. |
    +| `-f PATH` | Read task from file. |
    +| `--resume [ID]` | Resume conversation. No ID → list recent. |
    +| `--last` | Resume most recent (with `--resume`). |
    +| `--override-with-envs` | Apply `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` env vars. Without this, OpenHands uses `~/.openhands/settings.json` and ignores the env. |
    +| `--exit-without-confirmation` | Don't show the "are you sure" exit dialog. |
    +| `--always-approve` / `--yolo` | Auto-approve every action (default in `--headless`). |
    +| `--llm-approve` | LLM-based security gate (interactive only — does NOT work in headless). |
    +| `--version` / `-v` | Print version and exit. |
    +
    +**There is no `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` flag.** Model is `LLM_MODEL`. Workspace is the `workdir` you pass to the `terminal` tool. Sandbox / runtime is the `RUNTIME` and `SANDBOX_VOLUMES` env vars.
    +
    +## JSON Event Schema
    +
    +With `--json --headless`, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (`Initializing agent...`, `Agent is working`, `Agent finished`, the final summary box, `Goodbye!`, `Conversation ID:`, `Hint:`). Filter for lines starting with `{`.
    +
    +Top-level `kind` field discriminates events:
    +
    +- `MessageEvent` — user / agent text turn. `source` is `user` or `agent`.
    +- `ActionEvent` — agent picked a tool. Read `tool_name` (`file_editor`, `terminal`, `finish`) and `action.kind` (`FileEditorAction`, `TerminalAction`, `FinishAction`).
    +- `ObservationEvent` — tool result. `observation.is_error` is the success flag. `source` is `environment`.
    +- `FinishAction` inside an `ActionEvent` carries the agent's final message in `action.message`.
    +
    +The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with `{`.
    +
    +## Pitfalls
    +
    +- **LiteLLM warnings on every invocation.** The CLI prints `bedrock-runtime` and `sagemaker-runtime` warnings to stderr because `botocore` isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to `/dev/null` or filter it out before showing the user.
    +- **Banner spam.** Without `OPENHANDS_SUPPRESS_BANNER=1`, every run starts with a multi-line `+--+` ASCII box advertising the SDK. Always export it.
    +- **`--override-with-envs` is mandatory for automation.** Without it, OpenHands ignores `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` and falls back to `~/.openhands/settings.json`. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup.
    +- **Model slug is LiteLLM's, not the provider's.** `openrouter/openai/gpt-4o-mini` works; `openai/gpt-4o-mini` while pointed at OpenRouter does not. `anthropic/claude-sonnet-4-5` (hyphen) is native Anthropic; `openrouter/anthropic/claude-sonnet-4.5` (dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400.
    +- **`pip install openhands-ai` is the wrong package.** That's the legacy V0 SDK. The new CLI is `uv tool install openhands --python 3.12`. There is no maintained conda package.
    +- **Resume ID format is fiddly.** The CLI ends with `Conversation ID: f46573d9cfdb45e492ca189bde40019b` (no dashes) and then a `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b` (with dashes). Use the dashed form.
    +- **Headless ignores `--llm-approve`.** If you pass it, you get an argparse error. Headless mode hardcodes always-approve.
    +- **No Windows support upstream.** The OpenHands docs require WSL on Windows. This skill is gated `[linux, macos]` accordingly.
    +- **`~/.openhands/conversations/<id>/` accumulates.** Each run persists a trajectory. Clean it up if running batches.
    +- **Heavy install (~200 packages).** Use `uv tool install` (isolated venv) to avoid dependency conflicts with the active project.
    +
    +## Verification
    +
    +```
    +terminal(
    +  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=[redacted:secret-assignment] LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'",
    +  workdir="/tmp",
    +  timeout=120
    +)
    +```
    +
    +If the JSONL stream ends with a `FinishAction` whose `action.message` mentions `OPENHANDS_OK`, the install is working.
    +
    +## Related
    +
    +- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands)
    +- [OpenHands CLI command reference](https://docs.openhands.dev/openhands/usage/cli/command-reference)
    +- Sibling skills: `claude-code` (Anthropic-only), `codex` (OpenAI-only), `opencode` (multi-provider via OpenCode), `hermes-agent` (Hermes subagents via `delegate_task`).

  • website/sidebars.ts

    @@ -392,6 +392,7 @@ const sidebars: SidebarsConfig = {
                       items: [
                         'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox',
                         'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho',
    +                    'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands',
                       ],
                     },
                     {