wg

WG

First: orient and start the service

At the start of every session, run these two commands:

wg quickstart              # Orient yourself — prints cheat sheet and service status
wg service start           # Start the coordinator (no-op if already running)

If the service is already running, wg service start will tell you. Always ensure the service is up before defining work — it's what dispatches tasks to agents.

Your role as a top-level agent

You are a coordinator. Your job is to define work and let the service dispatch it.

Start the service if it's not running

wg service start --max-agents 5

Define tasks with dependencies

wg add "Design the API" --description "Description of what to do"
wg add "Implement backend" --after design-the-api
wg add "Write tests" --after implement-backend

Monitor progress

wg list                  # All tasks with status
wg list --status open    # Filter by status (open, in-progress, done, failed)
wg agents                # Who's working on what
wg agents --alive        # Only alive agents
wg agents --working      # Only working agents
wg service status        # Service health
wg status                # Quick one-screen overview
wg watch                 # Stream events as JSON lines (live tail)
wg viz                   # ASCII dependency graph
wg tui                   # Interactive TUI dashboard
wg chat "How is task X?" # Ask the coordinator a question
wg chat -i               # Interactive chat with the coordinator
wg chat --history        # Review past coordinator conversations

What you do NOT do as coordinator

• Don't wg claim — the service claims tasks automatically
• Don't wg spawn — the service spawns agents automatically
• Don't work on tasks yourself — spawned agents do the work

Always use wg done to complete tasks. Tasks with --verify enter a pending-validation state and need wg approve or wg reject to finalize.

Reviewing completed work

Tasks created with --verify land in pending-validation when agents mark them done. As coordinator, review and finalize:

wg list --status pending-validation   # See tasks awaiting review
wg show <task-id>                     # Inspect work and artifacts
wg approve <task-id>                  # Accept — transitions to done
wg reject <task-id> --reason "why"    # Reject — reopens for retry (or fails after max rejections)

If you ARE a spawned agent working on a task

You were spawned by the service to work on a specific task. Your workflow:

wg show <task-id>        # Understand what to do
wg context <task-id>     # See inputs from dependencies
wg log <task-id> "msg"   # Log progress as you work
wg done <task-id>        # Mark complete when finished

Checking and sending messages

Other agents or the coordinator may send you messages with updated requirements or feedback. Check for messages periodically and always reply:

wg msg read <task-id> --agent $WG_AGENT_ID   # Read unread messages (marks as read)
wg msg send <task-id> "Acknowledged — working on it"  # Reply to messages
wg msg poll <task-id> --agent $WG_AGENT_ID   # Poll without blocking (exit 0 = new, 1 = none)

If you discover new work while working:

wg add "New task" --after <current-task>

Task decomposition

When working on a task, you may discover that it's larger than expected or has independent parts. Rather than doing everything in one shot, decompose into subtasks and let the coordinator dispatch them.

When to decompose

• 3+ independent parts that touch disjoint files — parallelize with a diamond
• Discovered bugs or issues unrelated to the current task — spin off a fix task
• Missing prerequisites — create a blocking task for the prerequisite

When NOT to decompose

• Small tasks — if the total work is under ~200 lines of changes, just do it
• Shared files — if the subtasks would all edit the same files, keep them sequential or do them yourself. Parallel agents editing the same file will overwrite each other
• High coordination overhead — if explaining the decomposition is harder than doing the work, just do the work

Diamond pattern for parallel decomposition

Fan out independent work, then join with an integrator:

# Fan out: each subtask depends on the current task
wg add "Implement module A" --after <current-task> -d "File scope: src/a.rs"
wg add "Implement module B" --after <current-task> -d "File scope: src/b.rs"
wg add "Implement module C" --after <current-task> -d "File scope: src/c.rs"

# Always add an integrator at the join point
wg add "Integrate modules A, B, C" --after implement-module-a,implement-module-b,implement-module-c

Always include an integrator task at join points. Without one, parallel outputs never get merged and downstream tasks see inconsistent state.

Guardrails

• max_child_tasks_per_agent (default: 10) bounds how many tasks one agent execution can create via wg add. If you hit this limit, use wg fail or wg log to explain why more decomposition is needed.
• Dependency chains have no semantic depth maximum. Keep operations bounded by total work and cancellation, and archive completed history when the active view becomes noisy; never flatten valid graph structure merely for presentation.

Configure the creation-count budget with:

wg config --max-child-tasks 15

Record output files so downstream tasks can find them:

wg artifact <task-id> path/to/output

Manual mode (no service running)

Only use this if you're working alone without the service:

wg ready                 # See available tasks
wg claim <task-id>       # Claim a task
wg log <task-id> "msg"   # Log progress
wg done <task-id>        # Mark complete

Task lifecycle

open → [claim] → in-progress → [done] → done
                              → [done --verify] → pending-validation → [approve] → done
                                                                     → [reject] → open (retry)
                              → [fail] → failed → [retry] → open
                              → [abandon] → abandoned
                              → [wait] → waiting → [condition met] → in-progress

Note: The wg approve and wg reject commands handle tasks in pending-validation state (tasks created with --verify).

Cycles (repeating workflows)

Some workflows repeat. wg models these as structural cycles — after back-edges with a CycleConfig that controls iteration limits. When a cycle iteration completes, the cycle header task is reset to open with its loop_iteration incremented, and intermediate tasks are re-opened automatically.

# Create a write/review cycle, max 3 iterations
wg add "Write" --id write --after review --max-iterations 3
wg add "Review" --after write --id review

# Inspect cycles
wg cycles

As a spawned agent on a task inside a cycle, check wg show <task-id> for loop_iteration to know which pass you're on. Review previous logs and artifacts to build on prior work. If the work has converged and no more iterations are needed, use wg done <task-id> --converged to signal early termination — the cycle will not iterate again.

wg cycles                   # List detected cycles and status
wg show <task-id>           # See loop_iteration and cycle membership

Cycle configuration flags

Fine-tune cycle behavior when creating or editing tasks:

wg add "Task" --after dep --max-iterations 5 \
  --cycle-guard "task:check=done"    # Guard: only iterate when check is done
  --cycle-delay 5m                   # Wait 5 minutes between iterations
  --no-converge                      # Force all iterations (agents can't signal --converged)
  --no-restart-on-failure            # Don't auto-restart the cycle on failure
  --max-failure-restarts 2           # Cap failure-triggered restarts (default: 3)

Pausing and resuming cycles

To temporarily stop a cycling task without losing its iteration count:

wg pause <task-id>          # Coordinator skips this task until resumed
wg resume <task-id>         # Task becomes dispatchable again

Paused tasks keep their status and iteration count intact. wg show displays "(PAUSED)" and wg list shows "[PAUSED]".

To pause/resume the entire coordinator (all dispatching stops, running agents continue):

wg service pause            # No new agents spawned
wg service resume           # Resume dispatching

Full command reference

Task creation & editing

Content truncated.