Your AI staff, managed from chat.
Clone. Configure. Talk. You get a team of AI agents — each with its own chat topic/channel — orchestrated by Robyx, your principal coordinator. Works on Telegram, Discord, and Slack.
Why Robyx
There are many AI agent platforms out there — some with hundreds of pre-built skills, integrations with every service imaginable, and complex configuration systems.
Robyx takes the opposite approach.
You don't get a pre-built team. You build your own.
Robyx gives you a blank canvas: an orchestrator, a control room on your messaging platform, and the ability to create agents through conversation. You tell Robyx what you need, and it creates the workspace, the agent, the instructions — all on the fly. Need a deployment specialist? Ask Robyx. Need a scheduled monitor? Describe what it should check. Need a code reviewer that knows your architecture? Define it in natural language.
No marketplace. No pre-packaged skills. No vendor lock-in. Just a simple system that grows with your needs — from one agent to a full team, built bottom-up from your actual requirements.
The philosophy is simple: one control room, one AI CLI tool, infinite flexibility.
Core Concepts
Robyx has three roles, all living inside your messaging platform:
| Role | What it is | Where it lives |
|---|---|---|
| Robyx (orchestrator) | The principal coordinator. Routes requests, creates workspaces and specialists, delegates, keeps the control room scannable. | The main/control-room topic |
| Workspace agents | One agent per project/topic. Owns its own instructions, its own git branch, its own conversation. Knows the project deeply. | A dedicated topic prefixed with the workspace name |
| Specialists | Cross-functional helpers (code reviewer, writer, deploy agent…). Invoked by other agents when a skill is needed. | Their own topic, reachable via [REQUEST @name: …] |
And four task types, all handled by a single 60-second scheduler:
| Type | Use case | Example |
|---|---|---|
interactive |
You talk, it answers | Everyday chat with any agent |
one-shot |
Fire once at a future time | "Deploy tonight at 23:00" |
scheduled / periodic |
Runs on a recurring timer | "Every hour check BTC price" |
continuous |
Iterative autonomous work with its own git branch, state file, and per-task plan, running step-by-step until an objective is reached | "Run a research loop training variants until SSIM > 0.98" |
How Orchestration Works in Practice
The control room is a group chat with topics. Each topic is an agent. You talk, agents work.
- You ask Robyx for something. "I need a workspace that monitors my servers."
- Robyx creates it on the fly. A new topic appears, Robyx writes the agent's brief from your description, registers it in the scheduler, and spawns it. Zero config files.
- You talk to the new agent in its topic. It owns the work. Every message is contextually its own. If it needs a cross-functional skill, it asks a specialist via
[REQUEST @name: …]. - You can delegate, focus, or jump topics.
[FOCUS @agent]routes your next messages straight to it;[FOCUS off]returns to Robyx. - Long-running work stays in the workspace chat. Ask any workspace for an iterative research or optimization loop and it spins up a continuous task: git branch, state file, per-task
plan.md, automatic step-by-step execution. Every step report comes back here with a🔄 [<task-name>]prefix — no separate channel to watch. Talk to the primary workspace agent to list, stop, pause, resume, ask about the plan, or update the scope / checkpoint policy of a running task in place (the agent is always aware of the tasks it owns and edits them instead of creating duplicates). - Reminders and timers are native. Any agent can emit
[REMIND in="1h" text="…"]or[REMIND at="…" agent="…" text="…"]to schedule a message or an autonomous run. No code, no external cron. - Everything survives restarts. State, queue, continuous task progress, scheduled jobs — all persisted under
data/. Late-firing on recovery means no event is lost if the bot was offline.
Main Features
- Build your team by talking — workspaces, specialists, and agent briefs created from chat. No YAML, no dashboards.
- Three messaging platforms — Telegram, Discord, Slack. Switch at any time; all workspaces and memory are preserved.
- Three AI backends — Claude Code, Codex, OpenCode. Pick per-agent via semantic aliases (
fast,balanced,powerful) or explicit model IDs inmodels.yaml. - Unified 60 s scheduler — reminders, one-shot, periodic, and continuous tasks in a single queue (
data/queue.json) with atomic claims and late-firing on recovery. - Continuous autonomous tasks — step-by-step research/optimization loops with per-task git branch, structured state, per-task
plan.md, and four configurable checkpoint policies (on-demand,on-uncertainty,on-milestone,every-N-steps). Lifecycle (list, status, stop, pause, resume, read plan, update scope/policy in place) is controlled from the parent workspace chat — no dedicated control channel. - Agent interruption — any message to a busy agent immediately (SIGTERM → 5 s grace → SIGKILL) stops the current step and processes your new request.
- Collaborative workspaces — invite external collaborators into a separate Telegram group with a role-based authorization model (Owner / Operator / Participant) and two interaction modes (intelligent or passive). Telegram-only today; Discord and Slack fall back to owner-only workspaces.
- Memory system — per-agent active + archive tiers, integrated with Claude Code memory files.
- Voice + images — voice transcription via Whisper, agent-initiated image delivery (explicit
[SEND_IMAGE …]only, never proactive). - Safe auto-updates — tag-based releases, pre-update snapshot, smoke test, atomic rollback on failure; migration chain runs once per version.
- Autonomous-by-default permissions — CLI backends run with permissions to act; you stay in charge via chat.
- Production-grade service — launchd / systemd / Task Scheduler installers with keep-alive, logs, single-instance lock.
Documentation
| Topic | What's inside |
|---|---|
| Architecture | How it works, the three roles (Robyx / workspaces / specialists), workspace lifecycle |
| Scheduler | Reminders, one-shot, periodic, and continuous tasks; agent interruption; runtime contract |
| Memory System | Active + archive memory tiers, integration with existing Claude Code memory |
| Building Your Team | How to grow your fleet of agents through conversation |
| Configuration | Every env var, per-platform settings, in-chat config updates, platform migration |
| Commands | Slash command reference (Telegram + Discord) |
| AI Backends | Claude Code / Codex / OpenCode, autonomous-by-default permissions, models.yaml |
| Voice + Images | Voice transcription via Whisper, agent-initiated image delivery |
| Auto-Updates + Migrations + Service Management | Update flow with snapshots & smoke tests, migration framework, service installers |
| Data Directory Contract | What lives under data/, who writes it, what is safe to delete, backup & recovery |
Two more useful refs at the repo root:
ORCHESTRATOR.md— Robyx's behaviour reference ([REMIND],[DELEGATE], etc.)AGENTS.md— Conventions for agent / specialist briefsCHANGELOG.md— Per-version changes; full notes underreleases/
Quick Start
Prerequisites
- Python 3.10+
- One CLI-based AI tool: Claude Code | Codex CLI | OpenCode
- A messaging platform: Telegram, Discord, or Slack
The setup wizard guides you through everything. You can switch platforms at any time by telling Robyx — all your workspaces, agents, and memory are preserved.
Step 1: Clone and run the setup wizard
git clone https://github.com/terrordrummer/robyx-ai.git && cd robyx-ai python3 setup.py
The wizard asks which platform to use, then walks you through the setup.
Step 2: Create a bot on your chosen platform
Telegram
- Open Telegram and message @BotFather
- Send
/newbot, pick a name and username - Copy the token — the setup wizard handles the rest (auto-detects chat ID and owner ID when you add the bot to a group)
Discord
- Enable Developer Mode in Discord — this is required to copy Server ID and User ID in the steps below. Without it, the "Copy ID" options won't appear in right-click menus and you won't be able to complete the setup.
- Open Discord → click the gear icon (⚙️) at the bottom left → App Settings → Advanced → toggle Developer Mode ON
- Go to discord.com/developers/applications
- Click New Application → name it (e.g. "Robyx")
- Left menu → Bot → click Reset Token → copy the token
- Scroll down → enable Message Content Intent
- Left menu → OAuth2 → URL Generator → select scope bot, then enable these permissions:
- Send Messages
- Manage Channels
- Read Message History
- Create Public Threads
- Send Messages in Threads
- Paste the token in the setup wizard — it generates the invite link for you
- Open the invite link → select a server (or create one) → Authorize
- If detection succeeds, the interactive setup auto-detects the server, creates
#control-room, and finds your user ID; otherwise it falls back to asking for the IDs manually
Slack
- Go to api.slack.com/apps → Create New App
- Choose From scratch, name it, select your workspace
- OAuth & Permissions → add scopes:
chat:write,channels:manage,channels:read,files:read - Install to Workspace → copy the Bot Token (
xoxb-...) - Basic Information → App-Level Tokens → generate one with
connections:write→ copy (xapp-...) - Socket Mode → enable it
Step 3: Install as system service
./install/install-mac.sh # macOS (launchd) ./install/install-linux.sh # Linux (systemd) # powershell install/install-windows.ps1 # Windows
That's it. Open your messaging platform and start talking to Robyx.
Project Structure
robyx-ai/
├── setup.py # Setup wizard (interactive or CLI flags)
├── ORCHESTRATOR.md # Robyx's behavior reference
├── AGENTS.md # Agent / specialist conventions
├── CHANGELOG.md # Per-version summaries
├── docs/ # Topical documentation (linked from README)
├── releases/ # Full release notes per version
├── templates/
│ ├── prompt_orchestrator.md # Robyx system prompt (loaded by bot/config.py)
│ ├── prompt_workspace_agent.md # Workspace agent system prompt
│ ├── prompt_focused_agent.md # Focused-mode agent system prompt
│ ├── prompt_collaborative_agent.md# Collaborative-workspace agent system prompt
│ ├── CONTINUOUS_SETUP.md # Continuous-task setup interview prompt
│ └── CONTINUOUS_STEP.md # Step-agent prompt (per-step dispatch)
├── VERSION # Current version
├── bot/ # Python application
│ ├── _bootstrap.py # Start-up dep sanity check (runs before imports)
│ ├── bot.py # Entry point + service jobs
│ ├── config.py # All config from .env + system prompts
│ ├── config_updates.py # Direct KEY=value .env updates from chat
│ ├── agents.py # Agent model & session manager
│ ├── ai_backend.py # AI backend abstraction
│ ├── ai_invoke.py # CLI invocation, streaming, response patterns
│ ├── handlers.py # Command & message handlers (platform-agnostic)
│ ├── scheduler.py # Unified scheduler (reminders, one-shot, periodic, continuous)
│ ├── continuous.py # Continuous task state management
│ ├── lifecycle_macros.py # [LIST_TASKS] / [STOP_TASK] / [PAUSE_TASK] / [RESUME_TASK] / [GET_PLAN] dispatcher
│ ├── update_plan_macro.py # [UPDATE_PLAN] — partial in-place continuous-program merge
│ ├── scheduled_delivery.py # Output relay from scheduled runs to topics
│ ├── task_runtime.py # Agent context resolver for scheduled tasks
│ ├── memory.py # Agent memory system
│ ├── model_preferences.py # Backend-aware model alias resolution
│ ├── topics.py # Workspace/channel creation
│ ├── media.py # Outgoing image compression (Pillow)
│ ├── migrations/ # Migration framework (chain + legacy registry)
│ │ ├── base.py # Migration / MigrationContext / version utils
│ │ ├── runner.py # Chain discovery + execution
│ │ ├── tracker.py # data/migrations.json persistence
│ │ ├── legacy.py # Pre-0.20.12 name-keyed registry
│ │ └── vX_Y_Z.py # One per release, continuous chain
│ ├── session_lifecycle.py # Session invalidation logic
│ ├── updater.py # Auto-update system (snapshots + smoke test)
│ ├── process.py # Subprocess management
│ ├── voice.py # Voice transcription (Whisper)
│ ├── i18n.py # UI strings
│ └── messaging/ # Platform adapters
│ ├── base.py # Platform ABC + PlatformMessage dataclass
│ ├── telegram.py # Telegram adapter
│ ├── discord.py # Discord adapter
│ └── slack.py # Slack adapter
├── install/ # Platform installers
├── scripts/ # Dev tooling (e.g. new_migration.py)
├── tests/ # Test suite (960+ tests)
└── data/ # Runtime data (gitignored, created on first boot)
├── bot.pid # Single-instance lock
├── state.json # Agent state persistence
├── queue.json # Unified scheduler queue (all task types)
├── tasks.md # (legacy pre-0.20 — read-only migration source)
├── specialists.md # (legacy pre-0.20 — read-only migration source)
├── agents/ # Workspace agent briefs (.md)
├── specialists/ # Specialist briefs (.md)
├── continuous/ # Per-task state.json + plan.md
├── migrations.json # Applied migrations tracker
├── collaborative_workspaces.json # Collaborative-workspace registry
├── backups/ # Pre-update tar snapshots (retention: 3)
└── memory/ # Centralized memory — orchestrator + specialists only
# (workspace memory lives at <work_dir>/.robyx/memory.db)
License
MIT — Roberto Sartori