xeno-harness 4.2.0

Multi-agent autonomy harness with multi-provider support, per-role permission tiers, and Agent Harness Engineering observability.

xeno

Multi-agent AI harness. Give Claude a whole team — dispatch an orchestrator, parallel workers, and a reviewer across any LLM provider with cost budgets, cross-session memory, and a full audit trail.

---

What is xeno?

Claude Code is one agent talking to you. xeno is you directing a whole team.

You give xeno a brief. An orchestrator decomposes it. Workers execute in parallel with different tools and budgets. A reviewer gates the result. Every decision, tool call, and dollar spent lands in an audit trail you can query, replay, and analyze.

It runs on any provider — Anthropic API, OpenAI, local Ollama models (zero API cost), Vercel AI Gateway, or via the claude and codex CLIs. One wizard gets you up and running.

---

Features

Multi-agent execution

• Role hierarchy — orchestrator → delegator → worker → reviewer, each with scoped tools and budgets
• Per-role permission tiers — workers get fs_read_file; only the orchestrator can dispatch
• Kill + resume — stop a running job mid-flight, resume from the last checkpoint
• Replay — re-run any previous job under the same or different parameters

Memory

• Cross-session Mem0 recall — agents remember previous conversations and outcomes
• Team memory sharing — promote a run's memories to the whole team
• Layered scopes — per-user, per-team, and per-project memory queried together
• Ollama embeddings — run Mem0 locally with nomic-embed-text, no OpenAI account needed

Providers (6 backends)

Provider	Model family	Cost model
anthropic-api	Claude 3.x / 4.x	Pay per token
openai-api	GPT-4o, o1	Pay per token
ollama	Llama, Qwen, Mistral, …	Free (local)
ai-gateway	OpenAI-compatible gateway	Depends on gateway
claude-cli	Claude via claude CLI	Claude Pro/Max subscription
codex-cli	OpenAI Codex via codex CLI	Depends

Cost & quotas

• Per-role budget enforcement — jobs hard-stop when they exceed budget_usd_per_job
• Per-tenant quotas — submission gates + per-call spend gates with period rollover
• Full cost audit — every provider call records tokens_in, tokens_out, cost_usd

Team collaboration

• Multi-tenant — run isolated workspaces per user, team, or project
• Team management — xeno team create/join/invite/status/feed
• PR integration — open PRs tagged with X-Xeno-Run-Id, auto-promote memories on merge
• Webhook daemon — listen for GitHub merge events, promote team memories automatically

Live agent visualization

xeno viz <job_id> opens a live tree-and-timeline of an agent run in your browser. Each role's inner_loop emits viz events (start / tool / child-spawn / child-return / end) to a per-job WS channel; the React SPA renders them as an SVG tree with status colors + a swim-lane timeline. Clicking a node opens a detail drawer with the tool list, duration, child summaries, and a recursive /viz/<child_run_id> link to drill into spawned children. Both live (in-progress) and historic (completed) jobs render through the same view — historic events are seeded via GET /api/jobs/<id>/events on page load.

Developer UX

• Setup wizard — detects installed providers, runs smoke tests, writes ~/.xeno/config.toml
• Chat REPL — durable, tool-capable chat sessions with /history, /save, /switch, /kill
• XENO.md — drop a XENO.md in any project for per-project agent context (like CLAUDE.md)
• Skills — inject reusable skill sections into agent charters via ~/.xeno/skills/
• Telemetry — opt-in anonymous usage (24h gate, xeno telemetry opt-out at any time)

---

Install

pip install xeno-harness
# or, with uv (recommended):
uv pip install xeno-harness

Requires Python 3.12+. No Docker needed for local development — xeno bundles an embedded Postgres.

From source

git clone https://github.com/belonsavon-sys/agent-harness.git
cd agent-harness
uv sync
uv run xeno --help

---

First run

# Step 1: Run the setup wizard (detects your providers, runs smoke tests)
xeno setup

# Step 2: Try the chat REPL (works like Claude Code, but tools-capable)
xeno chat

# Step 3: Submit your first job
xeno run "Write a Python function that parses a CSV and returns the top 5 rows by a given column"

The wizard writes ~/.xeno/config.toml with your provider preference and tenant identity. You won't need to touch it again unless you add a new provider.

---

Key commands

Command	What it does
xeno setup	First-run wizard: detect providers, set identity, run smoke test
xeno reconfigure	Re-run the wizard (e.g. after adding Ollama)
xeno run "<brief>"	Submit a job; prints the report when done
xeno run "<brief>" --detach	Submit and return immediately; poll with xeno job <id>
xeno chat	Start an interactive chat session
xeno job <id>	Show status and full report for a job
xeno kill <id>	Stop a running job (checkpoint saved; resume any time)
xeno replay <id>	Re-run a previous job with the same brief
xeno board serve	Run the PM web UI (Kanban + Dashboard) on :7373
xeno board open	Open the PM UI in your default browser
xeno viz <job_id>	Open the live agent-tree viz for a job in your browser
xeno team create <name>	Create a team
xeno team join <invite-token>	Join a team via invite
xeno team feed	Tail the team activity feed
xeno quota	Show per-tenant spend and quota status
xeno providers configure	Add or change a provider
xeno analyze <id>	Token-usage breakdown for a job
xeno eval	Run the built-in eval suite (CI gate)
xeno telemetry status	Show telemetry opt-in state

---

Configuration

Environment variables

Copy .env.example to .env and fill in the keys you need:

cp .env.example .env
# Edit .env, then:
set -a; source .env; set +a

Variable	Required	Description
ANTHROPIC_API_KEY	For anthropic-api	Your Anthropic API key
OPENAI_API_KEY	For openai-api + Mem0	Your OpenAI API key
AI_GATEWAY_API_KEY	For ai-gateway	Vercel AI Gateway key

Per-project context

Drop a XENO.md at your project root. Agents read it automatically at the start of every run — like a CLAUDE.md but for xeno. Use it for:

• Project architecture overview
• Naming conventions
• What NOT to change
• Commands to know (npm run dev, pytest -q, etc.)

Skills

Place SKILL.md files in ~/.xeno/skills/<skill-name>/SKILL.md. Skills are injected into agent charters automatically when the agent's tools match the skill's allowed-tools list.

---

Tips

1. Use Ollama for free exploration. xeno providers configure --provider ollama sets up local models. No API costs for prototyping or development runs.

2. xeno chat for back-and-forth, xeno run for production. Chat persists conversation history and Mem0 recalls previous sessions. run is for one-shot jobs you want audited.

3. Set conservative worker budgets. Worker roles default to $0.05–$0.50 per job. The orchestrator gets more. Tune via ~/.xeno/config.toml before running expensive tasks.

4. Use xeno replay when a run fails partway. Replay re-runs the job from scratch but reuses the same run_id for lineage tracking. Cheaper than a full re-submit when the brief is right but the model wandered.

5. xeno analyze <id> shows where the cost went. Per-role, per-provider breakdown from the audit trail.

6. Team memory compounds. Every job automatically extracts memories via Mem0. Run xeno team feed after a sprint to see what the team's agents have learned.

7. xeno explain <id> reconstructs decisions. Like git blame for agent reasoning — see which recalled memories, tool calls, and prompts shaped each output.

---

Roadmap

xeno is under active development. Coming next:

• Project Management System — built-in task board where agents and humans are both team members; create, assign, and comment on tasks from the CLI or future web UI
• Live agent visualization — real-time process tree showing which agents are running, what tools they're using, and how cost is accumulating
• Knowledge graph — Obsidian-style node graph of memories, decisions, and agent interactions across all runs
• UX polish — improved terminal UI, keyboard shortcuts, and a Claude Code-inspired aesthetic

Track progress in docs/superpowers/roadmap-overview.md.

---

Development

# Install deps (Python 3.12+, uv required)
uv sync

# Run tests (~10s, no live API calls)
uv run pytest -q --ignore=tests/spikes

# Run with live provider calls (uses real API budget)
uv run pytest tests/spikes/ --run-live

# Lint + format check
uv run ruff check xeno/ tests/
uv run ruff format --check xeno/ tests/

Database

Tests use an embedded Postgres (pgserver) — no Docker needed. If you see shmget: No space left on device on macOS, raise the shared-memory caps:

sudo sysctl -w kern.sysv.shmmni=128 kern.sysv.shmseg=32

Commits

Follow Conventional Commits: feat:, fix:, docs:, chore:, refactor:. Releases are automated via release-please.

---

Repository layout

xeno/                  # Main package (Python 3.12+)
  agents/              # inner_loop, charters, dispatch
  cli/                 # CLI entry point and REPL
  db/                  # Embedded Postgres, migrations, connection pool
  identity/            # Keychain OAuth detection (macOS/Linux/Windows)
  memory/              # Mem0 service, layered recall
  providers/           # 6 LLM backends + cost tracking
  runtime/             # Budget, job queue, worker, kill/resume
  skills/              # Skill loader and index
  telemetry/           # Opt-in usage reporting
  team/                # Team management, quotas, PR integration

docs/superpowers/      # Specs, plans, spikes, and follow-ups
tests/                 # pytest suite (627 passing, 25 skipping)

---

License

MIT — see LICENSE.