| 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
wg service start
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
wg list --status open
wg agents
wg agents --alive
wg agents --working
wg service status
wg status
wg watch
wg viz
wg tui
wg chat "How is task X?"
wg chat -i
wg chat --history
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
wg show <task-id>
wg approve <task-id>
wg reject <task-id> --reason "why"
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>
wg context <task-id>
wg log <task-id> "msg"
wg done <task-id>
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
wg msg send <task-id> "Acknowledged — working on it"
wg msg poll <task-id> --agent $WG_AGENT_ID
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:
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"
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
wg claim <task-id>
wg log <task-id> "msg"
wg done <task-id>
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.
wg add "Write" --id write --after review --max-iterations 3
wg add "Review" --after write --id review
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
wg show <task-id>
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"
--cycle-delay 5m
--no-converge
--no-restart-on-failure
--max-failure-restarts 2
Pausing and resuming cycles
To temporarily stop a cycling task without losing its iteration count:
wg pause <task-id>
wg resume <task-id>
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
wg service resume
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
wg service stop-coordinator <id>
wg service archive-coordinator <id>
wg service delete-coordinator <id>
wg config --max-coordinators 4
wg chat --coordinator 1 "message"
