Service Management — Workgraph

Starting the service

wg service start

The daemon runs in the background, continuously polling the task graph. When a task becomes ready (all dependencies complete), the coordinator spawns an agent to work on it — up to max_agents in parallel.

# Limit parallel agents
wg service start --max-agents 4

# Override model for all spawned agents
wg service start --model sonnet

# Override executor
wg service start --executor shell

Service commands

Command	Description
`wg service start`	Start the background daemon
`wg service stop`	Stop daemon (running agents continue)
`wg service stop --kill-agents`	Stop daemon and kill all agents
`wg service status`	Show daemon PID, uptime, agent summary
`wg service reload`	Re-read config.toml without restarting
`wg service restart`	Graceful stop then start
`wg service pause`	Pause (agents continue, no new spawns)
`wg service resume`	Resume (immediate tick)
`wg service install`	Generate a systemd user service file

Reload lets you change settings at runtime without restarting:

wg service reload                              # re-read config.toml
wg service reload --max-agents 8 --model haiku # apply specific overrides

Configuration

The service reads from .workgraph/config.toml:

[coordinator]
max_agents = 4         # max parallel agents (default: 4)
poll_interval = 60     # seconds between ticks (default: 60)
executor = "claude"    # "claude", "amplifier", or "shell"
model = "opus"         # model for all spawned agents

[agent]
executor = "claude"
model = "opus"         # default model
heartbeat_timeout = 5  # minutes before agent is dead (default: 5)

Set values from the command line:

wg config --max-agents 8
wg config --model sonnet
wg config --executor shell
wg config --poll-interval 120

# Inspect merged config (shows source: global, local, or default)
wg config --list

Agent management

List and filter running agents:

wg agents              # all agents
wg agents --alive      # running only
wg agents --dead       # dead only
wg agents --working    # actively on a task
wg agents --json       # JSON for scripting

Kill agents:

wg kill agent-7          # graceful: SIGTERM → wait → SIGKILL
wg kill agent-7 --force  # immediate SIGKILL
wg kill --all            # kill all running agents

Killing an agent automatically unclaims its task so another agent can pick it up.

Dead agent detection

Agents send heartbeats while working. If an agent's process exits or its heartbeat goes stale (default: 5 minutes), the coordinator marks it dead and unclaims its task.

wg dead-agents             # check for dead agents
wg dead-agents --cleanup   # mark dead and unclaim tasks
wg dead-agents --purge     # remove all dead agents

Smart triage

When a dead agent is detected, the coordinator can use an LLM to triage the situation. The triager reads the agent's output log and decides whether the task was actually completed, is still running, or needs to be restarted.

wg config --auto-triage true
wg config --triage-model haiku

Model selection

Models are resolved in priority order:

Task model — set with wg add --model or wg edit --model
Executor config — model field in the executor's config file
Coordinator model — coordinator.model in config.toml
Executor default — if nothing else is set

# Per-task model at creation
wg add "Simple fix" --model haiku
wg add "Complex design" --model opus

# Change model on existing task
wg edit my-task --model sonnet

# Set coordinator default
wg config --model sonnet
wg service reload

Cost guidance: Use haiku for simple formatting and linting, sonnet for typical coding, and opus for complex reasoning and architecture.

Model registry

Manage available models and configure per-role routing:

wg model list                        # show all models
wg model add my-model --provider openrouter --model-id deepseek/deepseek-chat-v3
wg model set-default sonnet          # set default dispatch model
wg model set --role evaluator opus   # per-role model routing

Troubleshooting

Daemon logs are written to .workgraph/service/daemon.log (rotates at 10 MB). Recent errors also show in wg service status.

Issue	Solution
Socket already exists	Check `wg service status`, then `wg service stop`
Agents not spawning	Check `wg service status` for coordinator state. Verify `max_agents` with `wg agents --alive`. Check `wg ready`.
Agent marked dead early	Increase `heartbeat_timeout` in config.toml
Config changes ignored	Run `wg service reload` after editing config.toml