Quickstart

From install to a verifier-checked answer in five minutes.

Install

avatar-harness is a Python 3.12+ library. It is not yet published to PyPI — install it from source:

The repo is a uv workspace with two packages: the SDK (avatar-harness/, import avatar) and the cockpit (jo-cli/, import jo).

# From a clone (editable):
git clone https://github.com/codexceed/avatar-harness.git
cd avatar-harness
pip install -e './avatar-harness[openai]'   # the SDK + default OpenAI-compatible model client
pip install -e ./jo-cli                 # + the Textual cockpit, the `jo` command (optional)

# Or straight from GitHub into your own project's environment
# (uses your git credentials while the repo is private):
pip install 'avatar-harness[openai] @ git+https://github.com/codexceed/avatar-harness#subdirectory=avatar-harness'
# uv equivalent:
uv add 'avatar-harness[openai] @ git+https://github.com/codexceed/avatar-harness#subdirectory=avatar-harness'

Always quote the extras — zsh otherwise glob-expands the brackets and fails with no matches found: avatar-harness[openai].

The core imports without either extra — openai is needed only to use the default OpenAIModelClient (you can inject any ModelClient instead), and textual only for the bundled TUI. Two external binaries must be on PATH:

• ripgrep (rg) — the search_repo tool shells out to it.
• git — patches apply via git apply; the workspace pins HEAD as its diff baseline.

Working on this repo itself, make install (a thin uv sync) sets up everything including the dev tools.

Configure

Configuration comes from AVATAR_* environment variables or a local .env. The only required value is an API key:

# .env
AVATAR_API_KEY=sk-or-...                       # required; falls back to OPENAI_API_KEY
AVATAR_MODEL=openai/gpt-4o-mini                # default; any model your endpoint serves
AVATAR_BASE_URL=https://openrouter.ai/api/v1   # default (OpenRouter); change for OpenAI/local
AVATAR_WORKSPACE_ROOT=.                        # the repo the agent operates on (default: cwd)

The full knob list (budgets, verification commands, the sensitive-path denylist, context-compaction budgets) is in the SDK guide.

First run — the CLI

avatar "where does the agent loop terminate, and what sets outcome=success?"

The CLI streams a timestamped event trajectory as the agent works, then prints a Status: line and the cited answer. The whole run is journaled to events/<session_id>.jsonl for replay and debugging.

The workspace refuses to start on a tree with uncommitted tracked changes (the diff baseline must be well-defined — untracked files are fine). Commit, stash, or pass --allow-dirty.

First run — the library

The same engine, importable. Five lines to a verifier-checked answer:

from avatar import Harness

harness = Harness.from_env()                  # AVATAR_* / .env; no key needed to construct
state = harness.run("explain how str_replace anchors edits")
print(state.outcome, "\n", state.final_answer)

state.outcome is "success" only when the harness-owned verifier found positive external evidence — the model never self-certifies. The other terminal outcomes are incomplete (budget exhausted), blocked (needs human input), and failed (a completion claim that wouldn’t verify).

Every collaborator is an injectable seam:

from avatar import Harness, HarnessConfig

harness = Harness(
    # test_command is the always-wins override; left unset, the harness detects
    # the repo's declared contract (CI workflows, manifests, Makefile — ADR-0007)
    config=HarnessConfig(workspace_root="./repo", test_command="python -m pytest -q"),
    model=my_model_client,    # any ModelClient — no `openai` extra needed
)
state = harness.run("fix the failing auth test", task_kind="edit")

The task_kind (investigate / edit / test_only) selects the verification contract — what evidence is required before the run may be called a success. investigate is the default: a grounded answer with the tree netting to zero diff vs the pinned baseline at verification (transient instrumentation is legal mid-task, but must be reverted — ADR-0005).

Where to go next

SDK guide

The full surface: the two-plane Session, typed events, multi-turn ReplSession, and every configuration knob.

Build a terminal agent

A step-by-step tutorial: your own streaming, approval-answering agent in about 90 lines.