relayos 0.2.0a2

Agent Operating System — terminal-native AI workspace for persistent worker teams

RelayOS

You use Claude, GPT, Gemini, DeepSeek, and local models.
RelayOS makes them work together — automatically.

A terminal-native AI runtime that routes tasks to the right model,
remembers project context across sessions, and saves you money.

---

👋 The Problem

You open 5 browser tabs. ChatGPT for reasoning, Claude for architecture, Gemini for research, DeepSeek for coding. You copy output from one, paste it into the next. You burn premium tokens on tasks a free model could handle.

You waste 30% of your time managing tools instead of building.

🎯 The Solution

RelayOS is the coordination layer that makes your AI tools work like a real team:

┌─ You ──────────────────────────────────────┐
│                                             │
│   relay session ask "Build a payment sys"   │
│                                             │
└─────────────────────┬───────────────────────┘
                      │
┌─────────────────────▼───────────────────────┐
│              RelayOS                         │
│                                              │
│  1. Research competitors   → Gemini (FREE)   │
│  2. Design architecture   → Claude           │
│  3. Implement the code    → GPT              │
│  4. Security review       → DeepSeek (CHEAP) │
│  5. Document the API      → Gemini (FREE)    │
│                                              │
│  Total cost: $0.01    Time: 45s              │
└──────────────────────────────────────────────┘

Zero infrastructure. pip install relayos && relay. No Docker, no server, no browser.

---

✨ What Makes RelayOS Different

Feature	What It Does	Benefit
🧠 Smart Routing	Auto-selects the best model for each task	Free models first, premium only when needed
🔄 Multi-Step Plans	Decomposes tasks into execution graphs	One command, many AI models working together
💾 Project Memory	Knowledge persists across sessions	Workers never forget what they learned
💰 Cost Control	Per-model tracking + budget limits	No surprise bills
🔌 21 Terminal Types	Claude, GPT, Gemini, DeepSeek, local, and 16+ more	Bring your own tools
⌨️ Terminal Native	htop-style TUI, no browser needed	Stays in your workflow

---

⚡ Quick Start

Installation

pip install relayos

Try it — literally one command:

relay

Opens the control panel. Like htop, but for your AI team.

Chat with any model

# Auto-routes to best model
relay session chat "Explain Kubernetes architecture"

# Or target a specific worker
relay session chat "Design this API" -w architect

Execute a multi-step task

relay session ask "Build a JWT auth system in FastAPI"

RelayOS will automatically decompose, route, and execute across the best models for each step.

Plan before you spend

relay session plan "Build a payment system"
# Shows cost estimates before execution

Group discussion (multiple AI workers)

relay session group "Review this architecture"
# Each worker contributes: researcher → architect → reviewer

Switch models instantly

relay use opencode     # All tasks → OpenCode (free)
relay use mimo         # All tasks → Mimo (free)
relay use claude       # All tasks → Claude (premium)
relay use free         # Free-first routing

Project knowledge

relay project create my-app
relay session ask "Design the database" -p proj-id
relay session ask "Add caching later"   -p proj-id  # Knows previous decisions!
relay project knowledge proj-id                     # See accumulated knowledge

---

🖥️ The TUI

 Workers (1-9 select)         │ Status
                               │  Profile: balanced
 1 🧠 architect    ○ idle     │  Cost: $0.00
 2 🔍 researcher   ○ idle     │  Pending: 0
 3 ⭐ coder        ○ idle     │
 4 🎯 reviewer     ○ idle     │ Actions
 5 🐛 debugger     ○ idle     │  f=free  b=balanced
                               │  o=opencode  c=claude
═══════════════════════════════╪══════════════════════════════
 9w 9i 0b | inbox:0 | $0.00 | [balanced] | q=quit

Keyboard-driven, no mouse needed. One key to switch profiles or workers.

---

🗺️ Capability Graph

When you type relay session plan "Build a payment system", RelayOS generates:

Capability Graph: Build a payment system
Profile: balanced  |  Estimated cost: $0.0084
──────────────────────────────────────────────────────
  [1] research     Research requirements
       gemini-2.5-flash                FREE

  [2] architecture Design system architecture
       claude-sonnet-4-20250514        $0.0083  → research

  [3] review       Review architecture decisions
       deepseek-chat                   $0.0002  → architecture

──────────────────────────────────────────────────────
Each step passes only relevant data (not full text).
~800 tokens/step, ~7x less than naive approaches.

---

🔧 Supported Terminals (21 types)

Automatically detects what you have installed:

Status	Terminal	Default Model
✅	Claude Code	claude-sonnet-4-20250514
✅	Mimo Code	gpt-4o
✅	OpenCode	deepseek-chat
✅	Pi Coding Agent	gpt-4o
✅	Cursor	gpt-4o
✅	OpenClaw	gpt-4o
✅	GitHub Copilot	gpt-4o
✅	HuggingFace CLI	gpt-4o
⬜	OpenAI Codex	gpt-4o
⬜	Gemini CLI	gemini-2.5-flash
⬜	Aider	gpt-4o
⬜	ShellGPT	gpt-4o
⬜	Fabric	gpt-4o
⬜	ChatGPT CLI	gpt-4o
⬜	LLM CLI	gpt-4o
⬜	Kimi (Moonshot)	moonshot-v1-8k
⬜	Qwen CLI	qwen2.5:7b
⬜	Open Interpreter	gpt-4o
⬜	Continue	gpt-4o
⬜	Copilot Extension	gpt-4o
⚡	Custom	(configurable)

Add any CLI as a terminal:

relayos plugin add my-tool -m gpt-4o

---

🔧 All Commands

Command	What it does
relay	Open control panel
relay session chat	Single AI conversation
relay session ask	Auto-decompose + execute
relay session group	Multi-worker discussion
relay session plan	Show capability graph
relay session list	Recent sessions
relay use <terminal>	Switch default terminal
relay use <profile>	Switch cost profile
relay focus <worker>	SSH into a worker
relay team create	Create team from template
relay project create	Create knowledge project
relay project knowledge	Show project memory
relay plan "task"	Show execution plan
relay estimate "task"	Show cost estimates
relay run workflow.yaml	Run YAML workflow
relay config detect	Scan installed terminals
relayos plugin add	Register a custom CLI
relayos serve	Web dashboard (optional)

---

🏗️ Architecture

Terminal (relay / relayos)
         │
         ▼
┌────────────────────────────────────────────┐
│      ConversationEngine                    │
│  (session routing + capability detection)  │
└──────────────────┬─────────────────────────┘
                   │
┌──────────────────▼─────────────────────────┐
│        TaskGraphExecutor                   │
│  (schema-aware, artifact-passing, DAG exec) │
└──────────────────┬─────────────────────────┘
                   │
┌──────────────────▼─────────────────────────┐
│        ModelScheduler                      │
│  (15 models × 7 capabilities, cost-aware)   │
└──────┬──────────────────────┬──────────────┘
       │                      │
┌──────▼──────┐     ┌─────────▼──────────┐
│  Adapters   │     │  Knowledge Base     │
│  (21 terms) │     │  (SQLite, project)   │
└─────────────┘     └────────────────────┘

Storage (all local, zero infrastructure)

~/.relayos/           ← Single directory, portable
├── config.yaml       ← Your model/profiles config
├── state.db          ← Project state + decisions
├── sessions.db       ← Session history + messages
├── knowledge.db      ← Cross-session memory
├── artifacts.db      ← Structured step outputs
└── workers.db        ← Persistent workers

Design Philosophy

Principle	Why
Terminal-first	Developers live in the terminal. No browser needed.
State, not chat	Save decisions, not conversations. ~200x more compact.
Capability routing	Bind to task type, not model. Models change; tasks don't.
Zero infrastructure	Single process, local SQLite. No Docker, no Postgres, no Redis.
Cost-awareness	Free tiers first. Save money without thinking about it.

---

📈 Version History

Version	What
V0.1	Model routing — 5 provider adapters, YAML workflows
V0.2	Terminal pool — multi-CLI, cost tracking
V0.3	Worker system — 8 roles, persistence, TUI
V0.4	State compiler — structured state, event sourcing
V0.5	Model scheduler — 15 models, 3 cost profiles
V0.6	Session system — chat/ask/group modes
V0.7	Capability graph — multi-step task decomposition
V0.8	Task graph execution — schema-aware artifact passing
V0.9	Cross-session memory — project knowledge base

---

💪 Built With

Component	Tech
Language	Python 3.10+
CLI Framework	Click 8.0+
HTTP Client	HTTPX 0.27+
Terminal UI	Rich
Storage	SQLite (no external DB)
Models	15 scored models, 21 terminal types
License	Apache 2.0

Dependencies

Library	License	Purpose
Click	BSD-3-Clause	CLI framework
PyYAML	MIT	YAML parsing
HTTPX	BSD-3-Clause	HTTP client for model APIs
Rich	MIT	Terminal UI rendering

Credits

• Claude Code (Anthropic) — Primary development platform
• OpenCode — Terminal adapter & testing partner
• MimoCode — Terminal adapter for frontend workflows
• OpenAI Codex — Terminal adapter for coding tasks
• ECC plugin system — Agent orchestration patterns
• MCP (Model Context Protocol) — Tool integration protocol

---

📦 Installation

pip

pip install relayos

Optional: web dashboard

pip install relayos[server]
relayos serve --open

From source

git clone https://github.com/jjjjjjjjnnjnn/relayos.git
cd relayos
pip install -e .

Docker (web dashboard only)

docker build -t relayos .
docker run -p 8080:8080 -v $(pwd)/config:/root/.relayos relayos

---

🌐 Languages

• English
• 中文 (Chinese)
• Deutsch (German)
• Français (French)
• Español (Spanish)
• 日本語 (Japanese)
• 한국어 (Korean)

---

📄 License

Apache 2.0 Copyright 2026 jjjjjjjjnnjnn

---

Stop copy-pasting between AI tools.
Let them work together.


_{pip install relayos && relay}