First three-agent run

This tutorial runs three parallel agents with conflict-aware wave scheduling.

Prerequisites

Complete Install: CLI on PATH, pytxo init, and pytxo doctor passing.

Configure tasks

Create a pytxo.toml in your project root. Start with two tasks that touch different files:

max_agents = 3

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

[[task]]
id = "build-a"
agent = "builder"
paths = ["src/a.ts"]

[[task]]
id = "build-b"
agent = "builder"
paths = ["src/b.ts"]

If tasks touch overlapping paths, Pytxo schedules them in separate waves automatically.

Dry-run (preflight)

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

Inspect the JSON output: waves array and conflicts list show how scheduling will behave before any agent runs.

Run agents

pytxo run --config pytxo.toml --cmd "echo hello-from-agent"

Each agent executes in its own git worktree. Default execution uses PTY backends so interactive shells behave correctly.

Inspect telemetry

pytxo status
pytxo logs --agent <run_uuid>:agent-0 --tail 20

Use agent IDs printed under status. Events are stored under .pytxo/data/.

Without a config file

For a quick smoke test:

pytxo run --agents 3 --cmd "echo pytxo"

Uses synthetic disjoint paths (src/agent-0.ts, etc.) so all three agents can run in one wave.

Learn more

• CLI reference: all commands and flags
• Three moats: Signal Core, Blast Shield, Race Shield
• Testing agent CLIs: contributor recipes from a source checkout