Default: superturtle start (tmux)
The simplest way to run the bot persistently:
This creates a tmux session called superturtle-bot that survives terminal disconnects.
superturtle status # Check if running
superturtle stop # Stop the bot
tmux attach -t superturtle-bot # Re-attach to see logs
caffeinate on macOS (prevents sleep) and systemd-inhibit on Linux.
For most users, superturtle start is all you need. 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.superturtle-bot.plist
- Edit the plist:
nano ~/Library/LaunchAgents/com.superturtle-bot.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 load ~/Library/LaunchAgents/com.superturtle-bot.plist
launchctl list | grep superturtle
Managing
launchctl unload ~/Library/LaunchAgents/com.superturtle-bot.plist # Stop
launchctl load ~/Library/LaunchAgents/com.superturtle-bot.plist # Start
launchctl kickstart -k gui/$(id -u)/com.superturtle-bot # 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 superturtle'
alias st-stop='launchctl bootout gui/$(id -u)/com.superturtle-bot 2>/dev/null && echo "Stopped"'
alias st-start='launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.superturtle-bot.plist 2>/dev/null && echo "Started"'
alias st-restart='launchctl kickstart -k gui/$(id -u)/com.superturtle-bot && 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/super_turtle/claude-telegram-bot
ExecStart=/home/USERNAME/.bun/bin/bun run src/index.ts
Environment=TELEGRAM_BOT_TOKEN=your-bot-token
Environment=TELEGRAM_ALLOWED_USERS=123456789
Environment=CLAUDE_WORKING_DIR=/home/USERNAME/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
tmux attach -t superturtle-bot # Check for errors
# macOS LaunchAgent
tail -f /tmp/claude-telegram-bot.err
# 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 |
| Sleep prevention | caffeinate (built-in) | systemd-inhibit |
| Auto-start | RunAtLoad=true | WantedBy=default.target |
Next steps
