Skip to main content

​
Debugging

When a run stalls, fails repeatedly, or produces unexpected results, Gump gives you several tools to understand what happened.

​
The terminal display

During a run, Gump shows progress by turn — not by raw event. Each turn displays: 
[build/1/impl]  turn 5  coding  ██░░  3 edits, 1 shell  124 tok  4.2s
[build/1/impl]  turn 6  execution  ██░░  0 edits, 2 shell  89 tok  6.1s
[build/1/impl]  turn 7  coding  ████  2 edits, 0 shell  156 tok  3.8s
Each line shows the turn number, a classified label (coding, execution, exploration, planning, reasoning, reviewing, writing, mixed), action counts, tokens, and duration. The label is a deterministic heuristic based on the tool types used in the turn — no LLM involved.

​
Verbose mode

For detailed event-level output, add --verbose: 
gump run spec.md --workflow tdd --verbose
In verbose mode, each turn expands to show the individual actions: 
[build/1/impl]  turn 5  coding
  → edit internal/server/healthz.go (32 lines)
  → edit internal/server/healthz_test.go (18 lines)
  → shell: go build ./...  (exit 0, 1.2s)
This is the most useful debugging tool — you can see exactly what the agent did at each step.

​
Error messages

Gump’s error messages are contextual. Depending on where the error occurs, they suggest the right next action: End of a failed run: 
Run failed at step build/1/impl (circuit breaker after 3 attempts)

  → gump report --detail build/1/impl    view step details
  → gump run --replay --from-step impl   retry from a clean state
  → gump run --resume                    continue from current state
Worktree issue: 
Error: worktree .gump/worktrees/run-abc123 is dirty

  → gump gc                              clean up old worktrees
Config error: 
Error: unknown agent "claude-opsu" in step decompose

  → gump models                          list supported agents
  → gump run --help                      usage information
No generic --help appended to every error. Each message tells you exactly what to do next.

​
Reading the report

After a failed run, the report shows where things went wrong: 
gump report
Look for steps with retries or escalations. Then drill into the problematic step: 
gump report --detail build/2/impl
This shows every attempt, the gate result, the error output, the agent used, and the cost. It’s the fastest way to understand why a step failed.

​
Common issues

The agent runs out of turns without finishing — The guard max_turns killed it. Either increase the limit or simplify the task (break the item into smaller pieces). The gate keeps failing on test — Check gump report --detail to see the test stderr. The agent receives this on retry, but if the error is in the test infrastructure (not the code), the agent can’t fix it. Check your test_cmd in gump.toml. The cost is higher than expected — Run gump report to see cost per step. Escalations are the main cost driver. If a cheap agent fails frequently, consider starting with a slightly more capable one to reduce retries. The agent writes files it shouldn’t — The no_write guard should catch this for plan/artifact/review steps. For diff steps, use untouched: "glob" in the gate to enforce blast radius boundaries.

​
Inspecting the worktree

The worktree is a normal Git repo. After a run (or while paused with HITL): 
cd .gump/worktrees/run-<uuid>

# See what changed
git log --oneline

# Inspect a specific step's diff
git diff <commit-before> <commit-after>

# Check the state bag
cat .gump/runs/<uuid>/state-bag.json | jq .