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.

​
Prerequisites

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

​
Install

1

Install superturtle

npm install -g superturtle
2

Run the setup wizard

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

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
4

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