docs · adapters
Gemini CLI#
Unreleased: after 0.11.0. This page is on Hekma's main branch and ships in the next release; Hekma 0.11.0 does not have it.
Google's Gemini CLI speaks ACP when started with its ACP-mode flag, so it runs under Hekma's built-in acp kind. It needs a logged-in CLI (or API key) before it will open a session — a logged-out session/new answers JSON-RPC -32000, and the engine surfaces the code, never the agent's message.
Register#
hekma agent config set my-gemini acp.command "gemini"
hekma agent config set my-gemini acp.args "--experimental-acp"
hekma agent register my-gemini --kind acp
hekma agent start my-geminiThe --experimental-acp spelling is the long-documented IDE-integration form; newer builds also accept the shortened --acp.
Honesty table#
The pause and interaction levels are the acp kind's own capability declaration — identical for every ACP agent and proven by the conformance kit against a scripted stand-in; they are not per-agent promises. The metering rows are characterized from upstream documentation, not run-verified here.
| Surface | Value | Evidence class |
|---|---|---|
pause | guaranteed (Linux), guaranteed (macOS), best-effort (Windows) | contract-validated |
interaction | guaranteed (all OSes) | contract-validated |
| Metering source | self-reported | contract-validated |
| Billing-grade tokens | — — 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). No sentinel emission and no base-URL override is documented upstream | characterized |
| Context usage | an agent-reported usage_update would surface under acp_context_usage — context-grain, never billed; whether this agent reports one is unverified here | characterized |
Validation status. Upstream: experimental (the ACP mode's own flag spelling). Evidence: characterized — a repo-documented launch shape, plus a skip-unless-present smoke test that runs wherever the gemini binary exists (an honest no-op where it does not). It has no version pin and no run-verified turn on record here; see Supported agents for what that would take.
PATH requirement#
The launch command is the bare word gemini, resolved through the PATH of the environment hekma runs in. Hekma does not bundle, install or pin the Gemini CLI binary — install it yourself, keep it on the PATH, or give an absolute path. A start whose gemini cannot resolve fails with the engine's launch-failure diagnostic naming the executable.
Re-validation duty#
Gemini CLI moves quickly and its ACP mode carries the experimental flag spelling; every characterization here is a snapshot by design. Re-validate against the version you install before relying on agent-specific behaviour — Re-validation states the full duty, including the contract duties that no automated kit can prove.
Read next#
- Adapter Gallery: the index this entry belongs to.
- Run an ACP agent: registration, configuration and prompts for ACP agents.
- Meter token usage: what each metering tier counts, and what stays
—.