Dynamous Remote Coding Agent

Control AI coding assistants (Claude Code, Codex) remotely from Telegram, GitHub, and more. Built for developers who want to code from anywhere with persistent sessions and flexible workflows/systems.

Quick Start: Core Configuration • AI Assistant Setup • Platform Setup • Start the App • Usage Guide

Features

• Multi-Platform Support: Interact via Telegram, GitHub issues/PRs, and more in the future
• Multiple AI Assistants: Choose between Claude Code or Codex (or both)
• Persistent Sessions: Sessions survive container restarts with full context preservation
• Codebase Management: Clone and work with any GitHub repository
• Flexible Streaming: Real-time or batch message delivery per platform
• Generic Command System: User-defined commands versioned with Git
• Docker Ready: Simple deployment with Docker Compose

Prerequisites

System Requirements: - Docker & Docker Compose (for deployment) - Node.js 20+ (for local development only)

Accounts Required: - GitHub account (for repository cloning via /clone command) - At least one of: Claude Pro/Max subscription OR Codex account - At least one of: Telegram account OR GitHub account (for interaction)

---

🌐 Production Deployment: This guide covers local development setup. To deploy remotely for 24/7 operation on a cloud VPS (DigitalOcean, AWS, Linode, etc.), see the Cloud Deployment Guide.

---

Setup Guide

Get started:

git clone https://github.com/coleam00/remote-agentic-coding-system
cd remote-agentic-coding-system

1. Core Configuration (Required)

Create environment file:

cp .env.example .env

Set these required variables:

Variable	Purpose	How to Get
DATABASE_URL	PostgreSQL connection	See database options below
GH_TOKEN	Repository cloning	Generate token with repo scope
GITHUB_TOKEN	Same as GH_TOKEN	Use same token value
PORT	HTTP server port	Default: 3000 (optional)
WORKSPACE_PATH	Clone destination	Default: ./workspace (optional)

GitHub Personal Access Token Setup:

1. Visit GitHub Settings > Personal Access Tokens
2. Click "Generate new token (classic)" → Select scope: repo
3. Copy token (starts with ghp_...) and set both variables:

# .env
GH_TOKEN=ghp_your_token_here
GITHUB_TOKEN=ghp_your_token_here  # Same value

Database Setup - Choose One:

Option A: Remote PostgreSQL (Supabase, Neon)

Set your remote connection string:

DATABASE_URL=postgresql://user:password@host:5432/dbname

Run migrations manually after first startup:

# Download the migration file or use psql directly
psql $DATABASE_URL < migrations/001_initial_schema.sql

This creates 3 tables: - remote_agent_codebases - Repository metadata - remote_agent_conversations - Platform conversation tracking - remote_agent_sessions - AI session management

Option B: Local PostgreSQL (via Docker)

Use the with-db profile for automatic PostgreSQL setup:

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

Database will be created automatically when you start with docker compose --profile with-db.

---

2. AI Assistant Setup (Choose At Least One)

You must configure at least one AI assistant. Both can be configured if desired.

🤖 Claude Code

Recommended for Claude Pro/Max subscribers.

Get OAuth Token (Preferred Method):

# Install Claude Code CLI first: https://docs.claude.com/claude-code/installation
claude setup-token

# Copy the token starting with sk-ant-oat01-...

Set environment variable:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

Alternative: API Key (if you prefer pay-per-use credits):

1. Visit console.anthropic.com/settings/keys
2. Create a new key (starts with sk-ant-)
3. Set environment variable:

CLAUDE_API_KEY=sk-ant-xxxxx

Set as default assistant (optional):

If you want Claude to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=claude

🤖 Codex

Authenticate with Codex CLI:

# Install Codex CLI first: https://docs.codex.com/installation
codex login

# Follow browser authentication flow

Extract credentials from auth file:

On Linux/Mac:

cat ~/.codex/auth.json

On Windows:

type %USERPROFILE%\.codex\auth.json

Set all four environment variables:

CODEX_ID_TOKEN=eyJhbGc...
CODEX_ACCESS_TOKEN=eyJhbGc...
CODEX_REFRESH_TOKEN=rt_...
CODEX_ACCOUNT_ID=6a6a7ba6-...

Set as default assistant (optional):

If you want Codex to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=codex

How Assistant Selection Works: - Assistant type is set per codebase (auto-detected from .claude/commands/ or .codex/ folders) - Once a conversation starts, the assistant type is locked for that conversation - DEFAULT_AI_ASSISTANT (optional) is used only for new conversations without codebase context

---

3. Platform Adapter Setup (Choose At Least One)

You must configure at least one platform to interact with your AI assistant.

💬 Telegram

Create Telegram Bot:

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Set environment variable:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI...

Configure streaming mode (optional):

TELEGRAM_STREAMING_MODE=stream  # stream (default) | batch

For streaming mode details, see Advanced Configuration.

🐙 GitHub Webhooks

Requirements: - GitHub repository with issues enabled - GITHUB_TOKEN already set in Core Configuration above - Public endpoint for webhooks (see ngrok setup below for local development)

Step 1: Generate Webhook Secret

On Linux/Mac:

openssl rand -hex 32

On Windows (PowerShell):

-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

Save this secret - you'll need it for steps 3 and 4.

Step 2: Expose Local Server (Development Only)

Using ngrok (Free Tier)

# Install ngrok: https://ngrok.com/download
# Or: choco install ngrok (Windows)
# Or: brew install ngrok (Mac)

# Start tunnel
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)
# ⚠️ Free tier URLs change on restart

Keep this terminal open while testing.

Using Cloudflare Tunnel (Persistent URLs)

# Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/
cloudflared tunnel --url http://localhost:3000

# Get persistent URL from Cloudflare dashboard

Persistent URLs survive restarts.

For production deployments, use your deployed server URL (no tunnel needed).

Step 3: Configure GitHub Webhook

Go to your repository settings: - Navigate to: https://github.com/owner/repo/settings/hooks - Click "Add webhook" - Note: For multiple repositories, you'll need to add the webhook to each one individually

Webhook Configuration:

Field	Value
Payload URL	Local: https://abc123.ngrok-free.app/webhooks/github

Production: https://your-domain.com/webhooks/github | | Content type | application/json | | Secret | Paste the secret from Step 1 | | SSL verification | Enable SSL verification (recommended) | | Events | Select "Let me select individual events":

✓ Issues

✓ Issue comments

✓ Pull requests |

Click "Add webhook" and verify it shows a green checkmark after delivery.

Step 4: Set Environment Variables

WEBHOOK_SECRET=your_secret_from_step_1

Important: The WEBHOOK_SECRET must match exactly what you entered in GitHub's webhook configuration.

Step 5: Configure Streaming (Optional)

GITHUB_STREAMING_MODE=batch  # batch (default) | stream

For streaming mode details, see Advanced Configuration.

Usage:

Interact by @mentioning @remote-agent in issues or PRs:

@remote-agent can you analyze this bug?
@remote-agent /command-invoke prime
@remote-agent review this implementation

First mention behavior: - Automatically clones the repository to /workspace - Detects and loads commands from .claude/commands/ or .agents/commands/ - Injects full issue/PR context for the AI assistant

Subsequent mentions: - Resumes existing conversation - Maintains full context across comments

---

4. Start the Application

Choose the Docker Compose profile based on your database setup:

Option A: With Remote PostgreSQL (Supabase, Neon, etc.)

Starts only the app container (requires DATABASE_URL set to remote database in .env):

# Start app container
docker compose --profile external-db up -d --build

# View logs
docker compose logs -f app

Option B: With Local PostgreSQL (Docker)

Starts both the app and PostgreSQL containers:

# Start containers
docker compose --profile with-db up -d --build

# Wait for startup (watch logs)
docker compose logs -f app-with-db

# Database tables are created automatically via init script

Option C: Local Development (No Docker)

Run directly with Node.js (requires local PostgreSQL or remote DATABASE_URL in .env):

npm run dev

Stop the application:

docker compose --profile external-db down  # If using Option A
docker compose --profile with-db down      # If using Option B

---

Usage

Available Commands

Once your platform adapter is running, you can use these commands:

Command	Description	Example
/help	Show available commands	/help
/clone <url>	Clone a GitHub repository	/clone https://github.com/user/repo
/repos	List cloned repositories	/repos
/status	Show conversation state	/status
/getcwd	Show current working directory	/getcwd
/setcwd <path>	Change working directory	/setcwd /workspace/repo
/command-set <name> <path>	Register a custom command	/command-set analyze .claude/commands/analyze.md
/load-commands <folder>	Bulk load commands from folder	/load-commands .claude/commands
/command-invoke <name> [args]	Execute custom command	/command-invoke plan "Add dark mode"
/commands	List registered commands	/commands
/reset	Clear active session	/reset

Example Workflow (Telegram)

🚀 Initial Setup

You: /clone https://github.com/anthropics/anthropic-sdk-typescript

Bot: ✅ Repository cloned successfully!

     📁 Codebase: anthropic-sdk-typescript
     📂 Path: /workspace/anthropic-sdk-typescript

     🔍 Detected .claude/commands/ folder

You: /load-commands .claude/commands

Bot: ✅ Loaded 5 commands:
     • prime - Research codebase
     • plan - Create implementation plan
     • execute - Implement feature
     • validate - Run validation
     • commit - Create git commit

💬 Asking Questions

You: What files are in this repo?

Bot: 📋 Let me analyze the repository structure for you...

     [Claude streams detailed analysis]

🔧 Working with Commands

You: /command-invoke prime

Bot: 🔍 Starting codebase research...

     [Claude analyzes codebase structure, dependencies, patterns]

You: /command-invoke plan "Add retry logic to API calls"

Bot: 📝 Creating implementation plan...

     [Claude creates detailed plan with steps]

ℹ️ Checking Status

You: /status

Bot: 📊 Conversation Status

     🤖 Platform: telegram
     🧠 AI Assistant: claude

     📦 Codebase: anthropic-sdk-typescript
     🔗 Repository: https://github.com/anthropics/anthropic-sdk-typescript
     📂 Working Directory: /workspace/anthropic-sdk-typescript

     🔄 Active Session: a1b2c3d4...

     📋 Registered Commands:
       • prime - Research codebase
       • plan - Create implementation plan
       • execute - Implement feature
       • validate - Run validation
       • commit - Create git commit

🔄 Reset Session

You: /reset

Bot: ✅ Session cleared. Starting fresh on next message.
     📦 Codebase configuration preserved.

Example Workflow (GitHub)

Create an issue or comment on an existing issue/PR:

@your-bot-name can you help me understand the authentication flow?

Bot responds with analysis. Continue the conversation:

@your-bot-name can you create a sequence diagram for this?

Bot maintains context and provides the diagram.

---

Advanced Configuration

Streaming Modes Explained

Stream Mode

Messages are sent in real-time as the AI generates responses.

Configuration:

TELEGRAM_STREAMING_MODE=stream
GITHUB_STREAMING_MODE=stream

Pros: - Real-time feedback and progress indication - More interactive and engaging - See AI reasoning as it works

Cons: - More API calls to platform - May hit rate limits with very long responses - Creates many messages/comments

**Best f