Skip to main content
SubTurtles are autonomous background coding agents. The Meta Agent uses them to execute tasks without constant human supervision. The core model is simple:
  • Meta Agent decides what should be done.
  • SubTurtle executes one focused backlog item at a time.
  • State is tracked in .subturtles/<name>/CLAUDE.md.
  • Completion is signaled by appending ## Loop Control and STOP.

​
What a SubTurtle Is

A SubTurtle is a worker process started by ./super_turtle/subturtle/ctl spawn that runs an autonomous coding loop (slow, yolo, yolo-codex, or yolo-codex-spark). Each SubTurtle:
  • Runs in its own workspace: .subturtles/<name>/
  • Reads and writes only its own task state file
  • Works from repo root, so it can modify project code
  • Is constrained by a timeout watchdog
  • Is supervised by recurring, silent cron check-ins
ctl spawn defaults are --type yolo, --timeout 1h, and --cron-interval 10m. Supervision is registered with silent: true by default. (META_SHARED.md currently describes a 5-minute target cadence, but the executable default in ctl is 10 minutes unless overridden.)

​
Workspace Structure

Example workspace for a SubTurtle named docs-agent: 
.subturtles/docs-agent/
├── CLAUDE.md        # Per-agent task state (source of truth)
├── AGENTS.md        # Symlink to CLAUDE.md
├── subturtle.pid    # Worker process id
├── subturtle.log    # stdout/stderr log stream
├── subturtle.meta   # Spawned timestamp, timeout, type, watchdog pid, cron job id
├── .tunnel-url      # Optional frontend preview URL
├── .runtime-home/   # Optional writable HOME fallback in restricted environments
└── screenshots/     # Optional verification artifacts
ctl spawn seeds CLAUDE.md, creates the AGENTS.md symlink, starts the SubTurtle, and registers recurring cron supervision. When a SubTurtle is stopped (manually or via self-stop cleanup), its workspace is archived to .subturtles/.archive/<name>/.

​
State File Ownership

CLAUDE.md is the contract between Meta Agent and SubTurtle. 
## Current Task
Write docs/subturtles/overview.mdx.

## End Goal with Specs
[acceptance criteria]

## Backlog
- [x] Read key source docs
- [ ] Write docs/subturtles/overview.mdx <- current
- [ ] Commit
Lifecycle:
  1. Meta Agent provides initial task state (typically via ctl spawn --state-file <path> or piped stdin; low-level ctl start expects CLAUDE.md to already exist).
  2. SubTurtle reads it each iteration, does one commit-sized slice, and updates backlog progress.
  3. Supervisor check-ins inspect this file to determine Finished, Milestone, Stuck, or Error events.

​
Self-Completion via Loop Control

When all backlog items are complete, the SubTurtle appends: 
## Loop Control
STOP
The loop checks for this directive before and after each iteration and exits cleanly when present. 
# In super_turtle/subturtle/__main__.py
STOP_DIRECTIVE = "## Loop Control\\nSTOP"
After self-stop, the loop queues completion handoff notifications, then invokes ctl stop semantics to remove recurring cron supervision and archive the workspace.

​
Timeout and Watchdog

SubTurtles are protected by a watchdog created at start:
  • Watchdog sleeps until timeout.
  • If worker is still running, send SIGTERM.
  • Wait 5 seconds.
  • If still running, send SIGKILL.
This prevents runaway loops and guarantees bounded runtime even if an agent gets stuck. 
./super_turtle/subturtle/ctl spawn docs-agent --timeout 30m
Accepted duration format is flexible (30m, 1h, 2h, 1d, or raw seconds like 3600).

​
End-to-End Flow

1

Meta Agent provides state

It provides initial task state (current task, end goal, backlog) via --state-file or stdin to ctl spawn.
2

Meta Agent spawns worker

It runs:
./super_turtle/subturtle/ctl spawn <name> --type yolo-codex --state-file <path-or-stdin>
3

SubTurtle iterates autonomously

It reads state, implements one focused change, verifies, updates state, and commits.
4

Supervisor checks silently

Recurring cron checks stay silent unless there is meaningful news.
5

SubTurtle self-stops

It writes ## Loop Control + STOP when backlog is complete.
6

Meta cleanup and next action

The system finalizes cleanup and either starts the next queued task or reports full completion.