Treadmill

Treadmill

Run a command on a recurring interval using a background shell loop. Portable across all agent harnesses.

How to use

The bundled treadmill script handles start/stop/status. Set it up from the skill directory:

SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
export PATH="${SKILL_DIR}/scripts:$PATH"

Or reference it directly: bash ${CLAUDE_SKILL_DIR}/scripts/treadmill

Start a treadmill

treadmill start  

Interval formats: 30s, 5m, 1h, or plain seconds (e.g. 300).

Examples:

# Check research status every 5 minutes
treadmill start 5m python .research/experiments/00-baseline/modal_app.py

# Poll a deployment
treadmill start 2m curl -s https://api.example.com/health

# Run a script every hour
treadmill start 1h python check_metrics.py

Stop

treadmill stop

Check status

treadmill status

View logs

treadmill log      # last 30 lines
treadmill log 100  # last 100 lines

State

Treadmill keeps its state in .treadmill/ in the current directory:

• pid — PID of the background loop
• config — interval, command, start time
• log — stdout/stderr from each run

Pairing with labrat

For overnight ML research, start a treadmill that re-runs the labrat state-advance worker rather than a passive status printer:

# Reconcile state every 5 minutes
treadmill start 5m python /path/to/labrat/scripts/research-advance

Use research-status only for human-readable inspection. Use research-advance for automation, because it updates .research/state.json when artifacts appear.

If the harness is Codex, prefer the supervisor wrapper instead:

# Reconcile state, then wake Codex when the session is actionable
treadmill start 5m python /path/to/labrat/scripts/research-supervise

That wrapper gives you the missing /loop behavior: the background loop notices finished artifacts, updates .research/state.json, and only then starts a fresh non-interactive Codex run to do the next research step.

The agent can read treadmill logs to see what happened between invocations.

When to use this vs built-in loop

Some agent tools (like Claude Code) have a built-in /loop command. Use that when available. Use /treadmill when:

• Your agent harness doesn't have a built-in loop
• You want a detached background process that survives agent restarts
• You need to run shell commands on a timer independent of the agent

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nwyin
• Source: nwyin/labrat
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.