Claude Code Telegram Bot

The bot provides two primary interaction models for accessing Claude Code remotely via Telegram:

1. Agentic Mode (Default): A conversational interface designed for natural language interaction. Users chat naturally with Claude without needing specific commands. It supports file and image uploads and maintains automatic session persistence per user and project directory. Minimal commands include /start, /new, and /status.

2. Classic Mode: A terminal-like interface providing 13 specific commands (such as cd, ls, and pwd). This mode features project quick-switching via inline keyboards, Git status integration, and the ability to export sessions in multiple formats.

The project documentation is organized into several key guides to help you set up, configure, and extend the bot.

• Setup & Installation: Covers prerequisites, authentication, and installation methods.
• Configuration: Provides a full reference for environment variables and feature flags.
• Available Tools: Details the 16 tools available to Claude and how to manage them via allowlists/disallowlists.
• Systemd Setup: Instructions for running the bot as a persistent systemd user service.
• Project Overview: Explains the architecture and request flow.

Agentic Mode is the default conversational interface where you interact with Claude using natural language. No special commands are required for standard chat.

Available Commands:

• /start: Initialize the session.
• /new: Start a new conversation.
• /status: Check usage and status.
• /verbose <0|1|2>: Control the level of background activity shown:
  • 0 (quiet): Final response only.
  • 1 (normal): Tool names + reasoning snippets.
  • 2 (detailed): Tool names + inputs + full reasoning.
• /repo: List cloned repos or switch directories using /repo <name>.
• /sync_threads: Sync project threads (if ENABLE_PROJECT_THREADS=true).

The project version is managed in pyproject.toml. You can use make commands to bump the version, which automatically commits the change, creates a git tag, and pushes to GitHub. Pushing a tag triggers the release workflow (linting, testing, and GitHub Release creation).

• make bump-patch: Increments the patch version (e.g., 1.2.0 -> 1.2.1)
• make bump-minor: Increments the minor version (e.g., 1.2.0 -> 1.3.0)
• make bump-major: Increments the major version (e.g., 1.2.0 -> 2.0.0)

Pre-releases (using -rc, -beta, or -alpha suffixes) do not update the latest git tag.

The bot automatically adjusts settings based on the ENVIRONMENT variable or the DEBUG flag.

Development

Triggered by ENVIRONMENT=development or DEBUG=true.

• log_level: DEBUG
• rate_limit_requests: 100
• claude_timeout_seconds: 600

Testing

Triggered by ENVIRONMENT=testing.

• database_url: sqlite:///:memory:
• approved_directory: /tmp/test_projects
• claude_timeout_seconds: 30
• rate_limit_requests: 1000

Production

Triggered by ENVIRONMENT=production.

• log_level: INFO
• enable_telemetry: true
• claude_max_cost_per_user: 5.0
• claude_max_cost_per_request: 2.0
• rate_limit_requests: 5
• session_timeout_hours: 12

Use the following systemctl --user commands to manage the bot service lifecycle:

• Start: systemctl --user start claude-telegram-bot
• Stop: systemctl --user stop claude-telegram-bot
• Restart: systemctl --user restart claude-telegram-bot
• Status: systemctl --user status claude-telegram-bot
• Enable auto-start: systemctl --user enable claude-telegram-bot
• Disable auto-start: systemctl --user disable claude-telegram-bot

If you modify the .service file, you must reload the daemon first: systemctl --user daemon-reload

# Reload systemd to recognize the new service
systemctl --user daemon-reload

# Enable auto-start on login
systemctl --user enable claude-telegram-bot.service

# Start the service now
systemctl --user start claude-telegram-bot.service

To add a new configuration setting, follow these steps:

1. Define the setting in the Settings class within src/config/settings.py using Pydantic's Field:

   new_setting: bool = Field(False, description="Description of new setting")

2. Add the variable to .env.example.
3. Implement validation if necessary.
4. Write unit tests in tests/unit/test_config.py.
5. Update docs/configuration.md.

When running via SSH, the macOS keychain is often locked, causing Claude authentication to fail.

Option 1: Use make run-remote This unlocks the keychain with a password and starts the bot in a detached tmux session.

• make remote-attach: View logs.
• make remote-stop: Kill the bot.

Option 2: Use an API Key Set ANTHROPIC_API_KEY in your .env to bypass the keychain entirely.

To contribute to this project, follow these steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Implement changes and ensure they pass quality checks: make test && make lint.
4. Submit a Pull Request.

Code Standards:

• Python 3.11+
• Black formatting (88 chars)
• Type hints are required
• pytest with >85% coverage

Use make commands to start the bot. Use make run-debug for your initial setup to see logs, and make run for production.

make run-debug    # Recommended for first run
make run          # Production

To implement a feature flag:

1. Add a property to the FeatureFlags class in src/config/features.py:

   @property
   def new_feature_enabled(self) -> bool:
       return self.settings.enable_new_feature

2. Add the flag to the enabled features list.
3. Write corresponding tests.

Ensure your environment is correctly configured by testing ffmpeg and whisper-cpp manually.

1. Test ffmpeg conversion (creates a 2-second sine wave): ffmpeg -f lavfi -i "sine=frequency=440:duration=2" -ar 16000 -ac 1 /tmp/test.wav -y

2. Test whisper.cpp: whisper-cpp -m ~/.cache/whisper-cpp/ggml-base.bin -f /tmp/test.wav --no-timestamps

If the binary runs without errors, the setup is successful.