Skip to main content

​
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 tmux session called superturtle-bot. The bot survives terminal disconnects.
  • Re-attach: tmux attach -t superturtle-bot
  • 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
node super_turtle/bin/superturtle.js init
export CLAUDE_WORKING_DIR=$(pwd)
cd super_turtle/claude-telegram-bot
bun run start
Why the export?
  • bun run start goes through the bot launcher directly, so it needs CLAUDE_WORKING_DIR up front to locate .superturtle/.env
  • superturtle start sets CLAUDE_WORKING_DIR for you automatically, but the globally installed CLI may not point at your current working tree during local development
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