Metadata-Version: 2.4
Name: xeno-harness
Version: 4.2.0
Summary: Multi-agent autonomy harness with multi-provider support, per-role permission tiers, and Agent Harness Engineering observability.
Author-email: Pierre Belon-Savon <belonsavon@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.12
Requires-Dist: anthropic<1.0,>=0.40
Requires-Dist: argon2-cffi<26,>=23
Requires-Dist: claude-agent-sdk<1.0,>=0.1
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: litellm<1.85,>=1.84
Requires-Dist: mem0ai==0.1.116
Requires-Dist: pgserver<1.0,>=0.1
Requires-Dist: procrastinate<4.0,>=3.8.1
Requires-Dist: prompt-toolkit<4.0,>=3.0
Requires-Dist: psycopg2-binary<3.0,>=2.9
Requires-Dist: psycopg[binary,pool]<4.0,>=3.2
Requires-Dist: pydantic[email]<3.0,>=2.12
Requires-Dist: python-dotenv<2.0,>=1.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14,>=13
Requires-Dist: sqlparse<1.0,>=0.5
Requires-Dist: uvicorn[standard]<1.0,>=0.27
Requires-Dist: yoyo-migrations<9.0,>=8.2
Description-Content-Type: text/markdown

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

[![CI](https://github.com/belonsavon-sys/agent-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/belonsavon-sys/agent-harness/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/xeno-harness)](https://pypi.org/project/xeno-harness/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## 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

```bash
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

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

---

## First run

```bash
# 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:

```bash
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`](docs/superpowers/roadmap-overview.md).

---

## Development

```bash
# 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:

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

### Commits

Follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`. Releases are automated via [release-please](https://github.com/googleapis/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](LICENSE).
