Our review

Runs a command or prompt on a recurring interval using a background shell loop.

Strengths

Portable across all agent harnesses
Detached background processes survive agent restarts
Simple start/stop/status interface
Pairs with labrat for automated research workflows

Limitations

Requires Bash as the underlying tool
Not as integrated as native agent loops
Does not handle complex scheduling (cron-like)

When to use it

When you need to run a command repeatedly in the background, independent of the agent's lifecycle.

When not to use it

When the agent has a built-in loop (e.g., /loop) or you need more sophisticated scheduling.

Examples

Check research status every 5 minutes

Start a treadmill to run python .research/experiments/00-baseline/modal_app.py every 5 minutes.

Poll a deployment health endpoint

Start a treadmill to curl https://api.example.com/health every 2 minutes.

Run metrics script hourly

Start a treadmill to run python check_metrics.py every hour.

name: treadmill description: "Run a command or prompt on a recurring interval, like a lab rat on a wheel. Use when the user wants to poll, repeat a task periodically, set up a recurring check, or keep a long-running process supervised. Pairs with /labrat for overnight research sessions." license: Apache-2.0 compatibility: "Requires bash. Works on macOS and Linux." metadata: author: tau version: "1.0" allowed-tools: Bash

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> <command...>

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

Treadmill: Recurring Command Runner

Recommended for