Imagine a starship bridge where every officer is an AI agent - one navigates code, another monitors systems, a third plans complex maneuvers. Codex Orbit is that bridge, accessible from anywhere via Telegram. While existing tools let you observe Codex, we let you orchestrate a fleet of AI coding agents, local and cloud-based, through a single Telegram interface. No clunky dashboards, no VPNs - just pure, distributed AI power at your fingertips.
Current Codex remote tools (like the existing codex-tg) let you watch a single AI coding thread. But modern development demands multi-agent collaboration. Codex Orbit transforms Telegram into a mission control center where you:
- Deploy and manage multiple Codex instances simultaneously
- Route tasks between OpenAI's Codex and Claude's Opus models
- Run local coding agents alongside cloud-based ones
- Observe, interrupt, and redirect any agent in real-time
- Scale from solo developer to team-scale agent clusters
Think of it as Kubernetes for AI coding agents - but controlled via Telegram chat.
Codex Orbit doesn't replace your AI agents. It conducts them. Like a symphony conductor who doesn't play every instrument but shapes every note, you maintain full control over your AI orchestra. The Telegram interface becomes your baton.
graph TD
A[Telegram User] --> B[Orbit Bot]
B --> C{Agent Router}
C --> D[OpenAI Codex Cluster]
C --> E[Claude Opus Engine]
C --> F[Local Agents Pool]
D --> G[Thread 1: Code Generation]
D --> H[Thread 2: Debugging]
E --> I[Thread 3: Architecture Planning]
F --> J[Thread 4: Local Testing]
B --> K[Observer Dashboard]
K --> L[Real-time Logs]
K --> M[Agent Health Status]
K --> N[Resource Usage Metrics]
B --> O[Automation Engine]
O --> P[Cron Jobs]
O --> Q[Event Triggers]
- Parallel Deployment: Run 10+ agents simultaneously across different models
- Smart Task Routing: Auto-assign tasks to the best-suited agent (e.g., Claude for planning, Codex for coding)
- Cross-Model Communication: Agents can share context and results between different AI models
- Live Feed: Watch agent thinking in real-time (like peeking over a junior dev's shoulder)
- Pause/Resume: Freeze any agent mid-task, tweak parameters, and resume
- Branch & Merge: Fork an agent's work into parallel experiments, then merge the best
- Codex Local Mode: Run agents on your machine for sensitive code
- Docker Workers: Deploy ephemeral agents in containers
- Edge Computing: Use Raspberry Pi clusters for low-latency agent responses
- Interface in 12 languages (English, Spanish, French, German, Japanese, Korean, Chinese, Arabic, Hindi, Portuguese, Russian, Italian)
- Agents can be instructed in any language; responses adapt automatically
- Automated Monitoring: Agents alert you via Telegram when their peers fail
- Self-Healing: Orphaned agents get automatically reassigned
- Human-in-the-Loop: Any escalation route can redirect to you
| Operating System | Support Status | Notes |
|---|---|---|
| 🐧 Linux (Ubuntu 20.04+) | ✅ Full | Recommended for production |
| 🪟 Windows 10/11 | ✅ Full | Docker Desktop required |
| 🍎 macOS (M1/M2/M3) | ✅ Full | Native ARM64 support |
| 🐳 Docker (any OS) | ✅ Best | Optimized for containerization |
| 📱 Android (Termux) | No Claude API support | |
| 🖥️ Raspberry Pi OS | ✅ Full | Great for always-on agent hubs |
This YAML profile defines a development team with three specialized agents:
team:
name: "Squadron-A"
agents:
- name: "Architect"
model: "claude-opus-4"
role: "system_planner"
threads: 1
instructions: "Generate detailed architecture blueprints. Always include trade-off analysis."
- name: "Coder"
model: "codex-gpt-4"
role: "code_generator"
threads: 3
instructions: "Implement features with 95%+ test coverage. Use clean architecture patterns."
- name: "Debugger"
model: "codex-gpt-3.5"
role: "quality_assurance"
threads: 2
instructions: "Identify bugs, suggest fixes, and run automated test suites."
routing:
default_agent: "Coder"
fallback_sequence: ["Coder", "Debugger", "Architect"]
parallel_approval: true # Requires 2 agents to agree on critical changes
monitoring:
health_check_interval: 30 # seconds
alert_on_failure: true
telemetry_level: "detailed" # minimal | detailed | verboseStart the Orbit bot with a custom team:
python orbit.py \
--token "YOUR_TELEGRAM_BOT_TOKEN" \
--openai-key "sk-..." \
--claude-key "sk-ant-..." \
--profile "squadron-a.yaml" \
--local-agents 2 \
--auto-deploy new-feature-trackerExpected output (first 10 seconds):
[2026-04-15 10:30:01] 🚀 Orbit Bot v3.2.1 initializing...
[2026-04-15 10:30:02] ✅ Telegram connection established
[2026-04-15 10:30:03] ⏳ Connecting to OpenAI Codex... OK (3 threads available)
[2026-04-15 10:30:04] ⏳ Connecting to Claude Opus... OK (1 thread reserved)
[2026-04-15 10:30:05] 🎯 Agent profile "Squadron-A" loaded
[2026-04-15 10:30:06] 🔧 Local agents pool: 2 nodes ready
[2026-04-15 10:30:07] 👂 Listening for commands on @YourOrbitBot
[2026-04-15 10:30:08] 💡 Tip: Send /help to see all available commands
- Python 3.9+
- Telegram Bot Token (from @BotFather)
- OpenAI API Key (with Codex access)
- Claude API Key (optional, for hybrid mode)
-
Download the latest release:
-
Install dependencies:
pip install -r requirements.txt
-
Configure your environment:
cp .env.example .env nano .env # Add your API keys -
Launch Orbit:
python orbit.py --auto-configure
-
Open Telegram, find your bot, and send:
/start
| Command | Action | Example |
|---|---|---|
/deploy [name] |
Create new agent team | /deploy feature-login |
/status |
Show all active agents | - |
/pause [agent_id] |
Freeze a specific agent | /pause coder-3 |
/log [agent_id] |
View agent's recent thoughts | /log architect-1 |
/route [task] to [agent] |
Force-assign a task | /route "Refactor auth" to coder-2 |
/scale [n] |
Add N local agent nodes | /scale 3 |
/analytics |
7-day performance report | - |
/help |
Full command list | - |
IMPORTANT: Codex Orbit gives you powerful control over AI agents that can execute code, access files, and communicate externally.
- Never expose your bot token or API keys in public repositories
- Isolate agent environments using Docker containers
- Audit agent actions regularly using the telemetry dashboard
- Understand that AI agents may produce incorrect or harmful code - always review before production use
- For local agents, ensure your machine has adequate security controls
The authors of Codex Orbit are not responsible for any damage, data loss, or security breaches resulting from the use of this software. Use at your own risk. Always maintain human oversight of AI-generated changes.
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright (c) 2026
Codex Orbit: Because one AI is a tool, but an AI orchestra is a revolution. 🌟
Built for developers who want to control the future, not just observe it.