docs · adapters
Adapter Gallery#
Unreleased: after 0.11.0. The gallery and every entry page are on Hekma's main branch and ship in the next release; Hekma 0.11.0 does not have them.
This gallery is the validated index of which agents run under Hekma today: one page per agent, each with an honesty table in the capability declaration vocabulary, an explicit evidence class for every claim, and the re-validation duty stated per entry. Agent upstreams move fast, and an adapter's honesty is only as good as its last validation — a claim without a dated evidence class is not a claim this gallery makes.
Nine of the ten entries register through the built-in acp kind (any Agent Client Protocol v1 agent over stdio); Aider integrates through a manifest adapter.toml. The shipped manifest is validated in CI by the conformance kit against a bundled fake whose exec is shadowed onto PATH — CI never launches a real agent, and an entry claiming more than its validation proves fails the build.
The entries#
| Agent | Integration | Upstream status | Evidence class |
|---|---|---|---|
| Hermes Agent | --kind acp (hermes-acp) | stable | run-verified |
| opencode | --kind acp (opencode acp) | stable | run-verified |
| Gemini CLI | --kind acp (--experimental-acp) | experimental | characterized |
| GitHub Copilot CLI | --kind acp (--acp --stdio) | preview | characterized |
| Cursor CLI | --kind acp (agent acp) | experimental | characterized |
| goose | --kind acp (goose acp) | experimental | characterized |
| Claude Code | --kind acp via a third-party adapter | experimental (third-party adapter) | characterized |
| Codex | --kind acp via a third-party adapter | experimental (third-party adapter) | characterized |
| Crush | --kind acp via a third-party adapter (unofficial) | experimental (third-party adapter, unofficial) | characterized |
| Aider | manifest (adapter.toml) | stable | characterized |
The vocabulary, stated once#
Every table cell in this gallery uses one vocabulary:
Capability levels (per OS, the capability declaration vocabulary):
guaranteed— the engine may rely on it.best-effort— surfaced honestly (a qualifier cause on the transition, e.g.pause-best-effort), never silently treated as guaranteed.unsupported— the command fails fast, quoting the declaration; nothing is faked.
Metering sources (the two metering tiers): self-reported (the agent's usage accounting reaches the engine as KTESIO_USAGE {json} sentinel lines — under acp, on the agent's stderr, its stdout being the protocol stream) or engine-observed (the engine meters the agent's model traffic through a per-instance loopback proxy — no agent cooperation needed).
Evidence classes — how a claim in this gallery came to be believed:
run-verified— launched, supervised, and driven against the real agent, version-pinned. Pins are recorded in Supported agents and repeated on the entry pages that have one.contract-validated— proven by the conformance kit against a bundled fake; it proves the declaration's machinery, never the real agent's behaviour.characterized— taken from upstream documentation, dated, and NOT run-verified here. These entries are starting points for your own validation, not endorsements.
The honest absence token. Where no metering tier yields billing-grade usage, the token and cost cells show — — never a blank, a fabricated figure, or an implied zero — and the tiers-attempted notice names what was tried. For an acp instance with nothing wired, the notice reads:
no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; no context usage reported (ACP usage_update is context-grain, never billed)
The states are computed from your instance's actual run: an agent that reports a context window flips the last clause to context usage reported, and the figure surfaces under acp_context_usage — context-grain, never billed.
Two rules every entry carries#
The PATH requirement. Every published launch command is a bare program name, resolved through the operator's PATH at start (the manifest reference's own resolution rule). Hekma does not bundle, install or pin any agent binary — you install it per its own docs and keep it on the PATH of the environment hekma runs in. A start whose executable cannot resolve fails with the engine's launch-failure diagnostic naming the executable.
The re-validation duty. Every version pin and every dated characterization here is a stale-the-moment-it-is-written snapshot by design: pins make validation auditable, not permanent. Whoever ships a release leaning on an entry — or relies on agent-specific behaviour — re-validates against the installed version and moves the record forward. Re-validation states the full duty, including the contract duties that are exactly the parts no automated section can prove.
Read next#
- Supported agents: the validation pins behind the
run-verifiedentries, and the re-validation duty in full. - Adapter contract and conformance kit: what adapters promise, and how the kit tests one.
- Bring your own agent: write a manifest for a program this gallery does not list.