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.
Default: superturtle start (tmux)
The simplest way to run the bot persistently:
This creates a project-scoped tmux session that survives terminal disconnects.
superturtle status # Check if running
superturtle stop # Stop the bot
superturtle start # Re-attach to the running tmux session
For most users, superturtle start is all you need. Use superturtle status to print the exact tmux session and log paths for the current project. The sections below are for production setups that need auto-start on boot and crash recovery.
macOS (LaunchAgent)
For auto-start on boot and automatic restart on crash.
Setup
- Copy the template:
cp super_turtle/claude-telegram-bot/launchagent/com.claude-telegram-ts.plist.template \
~/Library/LaunchAgents/com.claude-telegram-ts.plist
- Edit the plist:
nano ~/Library/LaunchAgents/com.claude-telegram-ts.plist
<key>TELEGRAM_BOT_TOKEN</key>
<string>your-bot-token</string>
<key>TELEGRAM_ALLOWED_USERS</key>
<string>your-telegram-user-id</string>
<key>CLAUDE_WORKING_DIR</key>
<string>/Users/YOUR_USERNAME/path/to/project</string>
<key>PATH</key>
<string>/Users/YOUR_USERNAME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
- Load and verify:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist
launchctl list | grep com.claude-telegram-ts
Managing
launchctl bootout gui/$(id -u)/com.claude-telegram-ts # Stop
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist # Start
launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts # Restart
Prevent sleep
Go to System Settings > Battery > Options and enable “Prevent automatic sleeping when the display is off” (on power adapter).
Shell aliases
alias st='launchctl list | grep com.claude-telegram-ts'
alias st-stop='launchctl bootout gui/$(id -u)/com.claude-telegram-ts 2>/dev/null && echo "Stopped"'
alias st-start='launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist 2>/dev/null && echo "Started"'
alias st-restart='launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts && echo "Restarted"'
Linux (systemd)
Setup
- Copy the template:
mkdir -p ~/.config/systemd/user
cp super_turtle/claude-telegram-bot/systemd/superturtle-bot.service.template \
~/.config/systemd/user/superturtle-bot.service
- Edit with your paths:
nano ~/.config/systemd/user/superturtle-bot.service
WorkingDirectory=/home/USERNAME/superturtle
ExecStart=/bin/bash -lc 'cd /home/USERNAME/superturtle && exec "${SUPERTURTLE_BIN:-superturtle}" service run'
Environment=TELEGRAM_BOT_TOKEN=your-bot-token
Environment=TELEGRAM_ALLOWED_USERS=123456789
Environment=CLAUDE_WORKING_DIR=/home/USERNAME/superturtle
Environment=SUPERTURTLE_BIN=superturtle
- Enable and start:
systemctl --user daemon-reload
systemctl --user enable --now superturtle-bot
systemctl --user status superturtle-bot
Managing
systemctl --user stop superturtle-bot
systemctl --user start superturtle-bot
systemctl --user restart superturtle-bot
Logs
journalctl --user -u superturtle-bot -f # Follow
journalctl --user -u superturtle-bot -n 50 # Last 50 lines
journalctl --user -u superturtle-bot --since="1 hour ago"
Shell aliases
alias st='systemctl --user status superturtle-bot'
alias st-stop='systemctl --user stop superturtle-bot'
alias st-start='systemctl --user start superturtle-bot'
alias st-restart='systemctl --user restart superturtle-bot'
alias st-logs='journalctl --user -u superturtle-bot -f'
Development mode
For contributors working on superturtle itself:
cd super_turtle/claude-telegram-bot
bun run dev # Auto-reload on file changes
Troubleshooting
Bot doesn’t start
# tmux mode
superturtle status # Prints exact tmux attach + log paths
# macOS LaunchAgent
superturtle logs loop
# Linux systemd
journalctl --user -u superturtle-bot -f
Bot keeps restarting
Check logs for crash reasons: Claude Code auth failure, network issues, Telegram rate limit, OOM.
Telegram not receiving messages
- Verify bot token (
/start in Telegram)
- Check user ID is in
TELEGRAM_ALLOWED_USERS
- Check network connectivity
| Feature | macOS | Linux |
|---|
| Default | superturtle start (tmux) | superturtle start (tmux) |
| Service manager | launchd | systemd |
| Auto-start | RunAtLoad=true | WantedBy=default.target |
Next steps
