Exit codes and environment#

Every hekma command exits with one of seven codes, so a script can branch on the kind of failure without reading stderr. This page lists the codes with every condition that produces each, then the environment variables Hekma reads and the ones it passes to agents.

Exit codes#

The codes are a stable interface, covered by the same compatibility rule as the JSON documents: a code's meaning changes only in a major release, announced ahead in the release notes.

A script branches on the code directly:

hekma agent show worker --json > status.json
case $? in
  0) ;;                                            # status.json is valid
  3) hekma agent register worker --manifest "$HOME/agents/worker" ;;
  4) echo "worker is in the wrong state for that" >&2 ;;
  *) echo "unexpected failure" >&2; exit 1 ;;
esac

Commands that print to stdout stop cleanly when the reader goes away, so hekma agent logs NAME --json | head -5 exits 0.

Environment variables Hekma reads#

Without an override, the state directory is the platform data directory for an app named ktesio: ~/Library/Application Support/ktesio on macOS, ~/.local/share/ktesio on Linux, and %APPDATA%\ktesio\data on Windows.

An agent started by Hekma inherits the environment of the command that started it. This matters for detached agents: the variables in your shell when you run hekma agent start --detach are the ones the agent keeps.

Update checks#

Every command except self-update may check GitHub for a newer Hekma release. It checks at most once an hour, caching the answer, and when a newer release exists prints one line on stderr suggesting hekma self-update. It never changes stdout. The check is off when HEKMA_NO_UPDATE_CHECK, KTESIO_NO_UPDATE_CHECK or CI is set to a true value.

What Hekma passes to agents#

Hekma does not add fixed variables of its own to an agent's environment. Everything it passes comes from the adapter, the agent's config, or one of two engine-set values, and it reaches the agent only where the adapter maps it:

The built-in kinds map these keys:

So an acp agent with a filesystem memory backing gets HERMES_HOME pointing at its memory folder, whatever agent it is. Without a backing, no HERMES_HOME is set and the agent uses its own default.

The agent's working directory is its Agent Home. Its stdout and stderr are captured to log files there. Its stdin is a pipe only when the agent declares interaction support and was started without --detach; otherwise stdin is closed.

KTESIO_USAGE is not an environment variable. It is the prefix of the line an agent prints to report its own usage; see Meter token usage.

Read next#

• CLI reference: each command's errors in context.
• JSON output: the documents to parse when a command succeeds.
• Config keys: the keys that become agent environment variables.
• Troubleshooting: what to do about common failures.