Use Cases & Why Use It
If you regularly have more than one AI coding agent open — or you want unattended runs you can actually trust — XYZ Forge turns that into a coordinated, inspectable operations system instead of copy-paste between windows: specified work, collision-free lanes, verification gates, and a receipted record of what happened.
Why use XYZ
Local-first, no infra
Coordination is a local append-only event log — no server, no API keys for the kernel,
no remote dependency. One shared .tick/ directory per active run.
Verified beats plausible
Every phase boundary runs a real verification gate that must be able to start before turn 1. Done means a gate passed, not a model saying so.
Uses the subscriptions you have
Headless builders default to cost-blind, subscription-billed CLIs (Codex, agy). API-billed Claude is an explicit opt-in with a budget cap, never a silent default.
Inspectable state, not self-report
The whole run is a state machine you can read — event log, relay transcripts, typed escalation reasons — rather than a model's claim about what it did.
Designed to be reversible
Work lands on branches; relays write dated thread files plus the artifact under
review. Recovery is usually git checkout plus deleting a branch.
Collisions solved at the kernel
Path-scoped claims serialize overlapping edits between concurrent agents, so two sessions can't quietly shred the same file.
Deterministic before advisory
Anything expressible as a regex, schema, or file check is checked deterministically and may block. LLM review may warn, rank, or propose — it may never block.
Code & repo quality first
Two-tier QA pairs separate builder and reviewer models for whole-file per-task code audits, backed by deterministic on-disk gate receipts and orchestrator mechanical PR checks.
Docs are runtime state
Work has to be resumable from PROJECT/** alone, so drift between docs
and code is a defect with teeth, not project-management paperwork.
The operations loop — more than execution
The execution modes are one stage of a longer loop:
capture → rate → plan → preflight → execute → gate → land → record. The stages
before and after execution are what make unattended runs trustworthy:
| Stage | What it does |
|---|---|
| Capture / intake | Issues land as capture docs and parked rows in a release ledger, so work is written down before anyone asks an agent to do it. |
| Rate | pri / sev / appeal / effort scores decide what runs next — and why that. |
| Plan | The wave planner batches lanes with exact write-set intersection, zone caps, and dependency gating. |
| Preflight | Freshness probes, already-landed detection, and a readiness verdict before anything fires unattended. |
| Gate & land | Verification gates with CPU/wall/RSS caps at every boundary, on-disk gate receipts, and orchestrator mechanical PR sanity checks. |
| Record | A receipted release ledger (SQLite + a git-mergeable SQL dump) answers what shipped with evidence. |
What you can do with it
Consult — a cross-model second opinion
Fan one question out to Codex and agy in parallel; each answers independently in an isolated copy of the repo, and the answers are reconciled into one. Purely advisory, nothing modified. Lowest risk, fastest payoff — the recommended first run.
Relay — build and review until it's right
A Producer builds an artifact, a Reviewer critiques and proposes fixes, and they hand off back and forth until the artifact converges — replacing you as the copy-paste relay between two agent windows. Changes are confined to the relay thread file and the artifact.
Swarm — parallel lanes that don't collide
Several agents working concurrently on the same repo, each claiming a
non-overlapping, path-scoped lane through the tick kernel. Good for parallel
builds or parallel codebase recon, arranged by you across separate full clones or worktrees.
Marathon — the overnight queue
Build a queue of pre-flighted tasks during the day, then fire them as one long autonomous run — end-of-day or overnight. Every queued task is checked to be well-specified before anything runs unattended, and every phase boundary is gated. After an interruption, a read-only recovery report tells you exactly which commits are ungated.
AgentChorus — live sessions by compact ID
A serialized discussion between two or more live Claude/Codex sessions, joined through a collision-checked six-digit ID with exactly one active writer at a time. Local, not a chat server — every participant sees the same clone.
HQ — the multi-repo command center
Where tick coordinates agents inside one repo, HQ is the operator
front door across every repo on your device: resolve a fuzzy project name, report state, and
land intake on that repo's own governance rails. Read paths are safe; write paths preview
first.
Install the kernel anywhere
install.sh materializes the tick runtime into any other repo and
records it in a machine-local registry, so future versions can be pushed to installs that are
behind.
What you need
| Requirement | Notes |
|---|---|
| Node 18+ and git | The tick kernel and the test suite. |
| Python 3.8+ | Default runtime for the harness entry points (Bash fallback retained inline). |
| Codex CLI, agy CLI | For live Consult/Relay/Marathon turns — install and authenticate both before you start. |
| 16 GB RAM (unattended runs) | Recommended minimum for the serial marathon route; budget 1.5–2 GB per concurrent lane plus your target repo's own test-suite memory. |
| macOS | The platform XYZ ships for and gates on today; Linux and Windows are on the roadmap. |
For unattended runs, XYZ measured about 2.2 GB steady-state for a serial marathon on a 32 GB M1 Max; the README carries the full hardware-sizing guidance for parallel waves.