A persistent AI assistant — text your agent on Telegram, it works in your codebase.
relay is a lightweight C daemon that routes Telegram messages to Claude Code (or Gemini, or OpenAI Codex) running on your machine. Configure workspaces, switch between them like browser tabs, and your agent picks up exactly where you left off.
No cloud infrastructure. No web UI. Just a process on your machine and your Telegram app.
→ Architecture notes — why C, how the agent bus works, the trade-offs I took. → Seven days, 194 tasks, one daemon — retrospective on how do-work built relay in a week.
git clone git@github.com:rawphp/relay.git
cd relay
./install.shThe installer asks for a name, your Telegram credentials, and your first workspace. It builds the daemon, creates the runtime directory, and writes your config. Done in under two minutes.
You (Telegram) → relay daemon → Claude Code subprocess → You (Telegram)
Send a message. The daemon routes it to Claude Code in your active workspace, streams the response back to Telegram, and saves the session so the conversation continues next time.
| Multi-workspace | Configure any number of project directories and switch between them from Telegram |
| Per-workspace providers | Use Claude for one project, Codex for another, Gemini for a third |
| Persistent sessions | Conversations survive daemon restarts — picks up where you left off |
| Identity files | Give your agent a personality, goals, and memory that persist across sessions |
| Memory system | Optional semantic search over past conversations — relevant context injected automatically |
| Agent bus | Agents discover each other automatically, exchange messages, and persist offline messages — with human observer notifications |
| No cloud | Runs entirely on your machine — only outbound connections are to Telegram and your LLM |
| Command | Description |
|---|---|
/start | Get started |
/help | Show available commands |
/status | Show daemon and memory status |
/restart | Restart the daemon |
/clear | Start a new conversation |
/close | Close the active space |
/space <name> | Switch space |
/spaces | List all spaces |
/session <number> | Select session from listing |
/sessions | Browse resumable sessions |
/workspace | Show current workspace info |
/reload | Reload config without restart |
/bus | Show recent agent bus activity |
- macOS or Linux
- Xcode Command Line Tools or gcc
curl- At least one LLM CLI, installed and authenticated:
- Claude Code:
npm install -g @anthropic-ai/claude-code - OpenAI Codex:
npm install -g @openai/codex - Gemini CLI:
npm install -g @google/gemini-cli
- Claude Code:
- A Telegram bot token — @BotFather
- Your Telegram user ID — @userinfobot
| Installation & Configuration | Prerequisites, install.sh, relay.conf reference |
| Operations | CLI commands, updating, multi-agent setup |
| Identity Files | Customizing your agent's personality and memory |
| Architecture | How the daemon works internally |
| Development Guide | Building, testing, and extending relay |
cd relay
git pull
./update.shRebuilds the binary, redeploys to all registered agents, restarts. Config, identity files, sessions, and transcripts are never touched.
MIT