Remoat

Control your AI coding assistant from anywhere — right from Telegram.

Remoat is a local Telegram bot that lets you remotely operate Antigravity IDE on your PC — from your phone, tablet, or any device with Telegram.

Type a natural-language instruction, attach a screenshot, or send a voice note. Remoat dispatches it to Antigravity via Chrome DevTools Protocol, monitors progress in real time, and streams results back to Telegram. Everything runs on your machine.

• Quick Start
• Features
• Advanced Setup
• Commands
• Troubleshooting
• How It Works
• Project Structure
• Contributing
• License

• Node.js 18 or higher
• Antigravity installed on your machine
• A Telegram account

xcode-select --install

npm install -g remoat

Or with Homebrew (macOS/Linux):

brew tap optimistengineer/remoat
brew install remoat

remoat setup

The wizard walks you through:

• Telegram Bot Token — Create a bot via @BotFather on Telegram (/newbot), then copy the token it gives you
• Allowed User IDs — Only these Telegram users can control the bot. Message @userinfobot to get your ID
• Workspace Directory — The parent directory where your coding projects live (e.g. ~/Code)

remoat open

remoat start

That's it. Open Telegram, find your bot, and start sending instructions.

npx nodejs-whisper download

Having issues? Run remoat doctor to diagnose your setup.

Remote control from anywhere — Send natural-language prompts, images, or voice notes from your phone. Antigravity executes them on your PC with full local resources.

Project isolation via Telegram Topics — Each project maps to a Telegram Forum Topic. All messages within a topic automatically use the correct project directory and session history — no manual context switching needed.

Real-time progress streaming — Long-running tasks report progress in phases (sending, thinking, complete) with a live process log and elapsed timer, streamed as Telegram messages.

Voice input — Hold the mic button and speak. Remoat transcribes locally via whisper.cpp — no cloud APIs, no Telegram Premium required.

Approval routing — When Antigravity asks for confirmation (file edits, plan decisions), the dialog surfaces in Telegram with inline action buttons. Or toggle /autoaccept to approve automatically.

Security by design — Whitelist-based access control. Path traversal prevention. Credentials stored locally. No webhooks, no port exposure.

git clone https://github.com/optimistengineer/Remoat.git
cd Remoat
npm install
cp .env.example .env

Edit .env with your values:

TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USER_IDS=123456789
WORKSPACE_BASE_DIR=~/Code
USE_TOPICS=true

Then start the bot:

npm run dev       # development mode with auto-reload
# or
npm start         # run from source

Remoat connects to Antigravity via Chrome DevTools Protocol. Launch Antigravity with a debug port enabled:

remoat open       # auto-selects an available port (9222, 9223, 9333, 9444, 9555, or 9666)

From source, you can also use the bundled launcher scripts:

Launch Antigravity first, then start the bot. It connects automatically.

Antigravity IDE v2 renamed the Windows install folder and executable (note the space). Remoat supports both: it probes the v2 location first, then the v1 location, and uses the first one that actually exists — so a v1 install keeps working unchanged.

ANTIGRAVITY_PATH always wins over all of the above. On macOS v2 (verified on 2.0.10) the .app bundle is still named Antigravity.app — the rename is Windows-only.

Run remoat doctor to see exactly which path was resolved, and the full probed list if none was.

For multi-project workflows, Remoat supports Telegram Forum Topics — each project gets its own topic thread.

1. Create a Telegram supergroup and enable Topics in group settings
2. Add your bot to the group with admin permissions
3. Set USE_TOPICS=true in .env (this is the default)

For simpler setups, set USE_TOPICS=false and use the bot in a regular chat.

remoat              auto-detect: runs setup if unconfigured, otherwise starts the bot
remoat setup        interactive setup wizard
remoat open         launch Antigravity with CDP port enabled
remoat start        start the Telegram bot
remoat doctor       diagnose configuration and connectivity issues
remoat --verbose    show debug-level logs (CDP traffic, detector events)
remoat --quiet      errors only

Just type in any bound topic or direct chat:

refactor the auth components — see the attached screenshot for the target layout

Or hold the mic button and speak — the voice note gets transcribed locally and sent as a prompt.

Run diagnostics first:

remoat doctor

This checks your config, Node.js version, Xcode tools (macOS), Antigravity installation, and CDP port connectivity.

npm install fails with gyp ERR! on macOS — Install Xcode Command Line Tools: xcode-select --install

remoat open can't find Antigravity — Standard install locations are probed automatically (see Antigravity v1 vs v2); nothing has to live in /Applications. Run remoat doctor to see which path resolved and the full probed list. If your install is somewhere else, set ANTIGRAVITY_PATH in your .env file or environment:

# macOS — normally NOT needed, see the note below
export ANTIGRAVITY_PATH="/Applications/Antigravity.app/Contents/MacOS/Antigravity"
# Windows (cmd)
set ANTIGRAVITY_PATH=C:\Users\you\AppData\Local\Programs\Antigravity IDE\Antigravity IDE.exe
# Linux
export ANTIGRAVITY_PATH=/opt/applications/antigravity.AppImage

remoat open

macOS users: leave ANTIGRAVITY_PATH unset. remoat open launches the app with open -a, which locates the bundle through LaunchServices no matter where it lives, and the Antigravity IDE rename is Windows-only — the macOS bundle is still Antigravity.app with a Contents/MacOS/Antigravity binary. Setting ANTIGRAVITY_PATH switches remoat open to a direct-binary launch, so a wrong value turns a working setup into Failed to open ….

Paths with spaces: quote the value when you export it in a shell, but do not quote it inside .env — dotenv reads the value literally, and the surrounding quotes would become part of the path. Correct .env line: ANTIGRAVITY_PATH=C:\Users\you\AppData\Local\Programs\Antigravity IDE\Antigravity IDE.exe

Chat input field not found when sending a message — This was the Antigravity IDE v2 symptom fixed in #15 (the composer's ARIA role changed from textbox to combobox). If it reappears after an Antigravity update, run the bot with LOG_LEVEL=debug and include the Chat input matched tier … / Chat input not found after … line in your report — see docs/ANTIGRAVITY_DOM_SELECTORS.md.

PowerShell: remoat doctor prints the manual launch command in cmd syntax. For a detected v2 install that command starts with a quoted full path ("C:\Users\you\AppData\Local\Programs\Antigravity IDE\Antigravity IDE.exe" --remote-debugging-port=9222), which PowerShell parses as a string expression rather than a command. Prefix it with the call operator: & "C:\Users\you\AppData\Local\Programs\Antigravity IDE\Antigravity IDE.exe" --remote-debugging-port=9222.

Bot not responding to messages — Make sure Antigravity is running with CDP enabled (remoat open) before starting the bot. The bot will warn you on startup if no CDP ports are responding, but it continues running and auto-connects once Antigravity is available.

CDP connection lost — If you restart Antigravity, the bot auto-reconnects. Sending any message also triggers reconnection.

Verbose logging:

remoat --verbose      # see CDP traffic, detector events, and internal state

1. You send a message in Telegram
2. Remoat authenticates it against your whitelist, resolves the project context, and injects the prompt into Antigravity via CDP
3. A response monitor polls Antigravity's DOM at 2-second intervals, detecting progress phases, approval dialogs, errors, and completion
4. Results stream back to Telegram as formatted messages

The bot never exposes a port, never forwards traffic externally, and never stores your code anywhere but your local disk.

For a deeper dive, see docs/ARCHITECTURE.md. Click the diagram above for an interactive version.

src/
  bin/          CLI entry point (Commander subcommands)
  bot/          grammy bot — event handling, command routing, callback queries
  commands/     Telegram slash command handlers and message parser
  services/     core business logic (CDP, response monitoring, detectors, sessions)
  database/     SQLite repositories (sessions, workspace bindings, templates, schedules)
  middleware/   auth (user ID whitelist) and input sanitization
  ui/           Telegram InlineKeyboard builders
  utils/        config, logging, formatting, i18n, path security, voice/image handling
tests/          test files mirroring src/ structure
docs/           architecture docs, DOM selector reference, diagrams
locales/        i18n translations (en, ja)

Contributions are welcome — whether it's a bug fix, a new feature, documentation improvements, or test coverage.

git clone https://github.com/optimistengineer/Remoat.git
cd Remoat
npm install
cp .env.example .env  # fill in your values
npm run dev           # start with auto-reload
npm test              # run the test suite

See CONTRIBUTING.md for the full guide — code style, commit conventions, PR process, and project architecture.

MIT

Based on LazyGravity, a Discord bot for remotely controlling Antigravity via CDP. Remoat ports the core architecture to Telegram and adds features like Forum Topics, voice input, and structured DOM extraction.