agent-harness is a thin, offline-first multi-agent orchestrator for the
tzervas fleet. Use it when you need a local dry-run spawn plan, environment
runtime.
It is a separate product from tg-agent-relay (phone ↔ agent surface). Harness composes relay, agent-mcp, cabal-devmelopner, and templates from tz-forge by reference — it does not re-home them.
MIT · Python ≥ 3.14 · zero runtime dependencies · optional shared CI via gha-runner-ctl.
Alpha v0.3.0 — usable offline CLI + docs pack. Not a full swarm platform yet.
| Surface | Ready? |
|---|---|
version / spawn --dry-run / doctor |
Yes (offline) |
scripts/local-ci.sh |
Yes |
| AGENTS.md + CLAUDE.md | Yes |
| Live spawn / network GitHub fetch | No (v0 intentionally) |
| Epics #1–#5 | OPEN (board honesty) |
| Epic | Code / docs progress | Board |
|---|---|---|
| #3 Thin CLI / package | v0 scaffold landed | OPEN until formal ship close |
| #4 Relay + agent-mcp by ref | Integration notes only | OPEN |
| #5 E2E swarm dry-run | Dry-run spawn path only; full E2E later | OPEN |
Requires: uv, Python ≥ 3.14, bash. No network APIs after install (lockfile resolve may fetch packages once).
git clone https://github.com/tzervas/agent-harness.git
cd agent-harness
uv sync
uv run agent-harness version
# → 0.2.0
uv run agent-harness spawn --issue 3 --dry-run
# → spawn plan (dry-run)
# issue: #3
# mode: dry-run
# network: false
# lane: build
# validate: bash scripts/local-ci.sh
# note: offline; no GitHub fetch; …
uv run agent-harness doctor
uv run agent-harness compose-doctor
uv run agent-harness spawn --issue 3 --dry-run --json | head
# → doctor (offline)
# [ok] python>=3.14: …
# [ok] uv on PATH: …
# [ok] VERSION file: …
# [ok] scripts/local-ci.sh: …
# version: 0.2.0
bash scripts/local-ci.sh
# → ==> local-ci OKZero runtime dependencies (stdlib argparse only). Dry-run spawn never hits the network.
| Dependency / reference | Role |
|---|---|
| tzervas/tz-forge | Templates, fleet pack, tz-new, agent profiles |
| tzervas/tg-agent-relay | Telegram bridge, providers, MCP facade (consume, don’t fork product) |
| tzervas/agent-mcp | Multi-agent orchestration MCP (evaluate / integrate) |
| tzervas/cabal-devmelopner | Operator CLI/TUI for L0/L1 waves |
Full details: docs/INTEGRATIONS.md.
| Branch | Role |
|---|---|
main |
Stable; PR only |
dev |
Persistent integration |
feat/* |
Off dev (or intentional fleet branches off main) |
Issue close policy: merges to dev leave issues open (Refs #n); close on main only (Closes / Fixes).
See docs/WORKFLOW.md and AGENTS.md.
One shared runner host (not one per repo):
runs-on: [self-hosted, linux, x64, podman]Register the host with an org runner when possible so many repos share it.
See gha-runner-ctl.
Do not enable USE_SELF_HOSTED without maintainer approval.
- AGENTS.md — agent rules (PR tiers, safety, compose)
- CLAUDE.md — commands map for coding assistants
- CHANGELOG.md — release notes
- docs/VISION.md — goals and non-goals
- docs/WORKFLOW.md — orchestrator + swarms, cost lanes, spawn template
- docs/ARCHITECTURE.md — layers, package map, compose-by-reference
- docs/DECISIONS.md — design decisions (D1–D5)
- docs/EPICS.md — Wave C epic board links (status honesty)
- docs/INTEGRATIONS.md — tz-forge + relay + agent-mcp + cabal
- docs/FLEET_STANDARDS.md — fleet CI / issue close
MIT — see LICENSE.