Control Claude Code, OpenAI Codex, Google Antigravity (AGY), and xAI Grok via Telegram & Discord across any device.
Break out of the terminal. Asynchronous interaction, remote DevOps, data automation, and coding from anywhere.
Terminal agents like Claude Code, OpenAI Codex, Google Antigravity (AGY), and xAI Grok are far more than mere code generators. With full host permissions, they can analyze documents and images, generate visual assets, search live web news, manage background services, execute Python data scripts, and invoke custom extension tools.
Their main drawback is that they require you to stay at your desk in front of a terminal.
While some tools offer official remote features or web interfaces, they come with practical trade-offs:
- No vendor lock-in, freedom of choice: Official remotes exclusively control their own CLI (Claude remote only controls Claude). PocketAgent provides a unified gateway: whether you prefer Claude Code, OpenAI Codex, Google Antigravity, or Grok, you can operate your local machine through the same familiar Telegram / Discord interface without juggling separate remote tools, and switch anytime if needed.
- Mobile terminal friction vs. native messaging: Official remote setups typically rely on web terminals or standalone interfaces, which frequently suffer from disconnects, session timeouts, and clumsy mobile virtual keyboards. PocketAgent delivers native Telegram and Discord messaging — send a task, lock your screen, and receive asynchronous push notifications upon completion.
- Team collaboration & shared CLI accounts: Official remote tools are strictly single-user. PocketAgent natively supports Telegram and Discord groups, allowing team members to collaborate within the same shared conversation context while pooling the host machine's authenticated CLI accounts and subscriptions without needing separate setups or extra seats.
PocketAgent is a lightweight local gateway daemon that bridges these four CLI agents directly to your chat clients. Whether you are on mobile, a tablet, a secondary laptop, or desktop chat, dispatch tasks directly to your machine without keeping a terminal open or configuring complex SSH tunnels.
Telegram / Discord (Mobile / Desktop / Web / Tablet)
│
▼
PocketAgent Gateway (Local Daemon)
├─ 6-digit Pairing Security Gate
├─ Universal Conversation Ledger
├─ 4-CLI Skill Hub (~/.pocketagent/skills)
└─ Web Dashboard (http://127.0.0.1:18790)
│
┌───────────────┬───────┴───────┬───────────────┐
▼ ▼ ▼ ▼
Claude Code OpenAI Codex Antigravity xAI Grok
(CLI) (CLI) (AGY) (CLI)
│ │ │ │
└───────────────┴───────┬───────┴───────────────┘
▼
Your Local Computer & OS
(Bash/Zsh • Python • Git • Services • File System • Skills)
- Ubiquitous Terminal Access Across Devices: Runs real CLI processes on your machine with native shell, git, and filesystem permissions. Beyond writing code, you can analyze documents and screenshots, generate images, search live news, inspect server logs, and review diffs from any chat client.
- Mid-Conversation Engine Switching (
/engine): Switch between Claude Code, OpenAI Codex, Antigravity, and Grok anytime within the same conversation. PocketAgent automatically extracts conversation history, modified files, and task goals to hand over context without losing track. - 4-CLI Unified Skill Hub: Manage custom extension skills centrally in
~/.pocketagent/skills/. Skills are automatically symlinked across Claude, Codex, AGY, and Grok, eliminating the need to maintain separate tool definitions for each engine. - Multi-Bot, Group Collaboration & Multi-Channel: Run multiple Telegram and Discord bots concurrently on a single gateway across DMs and group channels. Group members share conversation context and host CLI subscriptions; each bot can be configured with its own default engine, model, reasoning effort, and custom system prompt (
SOUL.md). - Local Web Dashboard: Built-in minimalist console at
http://127.0.0.1:18790for live status monitoring, configuration hot reload (Cmd+S), workspace and file inspection, turn-by-turn dialogue logs, and online skill editing. - 100% Local & Secure: Operates strictly on your own hardware without third-party cloud intermediaries. New conversations require approving a 6-digit pairing code in the terminal before gaining access.
| Scenario | Message / Command | Local Machine Action |
|---|---|---|
| Doc & Image Analysis | Send a PDF paper / contract / receipt screenshot: Summarize key findings and calculate total expenses |
CLI uses multimodal capabilities or local scripts to parse content and returns structured highlights |
| Live Web & News Search | Search for today's top tech breakthroughs and compile a morning briefing |
CLI queries live web sources, aggregates coverage, and pushes a concise summary |
| Creative & Image Generation | Ask Codex to generate a futuristic cyberpunk poster and save to desktop |
CLI invokes image generation tools to render the asset and sends the image back to chat |
| Code Changes on the Go | Update auth token expiration to 2h in auth.ts and run vitest |
CLI edits the file, executes the test suite, and outputs the git diff and test status |
| Data & File Organization | List top 10 largest files in ~/Downloads and suggest what to clean |
CLI runs a quick local Shell/Python script to audit disk usage and reports a breakdown |
| Multi-Engine Workflow | Draft architecture with Claude, then send /engine to switch to AGY |
Automatically hands off context to Antigravity for implementation against a large codebase |
- Node.js >= 22
- At least one supported CLI installed:
- Claude Code (
claude) - Google Antigravity (
agy) - OpenAI Codex (
codex) - xAI Grok CLI (
grok, logged in viagrok login)
- Claude Code (
- A Telegram Bot Token from @BotFather and/or a Discord Bot Token from Discord Developer Portal (enable MESSAGE CONTENT INTENT under the Bot tab).
git clone https://github.com/happy-shine/pocketagent.git
cd pocketagent
npm install
npm run build
npm link # Registers global `pa` and `pocketagent` commandspa doctorChecks your Node.js runtime and detects which CLI engines are installed on your machine.
Edit ~/.pocketagent/config.yaml (created automatically on first run, or edit in the Web Dashboard):
defaultEngine: "claude" # claude | codex | agy | grok
bots:
- name: "my-telegram-bot"
channel: telegram # telegram | discord
token: "123456:ABC-DEF..." # Telegram Bot Token
dmPolicy: pairing # pairing | allowlist | open | disabled
groupPolicy: pairing
# allowFrom:
# - "1465542100"
# Optional Discord bot:
# - name: "my-discord-bot"
# channel: discord
# token: "MTE3..."# Start background daemon (default):
pa start
# Check status:
pa status
# Open Web Dashboard in browser:
open http://127.0.0.1:18790
# Restart or stop:
pa restart
pa stop
# View live background logs:
tail -f ~/.pocketagent/logs/gateway.log
# Run in foreground for debugging:
pa start -fWhen you first message the bot on Telegram or Discord, it will reply with a 6-digit pairing code (e.g. 123456).
Approve it in your terminal (or via the Web Dashboard):
pa pairing approve 123456| Command | Description |
|---|---|
/engine |
Open interactive menu to switch active CLI engine with context handover |
/model |
Select available models for the current engine |
/effort |
Adjust reasoning effort level (low, medium, high, max) |
/status |
View active engine, model, current workspace path, and turn count |
/new |
Start a new conversation in a fresh workspace |
/sessions |
List active sessions with inline buttons to switch or inspect |
/btw <question> |
Ask a quick side question without interrupting active tasks |
/stop |
Abort the current running CLI turn |
/cron |
List scheduled tasks with Run / Pause / Resume buttons; /cron rm <n> deletes one |
/help |
Display command help |
Ask the bot in plain words, e.g. "every weekday at 9am send me a digest of the latest AI news" or "remind me tomorrow at 3pm to call Alice". The CLI creates the task through the local gateway API and confirms the schedule. When it is due, PocketAgent runs the prompt unattended and posts the result to the chat.
- Isolated runs: each run starts with a fresh context, so it doesn't touch your conversation. Every task has its own persistent working directory where it can keep state between runs.
- Quiet monitoring: if a run replies
[SILENT], nothing is posted. Useful for prompts like "tell me only when X changes". - Manual management:
/cron add 0 8 * * * | <prompt>or/cron add 2026-10-04 09:00 | <prompt>;/cron run|pause|resume|rm <n>. - Safety: in group chats, only paired / allowlisted users can manage tasks. Tasks are paused after 3 consecutive failures. Runs missed while the machine was asleep are caught up at most once (within
catchUpGraceMs). - Tasks are stored in
~/.pocketagent/cron/. Optional tuning goes in ascheduler:block inconfig.yaml(seeconfig.example.yaml).
| Command | Description |
|---|---|
pa start [-f] |
Start PocketAgent daemon (-f for foreground mode) |
pa status |
Check daemon status, PID, and port |
pa restart |
Restart the background daemon |
pa stop |
Stop the daemon |
pa doctor |
Health check for environment and installed CLI engines |
pa pairing list |
List pending pairing authorization requests |
pa pairing approve <code> |
Approve a pairing code |
Because different CLIs store conversation state in incompatible formats, PocketAgent coordinates transitions using three components:
- Universal Ledger: Logs all prompts, assistant outputs, tool calls, and modified file paths in a unified local ledger.
- Handover Primer: When switching to another engine, the gateway summarizes past context, modified files, and remaining goals into a structured primer prompt for the incoming engine.
- Shared Working Directory: All engines work directly in the same local directory on disk. File changes, git commits, and artifacts produced by one engine are immediately available to the others.
MIT © happy-shine