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

# Introduction

> What Super Turtle is and how it works

Super Turtle is an autonomous coding system you control from Telegram.
You describe what you want built, and it handles decomposition, execution,
and supervision on your machine.

You do not need to plan subtasks, pick loop strategies, or monitor logs.
You interact with one Meta Agent in chat while the system coordinates the rest.

<Warning>
  Platform status: macOS is fully supported, Linux is untested alpha, and Windows is not an officially supported setup target right now. See [Platform Support](/config/platform-support).
</Warning>

## What You Can Ask For

Here are real examples of requests that fit Super Turtle:

* "Build me a landing page for my product and send me a preview link."
* "Refactor the auth system to clean up middleware and add tests."
* "Add a `/usage` command that shows Claude and Codex quotas together."
* "Investigate why Codex meta-agent stops until prompted, then fix it."
* "Review Telegram and Cloudflare tunnel security and harden defaults."

For each request, the system can split work into focused SubTurtles, run those
workers in parallel, and report progress at milestone level.

## Core Experience

1. The Meta Agent interprets intent and decides whether to do the task directly
   or spawn SubTurtles.
2. SubTurtles execute autonomous coding loops, update state, and commit progress.
3. Telegram remains the control surface where you send requests and receive
   milestone/completion updates.
4. The local dashboard exposes operational state (sessions, lanes, queue,
   conductor workers/wakeups/inbox) for observability.
5. You stay in one conversation while the system manages orchestration.

## System Flow

The docs follow this operational order:

1. **Meta Agent** — planning, decomposition, supervision policy
2. **SubTurtles** — parallel worker execution and state progression
3. **Telegram Bot** — user interaction surface and driver runtime
4. **Dashboard** — local observability and conductor state visibility

Silence means progress. You should only get interrupted when it matters.

## Example Milestone Conversation

```text theme={null}
You: build me a landing page and wire screenshot checks
Meta Agent: 🚀 On it.
Meta Agent: 🎉 Milestone: hero section shipped. Screenshot captured. Starting form flow.
Meta Agent: ✅ All done. Here's what shipped: landing page + responsive form + screenshot tooling.
```

The message stream stays outcome-focused: start, meaningful milestones, completion.

## Key Capabilities

<CardGroup cols={2}>
  <Card title="Text + Voice Control" description="Send text or voice from Telegram. Voice notes can be transcribed and handled like normal requests." />

  <Card title="Parallel SubTurtles" description="Spawn focused worker agents that execute subtasks concurrently to reduce turnaround time." />

  <Card title="Claude + Codex Driver Layer" description="Run through one interface while routing work between Claude Code and Codex as task needs change." />

  <Card title="Usage-Aware Balancing" description="Track usage and quota pressure, then adapt driver choice and supervision cadence to stay cost-efficient." />

  <Card title="Autonomous Supervision" description="Background cron check-ins monitor long-running work and keep chat updates milestone-focused." />

  <Card title="Long-Run Continuity" description="State files and run tracking support resilient handoffs across extended or multi-stage work." />
</CardGroup>

## What You See vs What Runs Behind the Scenes

From your perspective:

* You ask for outcomes.
* You get concise milestone updates.
* You receive completion summaries and preview links when available.

Behind the scenes:

* The Meta Agent decomposes large requests.
* SubTurtles execute in loop types like `yolo-codex`, `yolo`, or `slow`.
* Each worker maintains a markdown state contract in `CLAUDE.md`.
* Scheduled supervision watches for drift, failure, and completion.

## Why This Model Works

* **Low cognitive load:** you stay focused on outcomes, not process management.
* **Better throughput:** parallel workers can ship independent streams at once.
* **Lower noise:** milestone-only reporting reduces chat spam.
* **Practical autonomy:** the system can keep moving without constant prompts.

## Next Step

Start with [Quickstart](/quickstart), then read [Architecture](/architecture) to
understand how Meta Agent supervision, SubTurtle loops, and driver routing fit
together.