> ## Documentation Index
> Fetch the complete documentation index at: https://codexceed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`).

```bash theme={null}
# 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'
```

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

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:

```bash theme={null}
# .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](/guides/sdk#configuration).

## First run — the CLI

```bash theme={null}
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.

<Note>
  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`.
</Note>

## First run — the library

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

```python theme={null}
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:

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="SDK guide" icon="cubes" href="/guides/sdk">
    The full surface: the two-plane `Session`, typed events, multi-turn
    `ReplSession`, and every configuration knob.
  </Card>

  <Card title="Build a terminal agent" icon="terminal" href="/tutorials/terminal-agent">
    A step-by-step tutorial: your own streaming, approval-answering agent in
    about 90 lines.
  </Card>
</CardGroup>