hekma
Menu

docs · adapters

Aider#

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.

Aider has no ACP mode, so it integrates through a manifest adapter.toml — the one manifest-based entry in this gallery. Its billing-grade metering rides the engine-observed channel: Aider honours an OpenAI-compatible base-URL override, which is the wiring the manifest declares.

The shipped manifest#

This is the manifest in full. Copy it into a directory of your own (the example below assumes ./aider):

# The launch exec is a BARE program name, resolved on the operator's PATH at
# start (the manifest reference's own resolution rule) — Hekma does not
# bundle, install, or pin the Aider binary.
#
# Metering is engine-observed: at start the engine injects its loopback
# listener address into OPENAI_API_BASE, which Aider honours as its
# OpenAI-compatible base-URL override. The real provider endpoint is named
# separately with metering.upstream_base_url (hekma agent config set). Until
# that override is wired, no billing-grade tokens flow: the Fleet shows the
# honest `—` with the tiers-attempted notice, never a fabricated figure.
#
# Validated by the conformance kit against a bundled fake (the exec word is
# PATH-shadowed) — never against the real binary.

contract_version = "1.0.0"

[adapter]
kind = "aider"
name = "Aider"

[lifecycle.start]
exec = "aider"
# No launch args are pinned: add the flags your Aider setup needs. The
# engine-observed channel rides the config mapping below, not argv.

[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"

[capabilities.interaction]
linux = "guaranteed"
macos = "guaranteed"
windows = "guaranteed"

[metering]
source = "engine-observed"

[interaction]
channel = "stdio"

# The engine-observed wiring: the reserved `metering.base_url` key is
# delivered as this environment variable (no {env:...} substitution exists
# anywhere in a manifest — values stay literal).
[config."metering.base_url"]
env = "OPENAI_API_BASE"

The manifest pins no launch args — add the flags your Aider setup needs by editing your copy. It declares no {env:...} substitutions anywhere (manifest values stay literal; there is no substitution syntax to expand). Then register from the directory:

hekma agent register my-aider --manifest ./aider
hekma agent start my-aider

Honesty table#

The pause and interaction rows are the shipped manifest's own per-OS capability declaration, proven by the conformance kit against a bundled fake — not run-verified against the real binary. The metering rows are the honest part: the override is a hypothesis from Aider's documented interfaces, dated, never demonstrated here.

SurfaceValueEvidence class
pauseguaranteed (Linux), guaranteed (macOS), best-effort (Windows)contract-validated
interactionguaranteed (all OSes)contract-validated
Metering sourceengine-observedcontract-validated
Billing-grade tokens— unless the operator wires the override: tokens flow only when metering.upstream_base_url names the real provider endpoint (the engine then meters the model traffic through its loopback proxy, injected as OPENAI_API_BASE). Without it: no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen (Aider prints token stats of its own but writes no KTESIO_USAGE sentinel)characterized
Context usageAider's own on-screen token stats are display-only; the engine surfaces nothing extra for this entrycharacterized

Wiring the override, after registering:

hekma agent config set my-aider metering.upstream_base_url "https://api.openai.com"

Verify the endpoint form against your provider before relying on it: OpenAI-compatible base URLs conventionally need the /v1 suffix (https://api.openai.com/v1), and this wiring line is part of the characterized claim above — not run-verified here.

Validation status. Upstream: stable (the Aider project), but this entry's integration claims are characterized — the base-URL override wiring is a hypothesis from Aider's documented --openai-api-base/OPENAI_API_BASE interfaces, dated 2026-10-23, NOT run-verified here. What IS validated is the shipped manifest itself: the conformance kit runs the full fixed section suite against it in CI, with its bare exec word shadowed on PATH by a bundled fake agent (CI never launches the real binary). "Conformant" means every machine-checkable duty of the adapter contract held for the declaration; it is not a claim that real Aider honours the override.

PATH requirement#

The manifest's exec is the bare word aider, resolved through the PATH of the environment hekma runs in (the manifest reference's own resolution rule). Hekma does not bundle, install or pin the Aider binary — install it yourself, keep it on the PATH, or give an absolute path. A start whose aider cannot resolve fails with the engine's launch-failure diagnostic naming the executable.

Re-validation duty#

The override wiring is the part re-validation must cover first: prove it against your installed Aider version before trusting the metering row. Every claim here is a snapshot by design — Re-validation states the full duty, including the contract duties that no automated kit can prove.