Quickstart - Super Turtle

Prerequisites

Bun >= 1.0
tmux — brew install tmux
Claude Code CLI installed and authenticated
Telegram on your phone or desktop

macOS is fully supported. Linux is alpha. See Platform Support.

Install

Install superturtle

npm install -g superturtle

Run the setup wizard

superturtle init

The wizard walks you through:

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

Config is saved to .superturtle/.env.

Start the bot

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

Verify in Telegram

Open Telegram, find your bot, and send any message. You should get a response.

Non-interactive setup

For CI or scripted environments, pass flags directly:

superturtle init --token <BOT_TOKEN> --user <TELEGRAM_USER_ID> --openai-key <KEY>

Development setup

If you’re contributing to superturtle itself:

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:

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 — how Meta Agent and SubTurtles coordinate
Bot Commands — full command reference
Drivers — Claude Code vs Codex

​Prerequisites

​Install

​Non-interactive setup

​Development setup

​Mac reliability notes

​What’s next

Prerequisites

Install

Non-interactive setup

Development setup

Mac reliability notes

What’s next