Getting Started

From zero to agents working on your project.

Install

Workgraph is a single Rust binary. Install it with Cargo: 

cargo install --git https://github.com/graphwork/workgraph

Or clone and build from source:

git clone https://github.com/graphwork/workgraph
cd workgraph
cargo install --path .

Verify the installation:

wg --version

Global setup

Run the interactive setup wizard once after install:

wg setup

This writes ~/.workgraph/config.toml and configures your executor (claude or amplifier), default model, agency settings, and which lightweight model to use for assignment and evaluation (haiku is recommended).

Initialize a project

In any project directory:

cd my-project
wg init

This creates a .workgraph/ directory containing your task graph. No server, no account — everything lives next to your code. The directory is automatically added to .gitignore.

wg init also seeds starter roles and tradeoffs for the agency system and creates a default agent, so the service can start dispatching work immediately.

Create tasks

Add tasks with wg add. Use --after to declare dependencies:

# Simple task
wg add "Design the API"

# Task that depends on another
wg add "Build the backend" --after design-the-api

# Multiple dependencies
wg add "Deploy to staging" --after build-the-backend,write-tests

Task IDs are auto-generated from the title (kebab-case). You can also set one explicitly with --id.

Tasks support rich metadata:

# Estimated effort and skills
wg add "Implement auth" --hours 8 --skill rust --skill security

# Model override — use a cheaper model for simple work
wg add "Quick formatting fix" --model haiku

# Verification gate — must pass before the task can complete
wg add "Security audit" --verify "All findings documented"

# Deliverables
wg add "Build auth module" --deliverable src/auth.rs

Visualize the graph

See your dependency graph as ASCII art:

$ wg viz

design-the-api  (open)
└→ build-the-backend  (open)
  ├→ write-tests  (open) ────────┐
  └→ deploy-to-staging  (open) ←─┘

Check which tasks are ready (no unfinished blockers):

wg ready

Start the service

The coordinator daemon watches the graph and automatically spawns AI agents on ready tasks: 

wg service start --max-agents 3

When a task completes and unblocks downstream work, the coordinator picks those up too. The cascade continues until all tasks are done.

Monitor progress

Several ways to see what's happening:

# Interactive terminal dashboard
wg tui

# Agent status
wg agents

# Task list with status
wg list

# Full service status
wg service status

What's next