sand0vvv/fleet
A fleet of AI coding agents in your Telegram supergroup. Self-hosted, local, no account. - sand0vvv/fleet
0 stars · 0 forks · JavaScript Topics: cli, remote-control, telegram, mcp, self-hosted, codex, ai-agents, claude-code
README
fleet
A fleet of AI coding agents in your Telegram supergroup. Self-hosted · local · no account.
Fleet lets you drive a whole team of AI coding agents — Claude Code and Codex — from your phone, in a single Telegram supergroup. Each agent gets its own topic in the group. You text (or voice-message) them, they work on your machine and text back: code, files, screenshots, questions, progress. Everything runs locally. No cloud service, no sign-up, no dashboard. Your Telegram bot token and API keys stay on your machine in ~/.fleet/config.json. Telegram is reached via long-polling — no public URL, no webhook, works behind any NAT.
Built in public and still early — expect rough edges. Issues and PRs welcome.
Quickstart 0. Prerequisites — Node.js ≥ 18 and Claude Code installed and logged in (claude in your PATH). Codex is optional. 1. Make a bot — talk to @BotFather in Telegram: /newbot, pick a name, copy the token. 2. Make the group — create a Telegram group, enable Topics (group settings → Topics), and add your bot as admin (it needs to manage topics). 3. Install & configure: npm i -g @sand0vvv/fleet fleet init # asks for the bot token, voice provider, defaults fleet doctor # green lights = ready fleet start # the runner — keep this terminal open 4. Link — send /link in your supergroup. The runner binds itself to you (your Telegram user id) and that group. From then on only you can command the fleet. 5. Spawn an agent — in the group's General topic: /spawn C:\path\to\your\project
A topic appears named after the folder, a terminal window opens on your machine, and the agent is live. Text the topic — the agent answers there. Or from a terminal on the machine: cd into any project and run fleet claude (or fleet codex). What it looks like Telegram supergroup ├─ General ← fleet commands: /spawn /list /usage … ├─ 🟢 my-webapp ← Claude Code agent, running ├─ 🟢 my-webapp-codex ← Codex agent in the same folder └─ 🟡 data-pipeline ← parked (wakes on your next message)
Topic titles carry live status: 🟢 running · 🟡 parked · 🔴 stopped/crashed. While an agent works on your message, the topic shows typing…. Every agent runs on your machine. Claude agents live in a real terminal window you can watch and type into; close the window and the agent parks (frees resources) — it wakes automatically on your next message, with its session continued (--resume/--continue). Codex agents open their own console window and also resume their last session on wake. A fresh session only happens when you ask for one (/new). Commands Send these in Telegram (the bot's / menu shows them too):
Command Where What it does
/link anywhere in the group bind the fleet to you + this supergroup (first run)
/spawn <path> [codex] [model] General new agent for a folder (its own topic + window)
/list General all agents and their state
/usage anywhere real Claude limits panel (5h session / weekly) from your local login
/status <agent> General one agent's state, session, context size
/context topic the agent's real /context output, relayed to Telegram
/compact /clear topic native Claude commands, typed into the live terminal
/model topic model picker (buttons)
/hide / /show topic close the window (agent keeps running) / reopen it
/stop / /restart topic stop the process / kill + respawn
/new topic arm a fresh session (applied on next restart)
/sessions / /use <id> topic list this folder's sessions / resume a specific one
/rename <name> topic rename agent + topic
/kill topic remove the agent: process, topic, record
/help anywhere contextual: fleet commands in General, agent commands in a topic
Any other slash command you type in an agent's topic (e.g. /cost, /doctor, /review) is forwarded straight into the agent's terminal as a native command. Voice: send a voice message in an agent's topic — it's transcribed (Groq / OpenAI / local Whisper, your choice in fleet init) and delivered as text. Files: agents send files and screenshots back into their topic; anything you attach in the topic is downloaded into the agent's .inbox/ and handed to it. The CLI fleet init set up bot token, whisper, defaults (re-run safe; secrets shown masked) fleet start run the fleet (single instance — a stale runner is replaced automatically) fleet stop stop the running fleet fleet update stop → npm i -g latest → restart, in one command fleet logs [n] last n lines of the runner log fleet autostart on|off start the fleet at logon (Windows) fleet claude spawn a Claude agent for the current folder fleet codex spawn a Codex agent for the current folder fleet doctor check node/claude/codex/token/link fleet status show current config + version
Every command tells you when a newer version is on npm; the runner also drops a one-liner into your group. How it works Telegram ⇄ long-poll ⇄ fleet runner (your machine) ├─ localhost HTTP+WS (for the MCP below — nothing exposed) ├─ Claude agents → node-pty terminal + fleet MCP (send_message/send_file, │ channel injection for incoming messages) └─ Codex agents → own console window; codex-shell drives the official `codex app-server` JSON-RPC to inject your messages live
The runner long-polls the Telegram Bot API — no inbound ports, no webhook, no public URL. A message in an agent's topic is routed to that agent's local process. Each agent has a small fleet MCP that dials the runner back on localhost to push replies and files up to Telegram; incoming messages are injected into the live session (Claude: channel notification; Codex: turn/start over the app-server protocol). The runner posts the agent's reply into the right topic.
Reliability, both directions. Messages to a parked/offline agent are queued on disk and delivered when it wakes — nothing is lost if you closed the window. Replies and files from agents survive network hiccups the same way (on-disk outbox, retried in order). Rapid consecutive messages are debounced into one delivery (configurable, 0 = instant). A crashed agent is auto-restarted (crash-loop guarded), and if the runner itself dies it posts a crash report into your group before going down. State: everything lives in ~/.fleet/ — config.json (token, owner, group, defaults), state.json (agents/topics/sessions), delivery queues, logs. Secrets never touch a project directory, so they can't be committed by accident. Delete the folder to factory-reset. (Override the config path with the FLEET_CONFIG env var.) Troubleshooting
fleet doctor first — it checks everything. fleet logs shows the runner's recent log. Port busy: fleet start kills a stale runner and takes over by itself. If a non-fleet process holds the port, set "port" in ~/.fleet/config.json. Bot doesn't react: make sure the bot is an admin of the group and Topics are enabled; then /link again. No terminal window pops: run fleet start in a real console (not a background service); /show retries and tells you honestly if the window failed. Windows: if git-bash is installed agents use it, otherwise plain cmd.exe — both work.
Repo layout
Branch What
standalone this version — local, npm, long-polling. The one to use.
legacy the original cloud architecture (FastAPI backend + Postgres + webhook)
legacy-docker legacy variant that jails agents in a Docker sandbox
Author Built by @sand0vvv. License MIT