Jido.Harness

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 Arbor ACP.

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.1 release candidate. Test it with a Git dependency. Review the version 3 migration guide and dependency audit before release use.

Install

Add the dependency to your application's mix.exs:

def deps do
  [
    {:jido_harness, github: "agentjido/jido_harness", branch: "main"}
  ]
end

Run 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 --strict

Follow Getting started for installation, authentication, and application configuration.

Run one task

{: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.

Choose an API

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.

Providers

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.

Place in the Jido ecosystem

Harness owns coding-agent execution, process lifetime, and common results. Arbor ACP 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.

Documentation

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/:

• One-shot requests.
• Detached runs, streams, and replay.
• Interactive sessions and managed processes.

Provider cells use live CLIs. The managed-process example runs locally.

Contribute

See CONTRIBUTING.md for setup, the file map, checks, and release preparation.