Skip to main content

​
Your First Run

Let’s run a workflow end-to-end. You’ll write a spec, launch Gump, and see the result.

​
Write a spec

Create a file called spec.md in your repo: 
Add a /healthz endpoint to the HTTP server that returns 200 OK
with a JSON body containing the server uptime and version.
The spec can be anything — a feature description, a bug report, a task breakdown. Gump passes it to the agent as context.

​
Run a workflow

gump run spec.md --workflow cheap2sota
Gump will:
  1. Create an isolated Git worktree (your main branch stays clean)
  2. Ask Claude Sonnet to decompose the spec into independent items
  3. Implement each item using Qwen (the cheapest agent)
  4. Validate each step with compile + test gates
  5. If a gate fails, retry or escalate to a stronger agent
  6. Run a final quality gate (compile + lint + test)
You’ll see the progress in your terminal: 
🍿 gump run spec.md --workflow cheap2sota

→ Step 1: Decompose
  ✓ plan: 2 items (claude-sonnet)

→ Step 2: Build
  [build/1/impl]  running (qwen)
  [build/1/impl]  ✓ gate passed — compile+test
  [build/2/impl]  running (qwen)
  [build/2/impl]  ✗ gate failed — test
  [build/2/impl]  retry 2/5 (same)
  [build/2/impl]  ✓ gate passed — compile+test

→ Step 3: Quality
  ✓ compile + lint + test

Run completed. $0.83 · 8 turns · 52s

​
Preview without running

If you want to see what Gump will do before launching agents: 
gump run spec.md --workflow cheap2sota --dry-run
This parses the workflow, validates it, and prints the execution plan — without creating a worktree or calling any agent.

​
What just happened

Gump created a worktree in .gump/worktrees/run-<uuid>, ran the agents inside it, validated every step, and committed a snapshot after each one. The result is ready to merge. Check the report: 
gump report

Run: run_2026_03_24_1042
Workflow: cheap2sota · Status: pass · Duration: 52s · Cost: $0.83

Step            Agent           Turns  Cost    Gate
───────────────────────────────────────────────────────
decompose       claude-sonnet     2   $0.14   schema ✓
build/1/impl    qwen              3   $0.08   compile+test ✓
build/2/impl    qwen              5   $0.11   compile+test ✓ (1 retry)
quality         —                 —   —       compile+lint+test ✓
Now apply the result to your branch.