AGENTS.md

Context for AI coding agents working in this repo. Keep this file to non-inferable facts (commands, layout, conventions, gotchas) — not things you can read from the code. Universal working-style rules live in the global ~/.claude/CLAUDE.md, loaded automatically. The default change workflow lives in the global dev-workflow skill; this file adds the pyharness-specific commands, layout, and conventions it needs.

What this is

pyharness — a CodeAct agent with a containment and audit layer. The orchestrator either replies with text or emits one run_python call that the harness runs in a persistent Jupyter-style kernel. No fine-grained JSON tools; capabilities are builtins in scope or tools imported on demand. See docs/explanation/ for the model.

Commands

Everything is driven by make (make help lists all targets). uv is the package manager; there is no pip/venv step to run by hand.

make setup     # create .env + install editable package + dev toolchain (one-time)
make test      # tests + the adversarial suite — no API key needed. Use this to verify changes.
make evals     # run the adversarial suite alone and rewrite evals/SCOREBOARD.md (commit the diff)
make lint      # ruff check + ruff format --check (what CI checks when triggered)
make format    # ruff format + ruff check --fix (apply autofixes)
make typecheck # mypy — lenient, non-blocking (see [tool.mypy] in pyproject.toml)
make run       # interactive agent + live viewer :6061 (needs ANTHROPIC_API_KEY in .env)
make watch     # live viewer alone (tails .sessions/) for a session started elsewhere
make site      # re-bake the committed evidence site (evals/demo/site) — commit the diff
make up        # optional Phoenix OTel backend (:6006); make down stops it

The dev toolchain (ruff, mypy, pytest) is pinned in the dev dependency group ([dependency-groups] in pyproject.toml); make setup installs it. CI (.github/workflows/) is manual-only (workflow_dispatch) — nothing fires on push or PR; start a run with gh workflow run test.yml. It runs make test across Python 3.11/3.12/3.13 plus a ruff check, with mypy as a non-blocking signal. Because nothing runs automatically, the local checks are the real gate: run make test and make lint yourself. Do not wire coverage into the default pytest run — pytest-cov breaks the sandbox child's re-exec (6 tests).

pages.yml is workflow_dispatch-only for the same reason, and this one bites: it publishes evals/demo/site to https://z3e8.github.io/pyharness/, so committing a re-baked page does not update the live site. A clean repo is not a clean site. After any change to the committed pages — a make site re-bake, a redaction, a fix — run gh workflow run pages.yml and then verify over HTTP (curl https://z3e8.github.io/pyharness/<page>), not just in git. Only evals/demo/site is published; evals/data/site is repo-only.

To test-drive the harness itself (run a probe task, inspect what happened, fix, re-run) use the headless CLI — the harness-loop skill has the full loop:

uv run pyharness run "probe task" --json   # headless one-shot; digest on stdout, exit code = outcome (needs API key)
uv run pyharness show [--transcript]       # inspect the latest session — no API key, low context

Direct equivalents without make: uv run pytest -q, uv run pyharness. Config lives in a single .env (copied from .env.example); the Makefile and docker-compose both read it — do not export env vars by hand.

Repo map

Folder names are visible from ls; this table is the meaning — where the load-bearing seams are.

Conventions

• Python ≥ 3.11. Match surrounding style; keep changes surgical.
• Every capability the agent can call goes through broker/dispatch.py — add new ones there, not by scattering I/O across modules.
• The audit log is a tamper-evident hash chain; verify with make verify-audit DIR=.sessions/<name>.
• A change that alters behavior, a builtin, a flag, or a config var updates the matching docs/ page in the same commit — reference pages track specific sources (builtins.md ↔ SYSTEM_PROMPT in agent.py, configuration.md ↔ .env.example, python-api.md ↔ __init__.py). The docs skill has the full sync map.

The agents/ folder

agents/ is local working space for agents (Claude Code included) to plan work that outlasts one session. If a task is too big to finish in one go, drop the plan and running progress here as a living TODO so the next agent resumes from it, and keep it current with what actually shipped. Keep it tidy: prune stale notes, and move finished or superseded files into agents/old/.

It is gitignored and its history was removed from the repo (2026-08-01). It is scaffolding for building the project, not part of it, and it does not travel between machines — back it up yourself if that matters. Nothing in it is load-bearing for the running code. Design rationale that is worth publishing goes to docs/explanation/design-decisions.md instead, written in the maintainer's voice; do not treat agents/decisions.md as its source, since one is a log of what agents chose autonomously and the other is a curated account of what the maintainer decided.

Keep it minimal by design — a few active files, no scratch buildup. Three standing docs anchor it: README.md (the index/map — keep current), issues.md (open-only known-issues log: append suspicions and fix them together later, then retire each resolved record to a dated old/resolved-issues-*.md so the file only ever lists open work), and decisions.md (append-only log of autonomous choices agents made and why). Working docs come in two types — plans (plan-*.md) and reports (*-report.md) — living flat at the top level; retire them to old/ once shipped or superseded. The orchestrate-workflow skill drives the fan-out-to-sub-agents loop over this backlog.

Gotchas

• docs-legacy/ is gitignored local-only notes — do not treat it as current or wire anything to it. The live docs are docs/; agent scratch is agents/ (see above).
• Session state lives under .sessions/ (gitignored). The agent's relative paths resolve inside its session workspace, not the repo root.