Robyx-AI, Your AI staff, managed from chat

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

116 Commits

116 Commits

.specify

.specify

bot

bot

docs

docs

install

install

releases

releases

scripts

scripts

specs

specs

templates

templates

tests

tests

.env.example

.env.example

.gitignore

.gitignore

AGENTS.md

AGENTS.md

BACKLOG.md

BACKLOG.md

CHANGELOG.md

CHANGELOG.md

CLAUDE.md

CLAUDE.md

LICENSE

LICENSE

ORCHESTRATOR.md

ORCHESTRATOR.md

README.md

README.md

VERSION

VERSION

migrate-from-kaelops.sh

migrate-from-kaelops.sh

models.yaml

models.yaml

pytest.ini

pytest.ini

robyx-ai.png

robyx-ai.png

robyx-banner.png

robyx-banner.png

setup.py

setup.py

Repository files navigation

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 🔄 [] 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 in models.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 briefs

CHANGELOG.md — Per-version changes; full notes under releases/

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_d

[truncated for AI cost control]