Remote Coding Agent - MVP (Telegram + Claude)

Control Claude Code remotely from Telegram with persistent sessions, codebase management, and streaming responses.

Features

• Telegram Integration: Control Claude from anywhere via Telegram
• Claude Agent SDK: Full access to Claude's coding capabilities
• Persistent Sessions: Sessions survive container restarts
• Codebase Management: Clone and work with GitHub repositories
• Streaming Responses: Real-time or batch message delivery
• Docker Ready: Simple deployment with Docker Compose

Prerequisites

• Node.js 20+ (for local development)
• Docker & Docker Compose (for containerized deployment)
• PostgreSQL 18 (managed remotely or via Docker)
• GitHub Token (for cloning repositories)
• Telegram Bot Token (from @BotFather)
• Claude API Key or OAuth Token

Quick Start

1. Create Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow prompts
3. Save the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Get Claude Authentication

Preferred Method: OAuth Token (for Claude Pro/Max subscribers)

If you have a Claude Pro or Max subscription:

# Run this command to generate an OAuth token
claude setup-token

# Copy the generated token - it starts with sk-ant-oat01-...

This generates a CLAUDE_CODE_OAUTH_TOKEN that works with your subscription and is ideal for containerized environments.

Alternative: API Key

If you don't have a subscription or prefer using API credits:

• Visit console.anthropic.com
• Navigate to API Keys
• Create a new key (starts with sk-ant-)
• Use this as CLAUDE_API_KEY

3. Environment Setup

# Copy example environment file
cp .env.example .env

# Edit .env with your credentials
nano .env

Required variables in .env:

# Database
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

# Claude - Preferred: OAuth token from `claude setup-token`
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
# OR use API key (if no subscription)
# CLAUDE_API_KEY=sk-ant-...

# GitHub (for /clone command)
GH_TOKEN=ghp_...

# Telegram
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_STREAMING_MODE=stream  # stream | batch

# Optional
WORKSPACE_PATH=./workspace
PORT=3000

4. Setup Database Tables

Run the migration script to create the required tables:

# If using Docker Compose with-db profile (local PostgreSQL)
docker-compose --profile with-db up -d postgres
docker-compose exec postgres psql -U postgres -d remote_coding_agent -f /docker-entrypoint-initdb.d/001_initial_schema.sql

# If using remote PostgreSQL
psql $DATABASE_URL -f migrations/001_initial_schema.sql

This creates 3 tables with the remote_agent_ prefix:

• remote_agent_codebases - Repository metadata
• remote_agent_conversations - Platform conversation tracking
• remote_agent_sessions - AI session management

5. Start with Docker Compose

Option A: With local PostgreSQL (recommended for getting started)

docker-compose --profile with-db up -d --build

Option B: With remote PostgreSQL

# Set DATABASE_URL to your remote Postgres instance
docker-compose up -d --build

Docker Profiles

with-db Profile

Starts both the app and PostgreSQL container.

docker-compose --profile with-db up -d

Use when:

• Getting started / testing locally
• Don't have remote PostgreSQL
• Want isolated environment

Default Profile (no profile flag)

Starts only the app container.

docker-compose up -d

Use when:

• Have remote PostgreSQL (Supabase, Neon, RDS, etc.)
• Production deployment
• Want to manage database separately

Telegram Commands

Once your bot is running, message it on Telegram:

Command	Description	Example
/help	Show available commands	/help
/clone <url>	Clone a GitHub repository	/clone https://github.com/user/repo
/status	Show conversation state	/status
/getcwd	Show current working directory	/getcwd
/setcwd <path>	Change working directory	/setcwd /workspace/repo
/reset	Clear active session	/reset

Usage Example

You: /help
Bot: Available Commands:
     /help - Show this help message
     ...

You: /clone https://github.com/anthropics/anthropic-sdk-typescript
Bot: Repository cloned successfully!
     Codebase: anthropic-sdk-typescript
     Path: /workspace/anthropic-sdk-typescript

     You can now start asking questions about the code.

You: What files are in this repo?
Bot: (Claude streams response analyzing the repository structure)

You: How does error handling work?
Bot: (Claude analyzes and explains error handling patterns)

You: /status
Bot: Platform: telegram
     AI Assistant: claude

     Codebase: anthropic-sdk-typescript
     Repository: https://github.com/anthropics/anthropic-sdk-typescript

     Current Working Directory: /workspace/anthropic-sdk-typescript
     Active Session: a1b2c3d4...

You: /reset
Bot: Session cleared. Starting fresh on next message.
     Codebase configuration preserved.

Health Checks

The application exposes two health check endpoints:

# Basic health check
curl http://localhost:3000/health
# Expected: {"status":"ok"}

# Database connectivity check
curl http://localhost:3000/health/db
# Expected: {"status":"ok","database":"connected"}

# View application logs
docker-compose logs -f app

Use these endpoints for:

• Docker healthcheck configuration
• Load balancer health checks
• Monitoring systems

Streaming Modes

Stream Mode (Default)

Messages are sent immediately as Claude generates them.

TELEGRAM_STREAMING_MODE=stream

Pros:

• Real-time feedback
• Feels more interactive
• See progress on long tasks

Cons:

• More Telegram API calls
• Might hit rate limits with very long responses

Batch Mode

Messages are accumulated and sent as a single final response.

TELEGRAM_STREAMING_MODE=batch

Pros:

• Fewer API calls
• Single coherent message
• Better for short Q&A

Cons:

• No progress indication
• Longer wait for first message

Architecture

Telegram Bot (Polling)
      ↓
Orchestrator
      ↓
   ┌──┴──┐
   │     │
Slash   AI
Commands Messages
   │     │
   │     ↓
   │  Claude SDK
   │     ↓
   └──→ PostgreSQL
         (3 tables)

Database Schema

3 Tables:

• remote_agent_codebases - Repository metadata
• remote_agent_conversations - Platform conversation tracking
• remote_agent_sessions - AI session management with resume capability

Key Files

src/
├── index.ts              # Entry point
├── types/index.ts        # TypeScript interfaces
├── adapters/
│   └── telegram.ts       # Telegram SDK wrapper
├── clients/
│   └── claude.ts         # Claude SDK wrapper
├── db/
│   ├── connection.ts     # PostgreSQL pool
│   ├── conversations.ts  # Conversation queries
│   ├── codebases.ts      # Codebase queries
│   └── sessions.ts       # Session queries
├── handlers/
│   └── command-handler.ts # Slash command processing
└── orchestrator/
    └── orchestrator.ts   # Main message router

Troubleshooting

Bot Not Responding

# Check if app is running
docker-compose ps

# Check app logs
docker-compose logs -f app

# Verify bot token
echo $TELEGRAM_BOT_TOKEN

Database Connection Errors

# Check database health
curl http://localhost:3000/health/db

# Check PostgreSQL logs
docker-compose logs -f postgres

# Verify DATABASE_URL
echo $DATABASE_URL

# Test database directly
docker-compose exec postgres psql -U postgres -c "SELECT 1"

Clone Command Fails

# Verify GitHub token
echo $GH_TOKEN

# Check workspace permissions
docker-compose exec app ls -la /workspace

# Try manual clone
docker-compose exec app git clone https://github.com/user/repo /workspace/repo

TypeScript Compilation Errors

# Clean build
rm -rf dist node_modules
npm install
npm run build

# Check for type errors
npm run type-check

Container Won't Start

# Check logs for errors
docker-compose logs app

# Verify environment variables
docker-compose config

# Rebuild without cache
docker-compose build --no-cache
docker-compose up -d