Repository navigation
docs: surface ClawHub traction (1.1K downloads) in README #2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,84 +1,180 @@ | ||
| # OpenCode ACP Control | ||
|
|
||
| **Control OpenCode directly via the Agent Client Protocol (ACP).** | ||
| > **A reusable AI agent skill that lets coding agents drive OpenCode CLI sessions over the Agent Client Protocol (ACP).** | ||
| > **1.1K+ downloads on [ClawHub](https://clawhub.ai/berriosb/skills/opencode-acp-control-3) — used in production agent workflows.** | ||
|
|
||
| This repository contains a reusable **skill** (`.md`-based instruction set) that enables AI coding agents to start, control, and monitor OpenCode sessions over the **Agent Client Protocol (ACP)**. | ||
| [](https://clawhub.ai/berriosb/skills/opencode-acp-control-3) | ||
| [](./LICENSE) | ||
| [](https://agentclientprotocol.com) | ||
| [](https://opencode.ai) | ||
| [](https://python.org) | ||
| [](./.github/workflows/ci.yml) | ||
|
|
||
| ## What It Does | ||
| --- | ||
|
|
||
| - Start OpenCode in ACP mode | ||
| - Create, resume, and cancel sessions | ||
| - Send prompts and stream responses | ||
| - Resume past conversations from saved session IDs | ||
| - Check for and trigger OpenCode updates | ||
| ## What it does | ||
|
|
||
| ## Quick Start | ||
| This repository contains a reusable **agent skill** (`.md`-based instruction set) that enables AI coding agents — such as [Hermes Agent](https://hermes-agent.nousresearch.com) and Clawdbot — to **start, control, and monitor [OpenCode](https://opencode.ai) CLI sessions** over the standardized [Agent Client Protocol (ACP)](https://agentclientprotocol.com), which speaks **JSON-RPC 2.0** over stdio. | ||
|
|
||
| In plain terms: an AI agent can spin up an OpenCode session, send it coding tasks, stream responses back, resume old conversations by ID, and shut it down — all through a documented JSON-RPC interface. | ||
|
|
||
| ### Capabilities | ||
|
|
||
| - ✅ Start OpenCode in ACP background mode (`opencode acp`) | ||
| - ✅ Initialize JSON-RPC 2.0 connection and create new sessions | ||
| - ✅ Send prompts and stream responses (notifications + content blocks) | ||
| - ✅ Cancel mid-response without losing state | ||
| - ✅ Resume past conversations from saved session IDs | ||
| - ✅ Detect new OpenCode releases and trigger in-place updates | ||
| - ✅ Run end-to-end against a live `opencode acp` process via `examples/acp_demo.py` | ||
|
|
||
| --- | ||
|
|
||
| ## Why it matters | ||
|
|
||
| Most AI coding agents today are isolated: they can't reliably spawn, supervise, or coordinate other coding CLIs. **ACP** is the open standard (JSON-RPC 2.0 over stdio) that fixes this — but agents need explicit instructions to use it correctly (handshake order, framing, permission requests, session IDs). | ||
|
|
||
| This skill packages that knowledge into a drop-in instruction set any ACP-compatible agent can load. Instead of every agent author re-discovering the protocol quirks, they load `SKILL.md` and get the working workflow. | ||
|
|
||
| **Result:** agents become orchestrators, not isolated tools. | ||
|
|
||
| --- | ||
|
|
||
| ## Traction | ||
|
|
||
| | Metric | Value | Source | | ||
| |---|---|---| | ||
| | Downloads on ClawHub | **1.1K+** | [clawhub.ai/berriosb/skills/opencode-acp-control-3](https://clawhub.ai/berriosb/skills/opencode-acp-control-3) | | ||
| | Current version | **v0.1.1** (ClawHub) / **v0.2.0** (GitHub) | ClawHub dashboard | | ||
| | Last updated | **May 17, 2026** | ClawHub dashboard | | ||
| | Stars | 2 | GitHub | | ||
| | License | MIT | [LICENSE](./LICENSE) | | ||
|
|
||
| > The GitHub repo is the source of truth for development. ClawHub is the distribution channel for agent authors who install the skill with one command. | ||
|
|
||
| --- | ||
|
|
||
| ## Quick start | ||
|
|
||
| ### Install the skill into your agent | ||
|
|
||
| ```bash | ||
| # Clone | ||
| git clone https://github.com/berriosb/Opencode-Acp-Control.git | ||
| cd Opencode-Acp-Control | ||
| # ClawHub (recommended for OpenClaw / Clawdbot users) | ||
| openclaw skills install @berriosb/opencode-acp-control-3 | ||
|
|
||
| # Load as skill (Hermes Agent) | ||
| # Option A — copy into the active profile's skills dir | ||
| # Hermes Agent — copy into the active profile's skills dir | ||
| cp SKILL.md ~/.hermes/profiles/<profile>/skills/opencode-acp-control.md | ||
|
|
||
| # Option B — load from a custom path (Hermes picks up any .md under the skills tree) | ||
| # Or as a folder | ||
| mkdir -p ~/.hermes/profiles/<profile>/skills/opencode-acp-control | ||
| cp SKILL.md ~/.hermes/profiles/<profile>/skills/opencode-acp-control/SKILL.md | ||
| ``` | ||
|
|
||
| ## Try It Locally | ||
| ### Try it locally (no LLM needed) | ||
|
|
||
| ```bash | ||
| # Print the JSON-RPC frames the skill produces (no opencode needed) | ||
| # Print the JSON-RPC frames the skill produces (no OpenCode required) | ||
| python3 examples/acp_demo.py --dry-run | ||
|
|
||
| # Spawn opencode acp, run initialize + session/new, and exit (no LLM call) | ||
| # Spawn `opencode acp`, run initialize + session/new, and exit | ||
| python3 examples/acp_demo.py --no-prompt | ||
|
|
||
| # Full end-to-end run (requires a configured LLM provider) | ||
| # Full end-to-end run against a real project (requires a configured LLM provider) | ||
| python3 examples/acp_demo.py --cwd /path/to/project --prompt "list the files in this repo" | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Requirements | ||
|
|
||
| - **OpenCode** (≥ v1.1.0) — installed and available on `$PATH` | ||
| - A terminal with background process support | ||
| - An ACP-compatible agent (Hermes, Clawdbot, etc.) | ||
| - **[OpenCode](https://opencode.ai)** ≥ v1.1.0 — installed and available on `$PATH` | ||
| - **Python 3.11+** — only for running the demo script | ||
| - **An ACP-compatible agent** — Hermes Agent, Clawdbot, or any agent that loads `.md` skills | ||
|
|
||
| ## How It Works | ||
| --- | ||
|
|
||
| | Step | Action | Description | | ||
| |------|--------|-------------| | ||
| | 1 | `opencode acp` | Start OpenCode in ACP (background) mode | | ||
| | 2 | `initialize` | Initialize JSON-RPC 2.0 connection | | ||
| | 3 | `session/new` | Create a new coding session | | ||
| | 4 | `session/prompt` | Send prompts, stream responses | | ||
| | 5 | `session/cancel` | Cancel mid-response if needed | | ||
| ## How it works | ||
|
|
||
| | Step | JSON-RPC method | What it does | | ||
| |---|---|---| | ||
| | 1 | `initialize` | Negotiate protocol version and capabilities | | ||
| | 2 | `session/new` | Create a fresh coding session in a target directory | | ||
| | 3 | `session/prompt` | Send a user prompt and stream responses | | ||
| | 4 | `session/update` | Receive streamed content blocks + tool calls | | ||
| | 5 | `session/cancel` | Cancel mid-response without losing state | | ||
| | 6 | `session/load` | Resume a previous session by ID | | ||
|
|
||
| ## Tool Requirements for AI Agents | ||
| All frames are **newline-delimited JSON** on stdout (not LSP `Content-Length` framing) — this matches OpenCode's actual transport. | ||
|
|
||
| --- | ||
|
|
||
| This skill uses these agent tools (names vary by platform): | ||
| ## Agent tool mapping | ||
|
|
||
| | Generic Name | Hermes Agent | Clawdbot | | ||
| |-------------|-------------|----------| | ||
| | Run command | `terminal()` | `bash()` | | ||
| | Write to process | `process.write()` | `process.write()` | | ||
| This skill expects the agent runtime to expose these primitives (names vary by platform): | ||
|
|
||
| | Generic capability | Hermes Agent | Clawdbot / OpenClaw | | ||
| |---|---|---| | ||
| | Run shell command | `terminal()` | `bash()` | | ||
| | Write to a background process | `process.write()` | `process.write()` | | ||
| | Read process output | `process.poll()` | `process.poll()` | | ||
| | Kill process | `process.kill()` | `process.kill()` | | ||
| | Web fetch | `web_extract()` | `webfetch()` | | ||
| | User prompt | `clarify()` | `askUser()` | | ||
| | Kill background process | `process.kill()` | `process.kill()` | | ||
| | Fetch a URL | `web_extract()` | `webfetch()` | | ||
| | Ask the user | `clarify()` | `askUser()` | | ||
|
|
||
| --- | ||
|
|
||
| ## Repository layout | ||
|
|
||
| ``` | ||
| Opencode-Acp-Control/ | ||
| ├── SKILL.md # The skill definition — load this into your agent | ||
| ├── README.md # This file | ||
| ├── CHANGELOG.md # Release notes (Keep a Changelog format) | ||
| ├── _meta.json # Registry metadata for Hermes / ClawHub | ||
| ├── LICENSE # MIT | ||
| ├── examples/ | ||
| │ └── acp_demo.py # Runnable Python script — talks to a live `opencode acp` process | ||
| └── .github/ | ||
| └── workflows/ | ||
| └── ci.yml # CI: markdownlint + lychee URL check + ruff + python -m py_compile | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## CI / quality gates | ||
|
|
||
| Every push runs: | ||
|
|
||
| - **markdownlint** — enforces consistent Markdown style | ||
| - **lychee** — fails if any documented URL returns non-2xx | ||
| - **ruff** — Python lint | ||
| - **python -m py_compile** — syntax check on the demo script | ||
|
|
||
| --- | ||
|
|
||
| ## Contributing | ||
|
|
||
| Issues and PRs are welcome. Before opening a PR: | ||
|
|
||
| 1. `ruff check examples/` passes locally | ||
| 2. `markdownlint **/*.md` passes locally | ||
| 3. Bump the version in both `_meta.json` and `SKILL.md` frontmatter | ||
| 4. Add an entry to `CHANGELOG.md` under a new `## [x.y.z]` heading | ||
|
|
||
| --- | ||
|
|
||
| ## Author | ||
|
|
||
| **Bastián Berríos** ([@berriosb](https://github.com/berriosb)) | ||
|
|
||
| - 🌐 Portfolio: [hakke.cl](https://hakke.cl) | ||
| - 📦 ClawHub: [@berriosb](https://clawhub.ai/berriosb) | ||
| - 🐙 GitHub: [@berriosb](https://github.com/berriosb) | ||
|
|
||
| ## Files | ||
| Building AI agent infrastructure, RAG systems, and automation tools for production workflows. | ||
|
|
||
| - `SKILL.md` — The skill definition (load this into your agent) | ||
| - `examples/acp_demo.py` — Runnable Python script that demonstrates the full ACP workflow against a live `opencode acp` process | ||
| - `.github/workflows/ci.yml` — CI: `markdownlint` + URL link check + Python syntax check | ||
| - `CHANGELOG.md` — Release notes | ||
| - `_meta.json` — Registry metadata (Hermes) | ||
| --- | ||
|
|
||
| ## License | ||
|
|
||
| MIT — see [LICENSE](./LICENSE). | ||
| MIT — see [LICENSE](./LICENSE). | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the Hermes install path, a user following the README from GitHub no longer has a local checkout before this
cp SKILL.md ...command—the clone/cd lines that previously created it were removed—so the quick start fails withcp: cannot stat 'SKILL.md'. Add a clone/download step, or show a raw download command, before the copy instructions.Useful? React with 👍 / 👎.