Development Guide

This document provides detailed information for developers working on the Claude Code Telegram Bot.

Getting Started

Prerequisites

Python 3.11 or higher
Poetry for dependency management
Git for version control
Claude authentication (one of):
- Claude Code CLI installed and authenticated
- Anthropic API key for direct SDK usage

Initial Setup

Clone the repository:

git clone https://github.com/RichardAtCT/claude-code-telegram.git
cd claude-code-telegram

Install Poetry (if not already installed):
```
pip install poetry
```
Install dependencies:
```
make dev
```
Set up pre-commit hooks (optional but recommended):
```
poetry run pre-commit install
```

Create configuration file:

cp .env.example .env
# Edit .env with your development settings

Development Workflow

Daily Development

Activate the Poetry environment:
```
poetry shell
```
Run tests continuously during development:
```
make test
```
Format code before committing:
```
make format
```
Check code quality:
```
make lint
```

Available Make Commands

make help          # Show all available commands
make install       # Install production dependencies only
make dev           # Install all dependencies including dev tools
make test          # Run full test suite with coverage
make lint          # Run all code quality checks
make format        # Auto-format all code
make clean         # Clean up generated files
make run           # Run the bot in normal mode
make run-debug     # Run the bot with debug logging

# Version management
make version       # Show current version
make bump-patch    # Bump patch version, commit, and tag
make bump-minor    # Bump minor version, commit, and tag
make bump-major    # Bump major version, commit, and tag
make release       # Push tag to trigger GitHub release workflow

Project Architecture

Package Structure

src/
├── config/           # Configuration management (✅ Complete)
│   ├── __init__.py
│   ├── settings.py   # Pydantic Settings class
│   ├── loader.py     # Environment detection and loading
│   ├── environments.py # Environment-specific overrides
│   └── features.py   # Feature flag management
├── bot/              # Telegram bot implementation (✅ Complete)
│   ├── __init__.py
│   ├── core.py       # Main bot class
│   ├── handlers/     # Command and message handlers
│   ├── middleware/   # Authentication and rate limiting
│   └── utils/        # Response formatting utilities
├── claude/           # Claude Code integration (✅ Complete)
│   ├── __init__.py
│   ├── integration.py # Subprocess management
│   ├── parser.py     # Output parsing and formatting
│   ├── session.py    # Session management
│   ├── monitor.py    # Tool usage monitoring
│   ├── facade.py     # High-level integration API
│   └── exceptions.py # Claude-specific exceptions
├── storage/          # Database and persistence (✅ Complete)
│   ├── __init__.py
│   ├── database.py   # Database connection and migrations
│   ├── models.py     # Data models with type safety
│   ├── repositories.py # Repository pattern data access
│   ├── facade.py     # Storage facade interface
│   └── session_storage.py # Persistent session storage
├── security/         # Authentication and security (✅ Complete)
│   ├── __init__.py
│   ├── auth.py       # Authentication logic
│   ├── validators.py # Input validation
│   └── rate_limiter.py # Rate limiting
├── utils/            # Utilities and constants (✅ Complete)
│   ├── __init__.py
│   └── constants.py  # Application constants
├── exceptions.py     # Custom exception hierarchy (✅ Complete)
└── main.py          # Application entry point (✅ Complete)

Testing Structure

tests/
├── unit/             # Unit tests (mirror src structure)
│   ├── test_config.py
│   ├── test_environments.py
│   ├── test_exceptions.py
│   ├── test_bot/     # Bot component tests
│   ├── test_claude/  # Claude integration tests
│   ├── test_security/ # Security framework tests
│   └── test_storage/ # Storage layer tests
├── integration/      # Integration tests (🚧 TODO)
├── fixtures/         # Test data and fixtures (🚧 TODO)
└── conftest.py      # Pytest configuration

Code Standards

Code Style

We use strict code formatting and quality tools:

Black: Code formatting with 88-character line length
isort: Import sorting with Black compatibility
flake8: Linting with 88-character line length
mypy: Static type checking with strict settings

Type Hints

All code must include comprehensive type hints:

from typing import Optional, List, Dict, Any
from pathlib import Path

def process_config(
    settings: Settings, 
    overrides: Optional[Dict[str, Any]] = None
) -> Path:
    """Process configuration with optional overrides."""
    # Implementation
    return Path("/example")

Error Handling

Use the custom exception hierarchy defined in src/exceptions.py:

from src.exceptions import ConfigurationError, SecurityError

try:
    # Some operation
    pass
except ValueError as e:
    raise ConfigurationError(f"Invalid configuration: {e}") from e

Logging

Use structured logging throughout:

import structlog

logger = structlog.get_logger()

def some_function():
    logger.info("Operation started", operation="example", user_id=123)
    try:
        # Some operation
        logger.debug("Step completed", step="validation")
    except Exception as e:
        logger.error("Operation failed", error=str(e), operation="example")
        raise

Testing Guidelines

Test Organization

Unit tests: Test individual functions and classes in isolation
Integration tests: Test component interactions
End-to-end tests: Test complete workflows (planned)

Writing Tests

import pytest
from src.config import create_test_config

def test_feature_with_config():
    """Test feature with specific configuration."""
    config = create_test_config(
        debug=True,
        claude_max_turns=5
    )
    
    # Test implementation
    assert config.debug is True
    assert config.claude_max_turns == 5

@pytest.mark.asyncio
async def test_async_feature():
    """Test async functionality."""
    # Test async code
    result = await some_async_function()
    assert result is not None

Test Coverage

We aim for >80% test coverage. Current coverage:

Configuration system: ~95%
Security framework: ~95%
Claude integration: ~75%
Storage layer: ~90%
Bot components: ~85%
Exception handling: 100%
Utilities: 100%
Overall: ~85%

Implementation Status

✅ Completed Components

TODO-1: Project Structure

Complete package layout with proper Python packaging
Poetry dependency management with dev/test/prod separation
Makefile with development commands
Exception hierarchy with proper inheritance
Structured logging with JSON output for production
Testing framework with pytest, coverage, and asyncio support

TODO-2: Configuration System

Pydantic Settings v2 with environment variable loading
Environment-specific overrides (development/testing/production)
Feature flags system for dynamic functionality control
Cross-field validation with proper error messages
Type-safe configuration with full mypy compliance
Computed properties for derived values
Configuration loader with environment detection
Test utilities for easy test configuration

TODO-3: Authentication & Security Framework

Multi-provider authentication system (whitelist and token-based)
Rate limiting with token bucket algorithm
Comprehensive input validation and path traversal prevention
Security audit logging with risk assessment
Bot middleware framework for security integration

TODO-4: Telegram Bot Core

Complete bot implementation with handler registration
Command routing system with comprehensive command set
Message parsing and intelligent response formatting
Inline keyboard support for user interactions
Error handling middleware with user-friendly messages

TODO-5: Claude Code Integration

Async subprocess management for Claude CLI with timeout handling
Response streaming and parsing for real-time updates
Session state persistence with context maintenance
Tool usage monitoring and security validation
Cost tracking and usage analytics

TODO-6: Storage Layer

SQLite database with complete schema and foreign key relationships
Repository pattern implementation with clean data access
Migration system with schema versioning
Analytics and reporting with user/admin dashboards
Persistent session storage replacing in-memory storage

🚧 Next Implementation Steps

TODO-7: Advanced Features (Current Priority)

File upload handling with security validation
Git integration for repository operations
Quick actions system for common workflows
Session export features (Markdown, JSON, HTML)
Image/screenshot support and processing

TODO-8: Complete Testing Suite

Integration tests for end-to-end workflows
Performance testing and benchmarking
Security testing and penetration testing
Load testing for concurrent users

TODO-9: Deployment & Documentation

Docker configuration and containerization
Kubernetes manifests for production deployment
Complete user and admin documentation
API documentation and developer guides

Development Environment Configuration

Required Environment Variables

For development, set these in your .env file:

# Required for basic functionality
TELEGRAM_BOT_TOKEN=test_token_for_development
TELEGRAM_BOT_USERNAME=test_bot
APPROVED_DIRECTORY=/path/to/your/test/projects

# Claude Authentication (choose one method)
# Option 1: Use existing Claude CLI auth (no API key needed)
# Option 2: Direct API key
# ANTHROPIC_API_KEY=sk-ant-api03-your-development-key

# Development settings
DEBUG=true
DEVELOPMENT_MODE=true
LOG_LEVEL=DEBUG
ENVIRONMENT=development

# Optional for testing specific features
ENABLE_GIT_INTEGRATION=true
ENABLE_FILE_UPLOADS=true
ENABLE_QUICK_ACTIONS=true

Running in Development Mode

# Basic run with environment variables
export TELEGRAM_BOT_TOKEN=test_token
export TELEGRAM_BOT_USERNAME=test_bot  
export APPROVED_DIRECTORY=/tmp/test_projects
make run-debug

# Or with .env file
make run-debug

The debug output will show:

Configuration loading steps
Environment overrides applied
Feature flags enabled
Validation results

Version Management

How versioning works

The version is defined in a single place: pyproject.toml. At runtime, src/__init__.py reads it via importlib.metadata. There is no hardcoded version string to keep in sync.

Cutting a release

# Bump the version (choose one) — commits, tags, and pushes automatically
make bump-patch    # 1.2.0 -> 1.2.1
make bump-minor    # 1.2.0 -> 1.3.0
make bump-major    # 1.2.0 -> 2.0.0

make bump-* runs poetry version, commits pyproject.toml, creates a git tag, and pushes both to GitHub. The tag push triggers the release workflow:

Runs the full lint + test suite
Creates a GitHub Release with auto-generated release notes
Updates the rolling latest git tag (stable releases only)

Pre-releases

Tags containing -rc, -beta, or -alpha (e.g. v1.3.0-rc1) are marked as pre-releases on GitHub and do not update the latest tag.

Contributing

Before Submitting a PR

Run the full test suite:
```
make test
```
Check code quality:
```
make lint
```
Format code:
```
make format
```
Update documentation if needed
Add tests for new functionality

Commit Message Format

Use conventional commits:

feat: add rate limiting functionality
fix: resolve configuration validation issue
docs: update development guide
test: add tests for authentication system

Code Review Guidelines

All code must pass linting and type checking
Test coverage should not decrease
New features require documentation updates
Security-related changes require extra review

Common Development Tasks

Adding a New Configuration Option

Add to Settings class in src/config/settings.py:

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

Add to .env.example with documentation
Add validation if needed
Write tests in tests/unit/test_config.py
Update documentation in docs/configuration.md

Adding a New Feature Flag

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

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

Add to enabled features list
Write tests

Debugging Configuration Issues

Use debug logging:
```
make run-debug
```
Check validation errors in the logs
Verify environment variables:
```
env | grep TELEGRAM
env | grep CLAUDE
```

Test configuration loading:

from src.config import load_config
config = load_config()
print(config.model_dump())

Troubleshooting

Common Issues

Import errors: Make sure you're in the Poetry environment (poetry shell)
Configuration validation errors: Check that required environment variables are set
Test failures: Ensure test dependencies are installed (make dev)
Type checking errors: Run poetry run mypy src to see detailed errors
Poetry issues: Try poetry lock --no-update to fix lock file issues

Getting Help

Check the logs with make run-debug
Review test output with make test
Examine the implementation documentation in docs/
Look at existing code patterns in the completed modules

FilesExpand file tree

development.md

Latest commit

History