axe

Local LLM agent runner. TOML-defined agents, CLI invocation, Ollama backend.

Goals

Run multi-step LLM agent workflows locally — task decomposition, diary retrieval, podcast scripting — without cloud API calls and without writing a custom LLM runner.

Effectiveness

Solid. Handles all current agents reliably once configured correctly. The TOML agent format is low-friction and the sub-agent composition model maps cleanly onto the workflows we actually run (decomposer spawns a researcher, podcaster delegates to pipeline, etc.).

What made it effective

• Sub-agent composition with [sub_agents_config] — one agent can fan out to others without orchestration code
• [retry] config with backoff = "fixed" handles transient Ollama connection drops without any client-side retry logic
• --dry-run flag shows the resolved context without calling the LLM — invaluable for debugging prompt assembly

Bonus utility

The run_command tool inside agents lets them call shell commands mid-generation. inertia-decomposer uses this to retrieve diary context before decomposing — the agent fetches its own context rather than requiring the caller to pre-fetch it.

Friction / pain points / surprises

Default timeout is 120s — too short for 27b with sub-agents. inertia-decomposer makes at least two full 27b calls (tool call + sub-agent). This routinely exceeds 120s and silently fails with timeout: context deadline exceeded. The TOML has no timeout field — it must be passed as --timeout 540 at every call site. Easy to miss; cost us a full run of failures before diagnosing.

Batch endpoint doesn't recover from ConnectionClosed. axe uses Ollama's non-streaming endpoint. Long generations on a loaded model drop the socket. The whole request fails with no retry. We absorb this via per-task fault isolation (failed tasks retry on the next nightly run), but streaming would eliminate the failure mode entirely.

No --help flag. axe --help attempts to list agents and errors if the config directory is missing. Discovering available flags required reading dist/cli/args.js in the source tree.