Jido.Harness runs coding-agent CLIs from Elixir. It manages their processes and returns common request, event, result, and error types. Runs and sessions use Agent Client Protocol (ACP) through ExMCP.
Use it to run one task, keep a conversation open, or start work and collect its result later. Work belongs to the application supervision tree and can continue after the caller exits. Output retention is bounded. Runs and sessions do not survive a BEAM or host restart.
This checkout is the
3.0.0-rc.1release candidate. Test it with a Git dependency. Review the version 3 migration guide and dependency audit exceptions before release use.
Add the dependency to your application's mix.exs:
def deps do
[
{:jido_harness, github: "agentjido/jido_harness", branch: "main"}
]
endRun mix deps.get and commit mix.lock to record the selected revision.
Use ref: with a full commit ID when you need a fixed source revision.
Compilation requires make, a C++17 compiler, and Erlang's erl_interface
headers and library. Harness builds its bundled native process helper from
source. See the dependency reference.
Each provider needs an installed CLI, authentication, and an ACP entry point.
Some CLIs include ACP. Others need a separate adapter. Preview the installation
from an Elixir shell started with iex -S mix:
Jido.Harness.install(:codex, dry_run: true)Check provider readiness without sending a prompt:
mix jido_harness.check --providers codex --strictFollow Getting started for installation, authentication, and application configuration.
{:ok, %Jido.Harness.RunResult{status: :completed} = result} =
Jido.Harness.run(:codex, "Reply with exactly: harness-ready",
cwd: File.cwd!(),
runtime_timeout_ms: 300_000,
await_timeout: 320_000
)
IO.puts(result.text)This request uses a real provider and can consume API or subscription usage.
Check result.status when handling results: {:ok, result} can also contain a
failed or cancelled task. An await timeout stops the caller's wait; it does not
cancel the task.
| Need | API | Guide |
|---|---|---|
| Wait for one task | Jido.Harness.run/3 |
One-shot requests |
| Start work and return later | Jido.Harness.Run |
Detached runs |
| Keep a multi-turn conversation | Jido.Harness.Session |
Interactive sessions |
| Manage a local executable | Jido.Harness.Process |
Managed processes |
Resources have stable Harness IDs. You can inspect their state, stream or replay events, wait for completion, cancel active work, and prune retained results. See Choose an API.
Built-in adapters cover Amp, Claude Code, Codex, Cursor CLI, Gemini CLI, Grok, Kimi Code, OpenCode, Pi, and Z.AI. Options and capabilities differ between providers. Unsupported options return an error.
The provider guide lists entry points, installation requirements, model selection, and current isolation limits. No built-in version 3 ACP profile advertises structured output.
Harness owns coding-agent execution, process lifetime, and common results. ExMCP owns the ACP protocol. Jido Connect owns service API integrations. Application code owns provider selection, workspace setup, approval policy, and decisions about the result.
Harness does not require jido or jido_connect. It can run in an Elixir
application on its own. See the architecture
and dependency reference.
All guides, reference pages, migration instructions, and notebooks are under guides/.
Generated API documentation is written to the ignored doc/ directory.
- Overview: resource model and runtime guarantees.
- Getting started: one provider and one request.
- Operations: limits, telemetry, retention, and shutdown.
- Configuration reference: application settings.
- Escript packaging: package the native process helper.
- Testing: local fixtures and optional live contracts.
Runnable Livebooks are under guides/livebooks/:
Provider cells use live CLIs. The managed-process example runs locally.
See CONTRIBUTING.md for setup, the file map, checks, and release preparation.