Contributing to Claude Code Telegram Bot

March 30, 2026 · View on GitHub

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Development Status

This project is currently under active development with the following status:

✅ Project Structure & Configuration (Complete)
✅ Authentication & Security (Complete)
✅ Bot Core & Integration (TODO-4, TODO-5, Complete)
✅ Storage Layer (TODO-6, Complete)
🚧 Advanced Features (TODO-7, Next)

Getting Started

Prerequisites

Python 3.11 or higher
Poetry for dependency management
Git for version control

Setting Up Development Environment

Fork and clone the repository:

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

Install dependencies:
```
make dev
```
This also installs pre-commit hooks that automatically format your code (black, isort) on each commit, so you never need to worry about formatting manually.
Linux users: If make dev shows a DBusErrorResponse / ItemNotFoundException error for aiolimiter, this is a known Poetry keyring issue on Linux. To prevent it, disable the keyring backend before running make dev:
```
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring make dev
```
Or configure Poetry once to disable keyring globally:
```
poetry config keyring.enabled false
make dev
```
If you already ran make dev and see 2 test failures, install aiolimiter manually and re-run tests:
```
poetry run pip install aiolimiter
make test
```

Set up configuration:

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

Verify setup:
```
make test
make lint
```

Development Workflow

Before Starting Work

Check existing issues for similar work
Create an issue if none exists
Comment on the issue to indicate you're working on it
Create a feature branch from main

Making Changes

Follow the project structure:

src/
├── config/     # Configuration (✅ Complete)
├── security/   # Authentication & Security (✅ Complete)
├── bot/        # Telegram bot (✅ Complete - TODO-4)  
├── claude/     # Claude integration (✅ Complete - TODO-5)
└── storage/    # Database (✅ Complete - TODO-6)

Write tests for new functionality:

# Add tests in tests/unit/ or tests/integration/
make test

Follow code standards:

make format  # Auto-format code
make lint    # Check code quality

Update documentation as needed

Code Standards

Type Hints

All code must include comprehensive type hints:

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

async def process_data(
    items: List[Dict[str, Any]], 
    config: Optional[Path] = None
) -> bool:
    """Process data with optional config."""
    # Implementation
    return True

Error Handling

Use the custom exception hierarchy:

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:

import structlog

logger = structlog.get_logger()

def some_function():
    logger.info("Operation started", operation="example", user_id=123)
    # Implementation

Testing

Write comprehensive tests:

import pytest
from src.config import create_test_config

@pytest.mark.asyncio
async def test_feature():
    """Test feature functionality."""
    config = create_test_config(debug=True)
    # Test implementation
    assert config.debug is True

Contribution Types

High Priority (Current TODOs)

TODO-7: Advanced Features (Next 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

Files to create/modify:

src/bot/handlers/file.py
src/git/integration.py
src/features/quick_actions.py
src/features/export.py
tests/unit/test_features.py

Recently Completed ✅

TODO-4: Telegram Bot Core

✅ Bot connection and handler registration
✅ Command routing system
✅ Message parsing and formatting
✅ Inline keyboard support
✅ Error handling middleware

TODO-5: Claude Code Integration

✅ Subprocess management for Claude CLI
✅ Response streaming and parsing
✅ Session state persistence
✅ Timeout handling
✅ Tool usage monitoring

TODO-6: Storage Layer

✅ SQLite database schema
✅ Repository pattern implementation
✅ Migration system
✅ Analytics and reporting

Documentation Improvements

API documentation
User guides
Deployment guides
Architecture documentation

Testing Improvements

Integration tests
End-to-end tests
Performance tests
Security tests

Submitting Changes

Pull Request Process

Ensure tests pass:
```
make test
make lint
```
Update documentation if needed
Create pull request with:
- Clear title and description
- Reference to related issue
- List of changes made
- Screenshots if UI-related
Respond to review feedback promptly

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
refactor: reorganize bot handlers

Pull Request Template

## Description
Brief description of changes made.

## Related Issue
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature  
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Manual testing completed

## Checklist
- [ ] `make format` has been run (or pre-commit hooks are installed via `make dev`)
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or clearly documented)

Code Review Guidelines

For Contributors

Self-review your code before submitting
Write clear commit messages and PR descriptions
Respond promptly to review feedback
Keep PRs focused on a single change
Add tests for new functionality

For Reviewers

Be constructive and helpful in feedback
Test functionality when possible
Check for security implications
Verify documentation updates
Ensure tests are comprehensive

Issue Guidelines

Bug Reports

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior.

**Expected behavior**
What you expected to happen.

**Environment**
- OS: [e.g. macOS, Linux]
- Python version: [e.g. 3.9]
- Poetry version: [e.g. 1.7.1]

**Additional context**
Any other context about the problem.

Feature Requests

**Is your feature request related to a problem?**
A clear description of what the problem is.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Alternative solutions or features you've considered.

**Additional context**
Any other context about the feature request.

Security

Reporting Security Issues

Do not create public issues for security vulnerabilities.

Instead:

Email security concerns to [maintainer email]
Include detailed description of the vulnerability
Wait for acknowledgment before public disclosure

Security Guidelines

Never commit secrets or credentials
Validate all inputs thoroughly
Use parameterized queries for database operations
Follow principle of least privilege
Log security-relevant events

Development Environment

Required Tools

Poetry: Dependency management
Black: Code formatting
isort: Import sorting
flake8: Linting
mypy: Type checking
pytest: Testing

Recommended IDE Setup

VS Code

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.formatting.provider": "black",
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true
}