Running as a Service - Super Turtle

Default: superturtle start (tmux)

The simplest way to run the bot persistently:

superturtle start

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

Set your paths and credentials:

<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

Common issues: invalid bot token, missing bun binary, working directory doesn’t exist.

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

Platform differences

Feature	macOS	Linux
Default	`superturtle start` (tmux)	`superturtle start` (tmux)
Service manager	launchd	systemd
Auto-start	`RunAtLoad=true`	`WantedBy=default.target`

Next steps

Personal Assistant — Set up Claude as your assistant
Environment Variables — Full config reference
Security — Permissions and safety

​Default: superturtle start (tmux)

​macOS (LaunchAgent)

​Setup

​Managing

​Prevent sleep

​Shell aliases

​Linux (systemd)

​Setup

​Managing

​Logs

​Shell aliases

​Development mode

​Troubleshooting

​Bot doesn’t start

​Bot keeps restarting

​Telegram not receiving messages

​Platform differences

​Next steps

Default: superturtle start (tmux)

macOS (LaunchAgent)

Setup

Managing

Prevent sleep

Shell aliases

Linux (systemd)

Setup

Managing

Logs

Shell aliases

Development mode

Troubleshooting

Bot doesn’t start

Bot keeps restarting

Telegram not receiving messages

Platform differences

Next steps