Wg

workgraph

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. Workgraph 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

Task state transitions

Querying & viewing

Visualization

Monitoring & event streaming

Analysis & metrics

Service & agents

Messaging

Chat (coordinator interaction)

Notifications & integrations

Housekeeping & maintenance

Screencast (TUI recording)

Server (multi-user setup)

Agency (roles, tradeoffs, agents)

Federation (cross-repo agency sharing)

Peer workgraphs (cross-repo communication)

Run snapshots

Functions (reusable workflow patterns)

Traces (execution history & sharing)

Model & provider management

Artifacts & resources

Skills

Setup & configuration

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:

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 (anthropic, openai, openrouter, local) to route to a specific LLM provider. The provider resolves at dispatch time: task.provider > config default.

Execution modes

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

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:

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.