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
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.
Runnable Livebooks are under guides/livebooks/:
Provider cells use live CLIs. The managed-process example runs locally.
Contribute
See CONTRIBUTING.md for setup, the file map, checks, and
release preparation.
