# Treadmill

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

- **Type:** Skill
- **Install:** `agentstack add skill-nwyin-labrat-treadmill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nwyin](https://agentstack.voostack.com/s/nwyin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [nwyin](https://github.com/nwyin)
- **Source:** https://github.com/nwyin/labrat/tree/main/treadmill

## Install

```sh
agentstack add skill-nwyin-labrat-treadmill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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

```bash
treadmill start  
```

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

Examples:
```bash
# 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

```bash
treadmill stop
```

### Check status

```bash
treadmill status
```

### View logs

```bash
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:

```bash
# 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:

```bash
# 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](https://github.com/nwyin)
- **Source:** [nwyin/labrat](https://github.com/nwyin/labrat)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nwyin-labrat-treadmill
- Seller: https://agentstack.voostack.com/s/nwyin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.