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

Command	Purpose
wg add "Title" --description "Desc"	Create a visible draft (-d alias for --description)
wg add "X" --after Y	Create task with dependency
wg add "X" --after a,b,c	Multiple dependencies (comma-separated)
wg add "X" --skill rust --input src/foo.rs --deliverable docs/out.md	Task with skills, inputs, deliverables
wg add "X" --model haiku	Task with preferred model
wg add "X" --model openai:gpt-4o	Task with provider:model format
wg add "X" --context-scope clean	Set prompt context scope (clean/task/graph/full)
wg add "X" --exec-mode light	Set execution weight (full/light/bare/shell)
wg add "X" --verify "Tests pass"	Task requiring review before completion
wg add "X" --tag important --hours 2	Tags and estimates
wg add "X" --cost 50	Estimated cost
wg add "X" --assign <agent-hash>	Assign to an agent at creation
wg add "X" --max-retries 3	Maximum retries on failure
wg add "X" --visibility public	Visibility zone (internal/public/peer)
wg add "X" --after Y --max-iterations 3	Create cycle header with max 3 iterations
wg add "X" --delay 1h	Draft with a delayed eligibility time (publish separately)
wg add "X" --not-before "2026-01-15T09:00:00Z"	Schedule task for specific time (ISO 8601)
wg add "X" --place-near a,b	Placement hint: near these tasks
wg add "X" --place-before a,b	Placement hint: before these tasks
wg add "X" --repo peer-name	Create task in a peer wg (by name or path)
wg edit <id> --title "New" --description "New"	Edit task fields
wg edit <id> --add-after X --remove-after Y	Modify dependencies
wg edit <id> --add-after X --max-iterations 3	Add cycle back-edge
wg edit <id> --add-tag T --remove-tag T	Modify tags
wg edit <id> --add-skill S --remove-skill S	Modify skills
wg edit <id> --model sonnet	Change preferred model
wg edit <id> --model openai:gpt-4o	Change model (use provider:model format)
wg edit <id> --context-scope graph	Change context scope
wg edit <id> --exec-mode bare	Change execution weight
wg edit <id> --verify "cargo test passes"	Set or update verification criteria
wg edit <id> --visibility peer	Set visibility zone (internal/public/peer)
wg edit <id> --cycle-guard "task:check=done"	Set cycle guard condition
wg edit <id> --cycle-delay 5m	Set delay between cycle iterations
wg edit <id> --delay 30m	Set scheduling delay
wg edit <id> --not-before "2026-03-20T00:00:00Z"	Set absolute schedule
wg edit <id> --no-converge	Force all cycle iterations
wg edit <id> --no-restart-on-failure	Disable cycle restart on failure
wg edit <id> --max-failure-restarts 2	Cap failure-triggered restarts
wg edit <id> --allow-cycle	Allow cycle creation without CycleConfig (overrides cycle detection guard)
wg add-dep <task> <dep>	Add a dependency edge between two existing tasks
wg rm-dep <task> <dep>	Remove a dependency edge between two tasks

Task state transitions

Command	Purpose
wg claim <id>	Claim task (in-progress)
wg unclaim <id>	Release claimed task (back to open)
wg done <id>	Complete task
wg done <id> --converged	Complete task and signal cycle convergence
wg approve <id>	Approve a task in pending-validation (transitions to done)
wg reject <id> --reason "why"	Reject a task in pending-validation (reopens for retry)
wg publish <id>	Publish a draft task (validates deps, resumes subgraph)
wg publish <id> --only	Explicitly release one visible draft for dispatch
wg pause <id>	Pause task (coordinator skips it)
wg resume <id>	Resume a paused task
wg wait <id> --until "condition"	Park task as Waiting until condition is met
wg wait <id> --until "task:dep=done"	Wait for another task to complete
wg wait <id> --until "timer:5m"	Wait for a timer duration
wg wait <id> --until "message"	Wait for a message
wg wait <id> --until "human-input"	Wait for a human message
wg wait <id> --until "file:path"	Wait for a file to change
wg wait <id> --checkpoint "summary"	Save progress checkpoint when parking
wg fail <id> --reason "why"	Mark task failed
wg retry <id>	Retry failed task
wg abandon <id> --reason "why"	Abandon permanently
wg requeue <id> --reason "why"	Requeue in-progress task for failed-dependency triage (resets to open)
wg reclaim <id> --from old --to new	Reassign from dead agent

Querying & viewing

Command	Purpose
wg list	All tasks with status
wg list --status open	Filter: open, in-progress, done, failed, abandoned
wg ready	Tasks available to work on
wg show <id>	Full task details
wg blocked <id>	What's blocking a task
wg why-blocked <id>	Full transitive blocking chain
wg context <id>	Inputs from dependencies
wg context <id> --dependents	Tasks depending on this one's outputs
wg log <id> --list	View task log entries
wg impact <id>	What depends on this task
wg status	Quick one-screen overview
wg discover	Show recently completed tasks and artifacts (last 24h)
wg discover --since 7d	Custom time window (e.g. 30m, 24h, 7d)
wg discover --with-artifacts	Include artifact paths in output

Visualization

Command	Purpose
wg viz	ASCII dependency graph of open tasks
wg viz [TASK_ID]...	Show only subgraphs containing specified tasks
wg viz --all	Include done tasks
wg viz --status done	Filter by status
wg viz --dot	Graphviz DOT output
wg viz --mermaid	Mermaid diagram
wg viz --critical-path	Highlight critical path
wg viz --dot -o graph.png	Render to file
wg viz --show-internal	Show internal tasks (assign-, evaluate-) normally hidden
wg viz --no-tui	Force static output even when stdout is interactive
wg tui	Interactive TUI dashboard
wg tui-dump	Dump current TUI screen contents (requires a running wg tui)

Monitoring & event streaming

Command	Purpose
wg watch	Stream wg events as JSON lines
wg watch --event task_state	Filter by event type (task_state, evaluation, agent, all)
wg watch --task <id>	Filter events to a specific task (prefix match)
wg watch --replay 10	Include N recent historical events before streaming

Analysis & metrics

Command	Purpose
wg analyze	Comprehensive health report
wg check	Graph validation (cycles, orphans)
wg structure	Entry points, dead ends, high-impact roots
wg bottlenecks	Tasks blocking the most work
wg critical-path	Longest dependency chain
wg cycles	Cycle detection and classification
wg velocity --weeks 8	Completion velocity over time
wg aging	Task age distribution
wg forecast	Completion forecast from velocity
wg workload	Agent workload balance
wg resources	Resource utilization
wg cost <id>	Cost including dependencies
wg coordinate	Ready tasks for parallel execution
wg trajectory <id>	Optimal claim order for context
wg next --actor <id>	Best next task for an agent

Service & agents

Command	Purpose
wg service start	Start coordinator daemon
wg service start --max-agents 5	Start with parallelism limit
wg service stop	Stop daemon
wg service restart	Restart daemon (graceful stop then start)
wg service pause	Pause coordinator (running agents continue, no new spawns)
wg service resume	Resume coordinator dispatching
wg service status	Check daemon health
wg service reload	Reload daemon configuration without restarting
wg service tick	Run a single coordinator tick (debug mode)
wg service create-coordinator	Create a new coordinator session
wg service delete-coordinator	Delete a coordinator session
wg service archive-coordinator	Archive a coordinator session (mark as Done)
wg service stop-coordinator	Stop a coordinator session (kill agent, reset to Open)
wg service freeze	SIGSTOP all running agents and pause coordinator
wg service thaw	SIGCONT all frozen agents and resume coordinator
wg service interrupt-coordinator	Interrupt a coordinator's current generation
wg agents	List all agents
wg agents --alive	Only alive agents
wg agents --working	Only working agents
wg agents --dead	Only dead agents
wg spawn <id> --executor claude	Manually spawn agent
wg spawn <id> --executor claude --model haiku	Spawn with model override
wg kill <agent-id>	Kill an agent
wg kill --all	Kill all agents
wg kill <id> --force	Force kill (SIGKILL)
wg dead-agents --cleanup	Unclaim dead agents' tasks
wg dead-agents --remove	Remove from registry
wg dead-agents --purge	Purge dead/done/failed agents from registry
wg dead-agents --purge --delete-dirs	Also delete agent work directories when purging
wg dead-agents --threshold 30	Override heartbeat timeout threshold (minutes)
wg heartbeat <agent-id>	Record agent heartbeat
wg heartbeat --check	Check for stale agents (no heartbeat within threshold)
wg heartbeat --threshold 10	Override stale threshold in minutes (default: 5)

Messaging

Command	Purpose
wg msg send <task> "message"	Send a message to a task/agent
wg msg list <task>	List all messages for a task
wg msg read <task> --agent <id>	Read unread messages (marks as read)
wg msg poll <task> --agent <id>	Poll for new messages (exit code 0 = new, 1 = none)

User boards

Command	Purpose
wg user init	Create a user board for the current user
wg user init <name>	Create a user board for a specific user
wg user list	List all user boards (active and archived)
wg user archive	Archive the active board and create a successor

Provider profiles

Command	Purpose
wg profile set <name>	Set the active provider profile
wg profile show	Show current profile and resolved model mappings
wg profile list	List available profiles
wg profile refresh	Refresh model data from OpenRouter and recompute rankings

Cost tracking

Command	Purpose
wg spend	Show token usage and estimated cost summaries
wg spend --today	Show only today's spend
wg openrouter status	Show OpenRouter API key status and usage
wg openrouter session	Show session cost summary
wg openrouter set-limit	Set cost cap limits

Chat (coordinator interaction)

Command	Purpose
wg chat "message"	Send a message to the coordinator
wg chat -i	Interactive REPL mode
wg chat --history	Show chat history
wg chat --clear	Clear chat history
wg chat --attachment path/to/file	Attach a file to the message
wg chat --coordinator 1	Target a specific coordinator (multi-coordinator)

Notifications & integrations

Command	Purpose
wg notify <task>	Send task notification to Matrix room
wg notify <task> --room "#room"	Target specific Matrix room
wg notify <task> -m "message"	Include custom message with notification
wg matrix listen	Start Matrix message listener
wg matrix send "message"	Send a message to a Matrix room
wg matrix status	Show Matrix connection status
wg matrix login	Login with password (caches access token)
wg matrix logout	Logout and clear cached credentials
wg telegram listen	Start Telegram bot listener
wg telegram send "message"	Send a message to configured Telegram chat
wg telegram status	Show Telegram configuration status

Housekeeping & maintenance

Command	Purpose
wg compact	Distill graph state into context.md
wg sweep	Detect and recover orphaned in-progress tasks with dead agents
wg sweep --dry-run	Preview orphaned tasks without fixing
wg checkpoint <task> -s "summary"	Save checkpoint for context preservation
wg checkpoint <task> --list	List checkpoints for a task
wg stats	Show time counters and agent statistics
wg gc	Remove terminal tasks (done/abandoned/failed) from the graph
wg archive	Archive completed tasks
wg archive --dry-run	Preview what would be archived
wg archive --older 30d	Only archive old completions
wg archive --list	List archived tasks
wg reschedule <id> --after 24	Delay task 24 hours
wg reschedule <id> --at "2025-01-15T09:00:00Z"	Schedule at specific time
wg plan --budget 500 --hours 20	Plan within constraints
wg exec <task>	Execute a task's shell command (claim + run + done/fail)
wg exec <task> --set "cargo test"	Set the exec command for a task
wg exec <task> --clear	Clear the exec command
wg exec <task> --dry-run	Show what would be executed
wg replay	Snapshot graph, selectively reset tasks, re-execute with different model
wg replay --failed-only	Only reset failed/abandoned tasks
wg replay --below-score 0.7	Only reset tasks with evaluation score below threshold
wg replay --tasks a,b,c	Reset specific tasks plus transitive dependents
wg replay --subgraph <id>	Only replay tasks in subgraph rooted at given task
wg replay --keep-done 0.9	Preserve done tasks scoring above threshold (default: 0.9)
wg replay --plan-only	Dry run: show what would be reset

Screencast (TUI recording)

Command	Purpose
wg screencast render --trace <file> --output <file>	Render a TUI event trace into an asciinema .cast file
wg screencast render --compress-idle 5:2	Idle compression ratio (gaps >5s compressed to 2s)
wg screencast render --target-duration 30	Target total duration in seconds
wg screencast render --width 120 --height 36	Set terminal dimensions
wg screencast autopilot	Launch autopilot that drives the TUI for screencast recording
wg screencast autopilot --output demo.cast	Set output .cast file path
wg screencast autopilot --cols 80 --rows 24	Set terminal dimensions
wg screencast autopilot --duration 60	Max recording duration in seconds

Server (multi-user setup)