| name | agent-endurance |
| description | Structure long-running Claude Code sessions on this Python project so the agent iterates for hours instead of stopping after one pass. Use when the user mentions "long-running session", "multi-hour run", "agent keeps stopping", "agent finishes too early", "headless run", "tmux session", "milestones", "make verify", "fake success", "prevent shortcuts", or asks how to set up hooks, a verification gate, or an operating contract for an autonomous coding agent. |
Agent Endurance
Structure long-running Claude Code sessions so they iterate for hours instead of stopping after one pass.
When to use this skill
- Setting up a new multi-hour or overnight run on this repo.
- Diagnosing why an agent finishes too early or claims completion without evidence.
- Adding hooks, milestones, or a verification gate to an existing session.
Why agents stop early
Agents default to "produce a plausible completion." Without enforcement they will attempt a one-shot implementation, claim success without verification, swallow errors via broad try/except or mocked returns, and stop at the first "good enough" output.
The fix is never "ask harder." It is changing the environment.
Setup checklist
Step 1: Decompose into milestones
Break the project into 5–20 small milestones. Each has its own definition of done. Store them in MILESTONES.md at the repo root. Example already checked in — update statuses as work progresses (pending → CURRENT → done / blocked).
Step 2: Single verification command
make verify is the gate. It runs pytest -x --tb=short, ruff check ., ruff format --check ., and mypy --strict src/. The agent runs it after every meaningful edit. Do not skip it.
Step 3: Operating-contract prompt
The user-facing prompt reads like a contract: scope lock, verification mandate, anti-fake-success rules, failure protocol, evidence requirement, and explicit process order (Read → plan → execute one subtask → verify → repeat).
Full template: references/prompt-template.md.
Step 4: Hooks
Hooks are deterministic — they run even if the model forgets or tries to skip verification. Configure in .claude/settings.json:
- PostToolUse on
Write|Edit|MultiEdit → auto-format.
- Stop →
make verify; exit 2 blocks the stop.
- Stop →
scripts/check-no-fake-success.sh; exit 2 blocks the stop.
Full configs: references/hooks-config.md.
Step 5: Prevent fake-success
Most common failure mode. Run scripts/check-no-fake-success.sh from a Stop hook. It fails on:
except Exception in src/**/*.py- Empty
except: blocks with pass
- Stub returns (
return True # stub, return None # stub)
- Unreferenced
# TODO / # FIXME
Also require that every new function has at least one test exercising real behavior, and ban mocked network calls in production code.
Step 6: Multi-hour runs
For sessions >1 hour, use persistent infrastructure:
claude -p in a tmux/screen session on a VPS.- CI runners with the agent in the loop.
- Headless mode with
--output-format stream-json for log inspection.
Step 7: Subagents
Use the Task tool only for clearly separable concerns. More subagents ≠ better — they multiply context drift. Default to a single agent with hooks.
Example
User says: "Run this project overnight until M3 is done."
Actions:
- Confirm
MILESTONES.md marks M1, M2 as done and M3 as CURRENT.
- Fill in
references/prompt-template.md with milestone M3 details.
- Verify
.claude/settings.json has the Stop hook on make verify and check-no-fake-success.sh.
- Launch
claude -p "$(cat prompt.txt)" inside tmux.
- Next morning, check
MILESTONES.md and the session log for the completion summary.
Result: agent iterates on M3 only, cannot stop until make verify is green, and cannot introduce the banned shortcuts.
Troubleshooting
Agent finishes too quickly
Cause: Missing one of the four gates.
Fix: Check in order — (1) milestones exist and are scoped, (2) make verify target exists and runs, (3) anti-fake-success script is wired to a Stop hook, (4) prompt requires an evidence-bearing completion summary.
Stop hook never fires
Cause: Agent invokes a different stop path, or hook config is malformed.
Fix: Run claude --debug and confirm the Stop hook is registered. Validate .claude/settings.json is valid JSON.
make verify passes but code is clearly broken
Cause: Tests are mocked or skipped; checks cover too little.
Fix: Audit tests/ for @pytest.mark.skip, mock.patch of production functions, and coverage gaps. Add the anti-pattern to scripts/check-no-fake-success.sh.
Quick diagnostic
If the agent keeps finishing too quickly, tighten these four in order — same model will iterate much longer:
- No milestones → task too broad.
- No
make verify → no verification gate.
- No anti-fake-success rules → agent takes shortcuts.
- No evidence requirement → agent claims done without proof.
