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

# Quickstart

> Install superturtle and get your Telegram bot running

## Prerequisites

* [Bun](https://bun.sh) >= 1.0
* [tmux](https://github.com/tmux/tmux) — `brew install tmux`
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated
* [Telegram](https://telegram.org/) on your phone or desktop

<Warning>
  macOS is fully supported. Linux is alpha. See [Platform Support](/config/platform-support).
</Warning>

## Install

<Steps>
  <Step title="Install superturtle">
    ```bash theme={null}
    npm install -g superturtle
    ```
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={null}
    superturtle init
    ```

    The wizard walks you through:

    1. Creating a Telegram bot via `@BotFather`
    2. Getting your Telegram user ID via `@userinfobot`
    3. Optionally enabling voice transcription (requires `OPENAI_API_KEY`)

    Config is saved to `.superturtle/.env`.
  </Step>

  <Step title="Start the bot">
    ```bash theme={null}
    superturtle start
    ```

    This opens a project-scoped tmux session and attaches to it immediately. The bot survives terminal disconnects.

    * Re-attach: run `superturtle start` again, or use `superturtle status` to print the exact `tmux attach` command
    * Stop: `superturtle stop`
    * Status: `superturtle status`
  </Step>

  <Step title="Verify in Telegram">
    Open Telegram, find your bot, and send any message. You should get a response.
  </Step>
</Steps>

### Non-interactive setup

For CI or scripted environments, pass flags directly:

```bash theme={null}
superturtle init --token <BOT_TOKEN> --user <TELEGRAM_USER_ID> --openai-key <KEY>
```

## Development setup

If you're contributing to superturtle itself:

```bash theme={null}
git clone https://github.com/Rigos0/superturtle.git
cd superturtle
npx superturtle init
node super_turtle/bin/superturtle.js start
```

`superturtle init` installs dependencies, creates `.superturtle/.env`, and prompts for your tokens. In this repo, prefer the explicit `node super_turtle/bin/superturtle.js ...` form so you run the source checkout instead of any globally installed package.

Optional defaults for testing model configuration:

```bash theme={null}
cat >> .superturtle/.env <<'EOF'
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
CODEX_ENABLED=true
DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
DEFAULT_CODEX_EFFORT=low
EOF
```

## Mac reliability notes

* Enable `System Settings > Battery > Options > Prevent automatic sleeping when the display is off` (on power adapter).
* Keep the lid open while the bot is running.

## What's next

* [Architecture](/architecture) — how Meta Agent and SubTurtles coordinate
* [Bot Commands](/bot/commands) — full command reference
* [Drivers](/bot/drivers) — Claude Code vs Codex