wg

name	wg
description	Use this skill for task coordination with WG. Triggers include "wg", task graphs, multi-step projects, tracking dependencies, coordinating agents, or when you see a .wg directory.

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

Two guardrails prevent runaway decomposition:

• max_child_tasks_per_agent (default: 10) — max tasks a single agent can create via wg add. If you hit this limit, the system tells you. Use wg fail or wg log to explain why more decomposition is needed.
• max_task_depth (default: 8) — max depth of --after chains from root tasks. Prevents infinite decomposition chains. If you hit this, create tasks at the current level instead of nesting deeper.

Configure with:

wg config --max-child-tasks 15
wg config --max-task-depth 10

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 task (-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" --paused	Create task in paused state
wg add "X" --delay 1h	Task becomes ready after delay (30s, 5m, 1h, 1d)
wg add "X" --not-before "2026-01-15T09:00:00Z"	Schedule task for specific time (ISO 8601)
wg add "X" --no-place	Skip automatic placement analysis
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	Publish single task only (skip subgraph propagation)
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)

Command	Purpose
wg server init	Initialize multi-user server setup (dry-run by default)
wg server init --apply	Actually apply server setup changes
wg server init --group <name>	Unix group name (default: wg-)
wg server init --user <name>	Add a user to the project group (repeatable)
wg server init --ttyd	Generate ttyd web terminal configuration
wg server init --caddy	Generate Caddy reverse-proxy configuration
wg server init --ttyd-port 7681	Set port for ttyd web terminal
wg server connect	Create or attach to a user's tmux session
wg server connect --user <name>	Specify user (defaults to $WG_USER)

Agency (roles, tradeoffs, agents)

Command	Purpose
wg agency init	Bootstrap agency with starter roles, tradeoffs, and agents
wg agency stats	Performance analytics
wg agency stats --by-model	Per-model score breakdown
wg agency stats --by-task-type	Per-task-type score breakdown
wg role add <id>	Create a role
wg role list	List roles
wg role show <id>	Show role details
wg role edit <id>	Edit a role
wg role rm <id>	Remove a role
wg tradeoff add <id>	Create a tradeoff
wg tradeoff list	List tradeoffs
wg tradeoff show <id>	Show tradeoff details
wg tradeoff edit <id>	Edit a tradeoff
wg tradeoff rm <id>	Remove a tradeoff
wg agent create	Create agent (role+tradeoff pairing)
wg agent list	List agents
wg agent show <hash>	Show agent details
wg agent rm <hash>	Remove an agent
wg agent lineage <hash>	Show agent ancestry
wg agent performance <hash>	Show agent performance
wg assign <task> <agent-hash>	Assign agent to task
wg assign <task> --auto	Auto-select agent via LLM
wg assign <task> --clear	Clear assignment
wg evaluate run <task>	Trigger LLM-based evaluation of a completed task
wg evaluate record --task <id> --score <n> --source <tag>	Record evaluation from external source
wg evaluate show	Show evaluation history (filter by --task, --agent, --source)
wg evolve	Trigger evolution cycle
wg evolve --strategy mutation --budget 3	Targeted evolution
wg evolve apply <synthesis-file>	Apply a synthesis-result.json from a fan-out run

Federation (cross-repo agency sharing)

Command	Purpose
wg agency remote add <name> <path>	Add a named remote agency store
wg agency remote remove <name>	Remove a named remote
wg agency remote list	List configured remotes
wg agency remote show <name>	Show remote details and entity counts
wg agency scan <root>	Scan filesystem for agency stores
wg agency pull <source>	Pull entities from another agency store
wg agency push <target>	Push local entities to another agency store
wg agency merge <sources...>	Merge entities from multiple stores

Peer WG instances (cross-repo communication)

Command	Purpose
wg peer add <name> <path>	Register a peer WG instance
wg peer remove <name>	Remove a registered peer
wg peer list	List all configured peers with service status
wg peer show <name>	Show detailed info about a peer
wg peer status	Quick health check of all peers

Run snapshots

Command	Purpose
wg runs list	List all run snapshots
wg runs show <id>	Show details of a specific run
wg runs restore <id>	Restore graph from a run snapshot
wg runs diff <id>	Diff current graph against a run snapshot

Functions (reusable workflow patterns)

Command	Purpose
wg func list	List available functions
wg func show <id>	Show function details and required inputs
wg func extract <task-id>...	Extract a function from completed task(s)
wg func apply <id> --input key=value	Create tasks from a function with provided inputs
wg func bootstrap	Bootstrap the extract-function meta-function
wg func make-adaptive <id>	Upgrade a generative function to adaptive (adds run memory)

Traces (execution history & sharing)

Command	Purpose
wg trace show <id>	Show the execution history of a task
wg trace export --visibility <zone>	Export trace data filtered by visibility zone
wg trace import <file>	Import a trace export file as read-only context

Model & provider management

Command	Purpose
wg model list	Show all models in the registry (built-in + user-defined)
wg model add	Add or update a model in the config registry
wg model remove <id>	Remove a model from the config registry
wg model set-default <id>	Set the default model for agent dispatch
wg model routing	Show per-role model routing configuration
wg model set <role> <model>	Set the model for a specific dispatch role
wg models list	List models from the local registry
wg models search <query>	Search models from OpenRouter by name/ID/description
wg models remote	List all models available on OpenRouter
wg models add	Add a custom model to the local registry
wg models set-default <id>	Set the default model
wg models init	Initialize models.yaml with defaults
wg endpoints list	List all configured LLM endpoints
wg endpoints add	Add a new LLM endpoint
wg endpoints remove <name>	Remove an endpoint by name
wg endpoints set-default <name>	Set an endpoint as the default
wg endpoints test	Test endpoint connectivity (hits /models API)
wg key set <provider>	Configure an API key for a provider
wg key check	Validate API key availability and status
wg key list	Show key configuration status for all providers

Artifacts & resources

Command	Purpose
wg artifact <task> <path>	Record output file
wg artifact <task>	List task artifacts
wg artifact <task> <path> --remove	Remove artifact
wg resource add <id> --type money --available 1000 --unit usd	Add resource
wg resource list	List resources
wg match <task>	Find capable agents

Skills

Command	Purpose
wg skill list	List all skills used across tasks
wg skill task <id>	Show skills for a specific task
wg skill find <name>	Find tasks requiring a specific skill
wg skill install	Install the WG Claude Code skill to ~/.claude/skills/wg/

Setup & configuration

Command	Purpose
wg init	Initialize a new WG directory in the current directory
wg setup	Interactive configuration wizard for first-time setup
wg config --show	Show current config
wg config --list	Show merged config with source annotations (global/local/default)
wg config --init	Create default config
wg config --global --executor claude	Write to global config (~/.wg/config.toml)
wg config --local --model opus	Write to local config (default for writes)
wg config --executor claude	Set executor
wg config --model opus	Set default model
wg config --max-agents 5	Set agent limit
wg config --max-coordinators 2	Set max concurrent coordinator sessions
wg config --coordinator-interval 30	Set coordinator poll interval in seconds
wg config --poll-interval 60	Set service daemon background poll interval in seconds
wg config --coordinator-executor claude	Set coordinator executor
wg config --coordinator-model opus	Set coordinator model
wg config --coordinator-provider openrouter	Set coordinator provider
wg config --auto-evaluate true	Enable auto-evaluation
wg config --auto-assign true	Enable auto-assignment
wg config --auto-place true	Enable automatic placement analysis on new tasks
wg config --auto-create true	Enable automatic creator agent invocation
wg config --auto-triage true	Enable automatic triage of dead agents
wg config --creator-agent <hash>	Set creator agent (content-hash)
wg config --creator-model <model>	Set model for creator agents
wg config --assigner-model <model>	Set model for assigner agents
wg config --evaluator-model <model>	Set model for evaluator agents
wg config --evolver-model <model>	Set model for evolver agents
wg config --assigner-agent <hash>	Set assigner agent (content-hash)
wg config --evaluator-agent <hash>	Set evaluator agent (content-hash)
wg config --evolver-agent <hash>	Set evolver agent (content-hash)
wg config --triage-model haiku	Set model for triage (default: haiku)
wg config --triage-timeout 30	Set timeout in seconds for triage calls
wg config --triage-max-log-bytes 50000	Max bytes to read from agent output log for triage
wg config --retention-heuristics "policy"	Set retention heuristics (prose policy for evolver)
wg config --eval-gate-threshold 0.7	Set eval gate threshold (0.0-1.0)
wg config --eval-gate-all true	Apply eval gate to all tasks (not just eval-gate tagged)
wg config --flip-enabled true	Enable FLIP (roundtrip intent fidelity) evaluation
wg config --flip-inference-model <m>	Model for FLIP inference phase
wg config --flip-comparison-model <m>	Model for FLIP comparison phase
wg config --flip-verification-threshold 0.7	FLIP score threshold for Opus verification
wg config --flip-verification-model opus	Model for FLIP-triggered verification
wg config --chat-history true	Enable chat history persistence
wg config --chat-history-max 100	Max chat history entries
wg config --retry-context-tokens 2000	Max tokens of previous-attempt context on retry
wg config --max-child-tasks 15	Max tasks a single agent can create per execution
wg config --max-task-depth 10	Max depth of task dependency chains from root
wg config --install-global	Install project config as global default
wg config --install-global --force	Skip confirmation when overwriting existing global config
wg config --viz-edge-color mixed	Viz edge color style (gray/white/mixed)
wg config --tui-counters uptime,active	TUI time counters (uptime, cumulative, active, session)
wg config --tiers	Show current tier-to-model assignments
wg config --tier standard=gpt-4o	Set which model a tier uses
wg config --models	Show all model routing assignments (per-role)
wg config --set-model <role> <model>	Set model for a dispatch role
wg config --set-provider <role> <provider>	Set provider for a dispatch role
wg config --set-endpoint <role> <endpoint>	Bind a named endpoint to a dispatch role
wg config --role-model <role>=<model>	Set model for dispatch role (key=value syntax)
wg config --role-provider <role>=<provider>	Set provider for dispatch role (key=value syntax)
wg config --set-key <provider> --file <path>	Set API key file for a provider
wg config --check-key	Check OpenRouter API key validity
wg config --registry	Show all model registry entries (built-in + user-defined)
wg config --registry-add --id <id> --provider <p> --reg-model <m> --reg-tier <t>	Add model to registry
wg config --registry-add --endpoint <url> --context-window <n> --cost-input <n> --cost-output <n>	Registry add with optional endpoint/cost fields
wg config --registry-remove <id>	Remove model from registry
wg config --matrix --homeserver <url> --room <room>	Configure Matrix integration
wg config --matrix --username <user> --password <pass>	Set Matrix credentials
wg config --matrix --access-token <token>	Set Matrix access token directly

Output options

All commands support --json for structured output. Run wg --help for the quick list or wg --help-all for every command.

Executor and model awareness

Environment variables

Every spawned agent receives these environment variables:

Variable	Description
WG_TASK_ID	The task ID you're working on
WG_AGENT_ID	Your agent ID
WG_EXECUTOR_TYPE	Executor type: claude, amplifier, or shell
WG_MODEL	Model you're running on (e.g. opus, sonnet, haiku) — set when a model is configured
WG_USER	The current user identity
WG_ENDPOINT / WG_ENDPOINT_NAME	The endpoint name (set when an endpoint is configured)
WG_LLM_PROVIDER	The LLM provider (e.g. anthropic, openrouter)
WG_ENDPOINT_URL	The endpoint URL (set when an endpoint is configured)
WG_API_KEY	The API key for the endpoint (set when an endpoint is configured)
WG_WORKTREE_PATH	Path to the agent's isolated git worktree (set when worktree isolation is active)
WG_BRANCH	The worktree branch name (set when worktree isolation is active)
WG_PROJECT_ROOT	Path to the main project root (set when worktree isolation is active)

Multi-executor awareness

You may be running under different executors:

• claude — Claude Code CLI (claude --print). You have full access to Claude Code tools (file editing, bash, etc).
• amplifier — Amplifier multi-agent runtime. You have access to installed amplifier bundles and can delegate to sub-agents.
• shell — Direct shell execution for scripted tasks.

Check $WG_EXECUTOR_TYPE to know which executor you're running under if your behavior should differ.

Model awareness

The $WG_MODEL variable tells you what model you're running on. Different tasks may use different models based on complexity (model hierarchy: task.model > executor.model > coordinator.model).

Calibrate your approach to your model tier:

• Frontier models (opus): Tackle complex multi-file refactors, architectural decisions, nuanced trade-offs.
• Mid-tier models (sonnet): Good for standard implementation, bug fixes, well-scoped features.
• Fast models (haiku): Best for simple, well-defined tasks — lookups, single-file edits, formatting.

If a task feels beyond your model's capability, use wg fail with a clear reason rather than producing low-quality output.

Provider awareness

Tasks can specify a provider using the provider:model format in --model (e.g., --model openai:gpt-4o). Supported providers: anthropic, openai, openrouter, local. The provider resolves at dispatch time: task.provider > config default. The standalone --provider flag is deprecated.

Execution modes

Tasks can specify --exec-mode to control what tools the agent receives:

Mode	Description	Use Case
full	Full Claude Code tools (file editing, bash, etc.) — default	Standard implementation, debugging
light	Read-only tools (no file writes, no destructive commands)	Code review, analysis, audit
bare	Only wg CLI instructions, no extra tools	Meta-tasks, workflow management
shell	No LLM — direct shell execution of exec command	Scripted automation, CI/CD

wg add "Review code" --exec-mode light
wg add "Run tests" --exec-mode shell
wg exec run-tests --set "cargo test"

Context scopes

Tasks can specify a --context-scope that controls how much context the agent receives in its prompt:

Scope	Description	Use Case
clean	Bare executor — no WG CLI instructions	Pure computation, translation, writing
task	Task-aware with WG workflow instructions (default)	Standard implementation, bug fixes
graph	Adds project description, 1-hop neighborhood, status summary	Integration, cross-component review
full	Adds full graph summary, CLAUDE.md, system preamble	Meta-tasks, workflow design

Set scope when creating or editing tasks:

wg add "Translate document" --context-scope clean
wg edit <task-id> --context-scope graph

Resolution priority: task > role default > coordinator config > "task" (default).

Amplifier bundles (amplifier executor only)

When running under the amplifier executor (WG_EXECUTOR_TYPE=amplifier), you can use installed amplifier bundles for specialized capabilities. Delegate to sub-agents when:

• The subtask is independent and well-scoped (e.g. "write tests for module X")
• Parallel execution would speed things up
• The subtask needs a different skill set than your current context

Do the work yourself when:

• The task is simple and sequential
• Context from prior steps is critical and hard to transfer
• Coordination overhead would exceed the work itself

Multi-coordinator support

The service supports multiple concurrent coordinator sessions. Each coordinator manages its own scope of tasks and agents.

wg service create-coordinator        # Create a new coordinator session
wg service stop-coordinator <id>     # Stop a coordinator (kill agent, reset to Open)
wg service archive-coordinator <id>  # Archive a coordinator (mark as Done)
wg service delete-coordinator <id>   # Delete a coordinator session
wg config --max-coordinators 4       # Set max concurrent coordinators (default: 4)
wg chat --coordinator 1 "message"    # Target a specific coordinator