Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superturtle.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 .superturtle/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: .superturtle/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-codex, --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: 
.superturtle/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 .superturtle/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.