CTL Commands - Super Turtle

./super_turtle/subturtle/ctl manages SubTurtle lifecycle: spawn, run, inspect, stop, and archive.

Command Summary

Command	Purpose
`spawn`	Create workspace, seed state, start SubTurtle, register recurring cron supervision
`start`	Start a SubTurtle in an existing workspace (no state seeding)
`stop`	Stop worker, stop watchdog, remove cron, archive workspace
`status`	Show running state, type, elapsed/remaining time, and tunnel URL if present
`logs`	Tail live SubTurtle logs
`list`	List active SubTurtles (or archived with `--archived`)
`archive`	Move a stopped SubTurtle to `.superturtle/subturtles/.archive/<name>/`
`gc`	Archive stopped SubTurtles older than a max age
`reschedule-cron`	Change recurring supervision interval for a running SubTurtle

Default loop type is yolo-codex. Default timeout is 1h. spawn default cron interval is 10m.

Duration Format

Duration flags use m, h, or d suffixes (or raw seconds):

30m
1h
2h
1d
600

Used by:

--timeout
--cron-interval
gc --max-age
reschedule-cron <interval>

`spawn`

High-level command used by the Meta Agent. It:

Creates .superturtle/subturtles/<name>/
Seeds CLAUDE.md from --state-file or piped stdin
Creates AGENTS.md -> CLAUDE.md symlink
Starts the SubTurtle
Registers recurring silent cron supervision

./super_turtle/subturtle/ctl spawn [name] \
  [--type slow|yolo|yolo-codex|yolo-codex-spark] \
  [--timeout DURATION] \
  [--state-file PATH|-] \
  [--cron-interval DURATION] \
  [--skill NAME ...]

Examples:

# Start from a prepared state file
./super_turtle/subturtle/ctl spawn docs-agent \
  --type yolo-codex \
  --timeout 1h \
  --state-file /tmp/docs-agent.md \
  --cron-interval 10m

# Pipe state over stdin
cat /tmp/task.md | ./super_turtle/subturtle/ctl spawn api-agent --state-file -

# Repeat --skill to load multiple skills
./super_turtle/subturtle/ctl spawn ui-agent \
  --state-file /tmp/ui.md \
  --skill frontend \
  --skill testing

spawn requires state input. If you do not pass --state-file, you must pipe stdin.

`start`

Low-level start command. Unlike spawn, it does not seed CLAUDE.md or register cron.

./super_turtle/subturtle/ctl start [name] \
  [--type slow|yolo|yolo-codex|yolo-codex-spark] \
  [--timeout DURATION] \
  [--skill NAME ...]

Examples:

# Start default workspace (.superturtle/subturtles/default/)
./super_turtle/subturtle/ctl start

# Start named workspace with explicit type/timeout
./super_turtle/subturtle/ctl start docs-agent --type slow --timeout 2h

start fails if .superturtle/subturtles/<name>/CLAUDE.md does not already exist.

`stop`

Gracefully stops a SubTurtle:

Removes recurring cron job (if any)
Stops watchdog
Sends SIGTERM, then SIGKILL if needed
Cleans pid/meta files
Archives workspace

./super_turtle/subturtle/ctl stop [name]

Example:

./super_turtle/subturtle/ctl stop docs-agent

`status`

Reports whether a SubTurtle is running and prints runtime details:

Loop type
PID
Elapsed and remaining timeout
Skills list (if set)
Process table row
Tunnel URL (if .tunnel-url exists)

./super_turtle/subturtle/ctl status [name]

Example:

./super_turtle/subturtle/ctl status docs-agent

`logs`

Follows the SubTurtle log file:

./super_turtle/subturtle/ctl logs [name]

Examples:

# Tail and follow default 50 lines
./super_turtle/subturtle/ctl logs docs-agent

# Increase initial tail size
LINES=200 ./super_turtle/subturtle/ctl logs docs-agent

`list`

Lists SubTurtles and current task pulled from each workspace CLAUDE.md.

./super_turtle/subturtle/ctl list [--archived]

Examples:

# Active workspaces
./super_turtle/subturtle/ctl list

# Archived workspaces
./super_turtle/subturtle/ctl list --archived

Output includes status, loop type, PID/time summary (if running), current task line, and skills (if any).

Additional Maintenance Commands

`archive`

Archive one stopped SubTurtle workspace:

./super_turtle/subturtle/ctl archive <name>

`gc`

Archive stopped SubTurtles older than a threshold (default 1d):

./super_turtle/subturtle/ctl gc [--max-age DURATION]

Example:

./super_turtle/subturtle/ctl gc --max-age 12h

`reschedule-cron`

Update recurring supervision interval for a SubTurtle:

./super_turtle/subturtle/ctl reschedule-cron <name> <interval>

Example:

./super_turtle/subturtle/ctl reschedule-cron docs-agent 5m

Typical Lifecycle

Seed and spawn

./super_turtle/subturtle/ctl spawn docs-agent --state-file /tmp/docs-agent.md

Check progress

./super_turtle/subturtle/ctl status docs-agent
./super_turtle/subturtle/ctl logs docs-agent

Adjust supervision cadence if needed

./super_turtle/subturtle/ctl reschedule-cron docs-agent 3m

Stop and archive

./super_turtle/subturtle/ctl stop docs-agent

​Command Summary

​Duration Format

​spawn

​start

​stop

​status

​logs

​list

​Additional Maintenance Commands

​archive

​gc

​reschedule-cron

​Typical Lifecycle

​Related Pages

Command Summary

Duration Format

`spawn`

`start`

`stop`

`status`

`logs`

`list`

Additional Maintenance Commands

`archive`

`gc`

`reschedule-cron`

Typical Lifecycle

Related Pages