Collision demo

This tutorial is the sixty-second Race + Blast proof: overlapping work is detected before execution, independent work runs together in isolated copies, and nothing lands in your real checkout until you approve.

Prerequisites

Complete Install: CLI on PATH, then pytxo doctor.

No coding-agent API keys are required for the dry-run and echo smoke below. For a natural-language mission with real CLIs, see First mission.

Option A: use the repo fixture

From a Pytxo source checkout:

cd tooling/demos/collision
git init
git add -A && git commit -m "collision demo" --allow-empty
pytxo trust orbit
pytxo run --config pytxo.toml --dry-run

Option B: paste this config

Create pytxo.toml in any trusted git repo:

max_agents = 3
permission_profile = "orbit"
isolation = "worktree"

[[agent]]
name = "demo"
paths = ["src/**"]
cli_adapter = "generic"

[[task]]
id = "touch-shared-a"
agent = "demo"
paths = ["src/shared.ts"]

[[task]]
id = "touch-shared-b"
agent = "demo"
paths = ["src/shared.ts"]

[[task]]
id = "touch-alone"
agent = "demo"
paths = ["src/alone.ts"]

Dry-run (preflight)

pytxo run --config pytxo.toml --dry-run

Before any process starts, stderr summarizes:

• Isolated copies (Blast)
• Overlapping paths wait (Race)
• Wave count and conflict pairs

JSON fields to inspect:

That is Race Shield: overlapping path claims do not run together.

Run (still safe)

pytxo run --config pytxo.toml --cmd "echo pytxo-collision-demo"

Each agent executes in its own git worktree (Blast). The echo command does not rewrite your real checkout. Inspect:

pytxo status

Real agents next

When Claude Code, Codex, or Cursor CLI is on PATH:

pytxo mission "Add a one-line comment to src/shared.ts and a unit test"

Same isolation and wave rules; you still approve the flush. See First mission and Desktop History → Review package.

Learn more

• First mission
• Three moats: Blast, Race, Signal
• CLI reference