docs · reference

Supported agents#

Hekma 0.11.0 runs any agent that speaks the Agent Client Protocol (ACP) through its built-in acp kind, and any other program through an adapter.toml manifest. OpenCode and Hermes Agent have been run end to end over ACP at the versions below. Agents change quickly, so re-test against the version you install. The adapter gallery (Unreleased: after 0.11.0) gives each agent that runs under Hekma today its own page, with a per-capability honesty table and an evidence class for every claim.

Compatibility#

Agent or kindHow you register itStatusTested version
Any ACP agent--kind acp, with acp.command and acp.argsSupported. Speaks ACP protocol version 1.Tested against a scripted ACP test agent in Hekma's test suite
OpenCode--kind acp, acp.command opencode, acp.args acpRun end to end: start, a full prompt turn with the reply in the logs, context usage reported, clean stop.v2.0.28 (2026-10-16). Start and session handshake also checked with v2.0.32 (2026-10-22).
Hermes Agent--kind acp, acp.command hermes-acpRun end to end, as for OpenCode.v0.21.7+500.g8f81791 (2026-10-16)
Hermes Agent gateway--kind hermesDeprecated: use --kind acp with hermes-acp. Still works unchanged.v0.20.5, commit 41447a6d (2026-08-25)
Gemini CLI--kind acp, acp.command gemini, acp.args --experimental-acp (newer builds: --acp)Expected to work; Hekma's test suite has a check that runs when gemini is installed, but no verified version is recorded. Needs a logged-in CLI or API key.not verified
Your own program--manifest DIRSupported through an adapter.toml.You test it, with the conformance kit.
mock--kind mockA test fixture: registers and accepts config, but has no launch command, so it cannot start.not applicable

Hekma does not install, bundle or update any agent. Install the agent yourself and make sure its command is on the PATH that hekma runs with, or give an absolute path.

From the CLI alone, Hekma 0.11.0 cannot keep an ACP agent running and send it prompts: a plain start ends with its command, and a detached start closes stdin, which ACP needs. ACP agents need a program that embeds the engine. Run an ACP agent explains this in full.

Built-in kinds#

KindLaunchPauseInteractionMetering sourceConfig mapping
acpacp.command and acp.argsguaranteed on Linux and macOS, best-effort on Windowsguaranteedself-reported, through KTESIO_USAGE lines on stderr; engine-observed if metering.upstream_base_url is setmemory.dir to HERMES_HOME, metering.base_url to OPENAI_BASE_URL
hermeshermes gateway run --external-supervisorbest-effortguaranteedself-reportedmemory.dir to HERMES_HOME
mocknoneguaranteed on Linux and macOS, best-effort on Windowsguaranteedself-reportedmodel to MODEL, memory.dir to KTESIO_MEMORY_DIR

The hermes kind is deprecated in favour of --kind acp with acp.command hermes-acp. It keeps working unchanged and will not be removed before a major release. Moving to acp keeps the same metering (self-reported usage lines, on stderr under acp) and the same memory delivery (a filesystem memory backing arrives as HERMES_HOME). Without a memory backing, neither kind sets HERMES_HOME, so every Hermes agent without one shares Hermes's default home; attach a filesystem backing to give each its own.

OpenCode notes#

OpenCode needs no login for its free default models; a paid model needs opencode auth login first, and a logged-out OpenCode refuses the session at start. OpenCode reports token counts in its own ACP messages, but those are not one of Hekma's usage sources, so Hekma shows its context usage and records no billable usage unless you add a usage source. To give each OpenCode agent its own data and config, set agent.XDG_DATA_HOME and agent.XDG_CONFIG_HOME to folders inside its Agent Home. Recipes are in Run an ACP agent.

Re-validation#

Every version in the table is a snapshot: it records what was run, on that date, with that Hekma release. OpenCode ships several releases a week and Hermes Agent changes almost daily, so a later version can change its handshake, its config files or the settings Hekma relies on to keep agents apart. Before you depend on agent-specific behaviour, run your agent's version through the same steps (register, start, one prompt turn, stop) and, for a manifest adapter, through the conformance kit; the contract duties that the kit cannot test are exactly the ones to check by hand.