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.

Super Turtle is a local multi-agent system orchestrated by one Meta Agent. The Meta Agent owns planning and supervision, delegates execution to SubTurtles, receives requests via Telegram, and exposes operational state in the local dashboard.

​
Control-Plane Order

Use this mental model when reading the system docs:
  1. Meta Agent decides strategy and delegation.
  2. SubTurtles execute scoped work and emit durable lifecycle facts.
  3. Telegram Bot is the operator interaction surface.
  4. Dashboard is the local observability surface over runtime + conductor state.

​
System Diagram

​
Meta Agent

The Meta Agent is the orchestrator, not just a chat interface. It:
  • Interprets requests from Telegram.
  • Decomposes larger tasks into parallelizable units.
  • Seeds SubTurtle state files and starts workers with ./super_turtle/subturtle/ctl spawn.
  • Monitors progress through scheduled supervision prompts.
  • Sends milestone-only updates instead of noisy step-by-step logs.
The user experience stays simple: one conversation, multiple workers behind the scenes.

​
SubTurtle Loop Types

Each SubTurtle runs one autonomous loop:
TypeWhat it doesTypical use
slowPlan -> Groom -> Execute -> ReviewComplex multi-step work
yoloSingle Claude call per iterationClaude-first tasks
yolo-codexSingle Codex call per iterationDefault cost/speed balance
yolo-codex-sparkSingle Codex Spark call per iterationFastest Codex-based loops
See SubTurtle Loop Types for details.

​
State Management

Task intent is markdown-first and lives in CLAUDE.md files:
  • Project-level state in the repo root.
  • Per-worker state in .superturtle/subturtles/<name>/CLAUDE.md.
Durable orchestration state is conductor-first and lives under .superturtle/state/ (workers, wakeups, inbox, events.jsonl). The backlog in each file is the execution contract for that run. A SubTurtle exits when it appends: 
## Loop Control
STOP
This keeps intent human-readable while lifecycle/delivery truth remains machine-checkable.

​
Cron Supervision

ctl spawn automatically registers recurring supervision jobs in .superturtle/cron-jobs.json.
  • Jobs are marked silent: true by default for low-noise operation.
  • Check-ins review worker progress and only surface meaningful updates.
  • Interval is configurable (--cron-interval on spawn, ctl reschedule-cron later).
The default spawn interval is 10 minutes, and it can be tightened or relaxed as workload changes.

​
Driver Abstraction

Super Turtle routes execution through a driver layer so workers can use either runtime without changing task-level instructions:
  • Claude Code: strongest reasoning and high-complexity workflows.
  • Codex: lower-cost, faster loops for straightforward implementation.
yolo-codex is the default SubTurtle type. The Meta Agent can switch between Claude- and Codex-based loops based on task complexity and quota signals.

​
What’s Next