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

> What SubTurtles are, how their workspaces and state files work, and how they stop safely

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

<Info>
  `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.)
</Info>

## Workspace Structure

Example workspace for a SubTurtle named `docs-agent`:

```text theme={null}
.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.

```markdown theme={null}
## 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:

```markdown theme={null}
## Loop Control
STOP
```

The loop checks for this directive before and after each iteration and exits cleanly when present.

```bash theme={null}
# 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.

```bash theme={null}
./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

<Steps>
  <Step title="Meta Agent provides state">
    It provides initial task state (current task, end goal, backlog) via `--state-file` or stdin to `ctl spawn`.
  </Step>

  <Step title="Meta Agent spawns worker">
    It runs:

    ```bash theme={null}
    ./super_turtle/subturtle/ctl spawn <name> --type yolo-codex --state-file <path-or-stdin>
    ```
  </Step>

  <Step title="SubTurtle iterates autonomously">
    It reads state, implements one focused change, verifies, updates state, and commits.
  </Step>

  <Step title="Supervisor checks silently">
    Recurring cron checks stay silent unless there is meaningful news.
  </Step>

  <Step title="SubTurtle self-stops">
    It writes `## Loop Control` + `STOP` when backlog is complete.
  </Step>

  <Step title="Meta cleanup and next action">
    The system finalizes cleanup and either starts the next queued task or reports full completion.
  </Step>
</Steps>

## Related Pages

* [Loop Types](/subturtles/loop-types)
* [CTL Commands](/subturtles/ctl-commands)
* [State Files](/subturtles/state-files)
* [Meta Supervision](/meta/supervision)