codexbot

Control AI coding agents from your phone. codexbot connects Telegram or Slack to OpenAI Codex and Anthropic Claude, so you can ask them to read, write, and refactor code — all from a chat message.

Send a prompt from Telegram while you're on the go. The agent works in your codebase and streams every step back to you in real time: what it's thinking, which files it's reading, the commands it runs, and the changes it makes.

Why

Sometimes you want to kick off a coding task, review progress, or give follow-up instructions without sitting at your desk. codexbot turns your favorite chat app into a remote terminal for AI agents that can actually write and run code.

Features

• Two backends — Codex (default) or Claude, switchable at any time
• Real-time streaming — see agent thoughts, tool usage, command output, and file changes as they happen
• Background service — runs as a daemon with start/stop/status management
• Interactive mode — test locally in your terminal before connecting a chat platform
• Chat commands — control the agent directly from Telegram or Slack (/status, /stop, /restart, etc.)
• Telegram command menu — commands appear in Telegram's autocomplete for easy access
• Multi-turn context — the agent remembers your conversation across messages
• Long message handling — responses are split intelligently to fit platform limits

Prerequisites

• Node.js 18 or later
• Codex CLI or Claude CLI installed and signed in (either via OAuth or API key — however you normally authenticate)
• A Telegram bot token or a Slack app with Socket Mode enabled

Getting Started

1. Install

npm install -g codexbot

Or install from source:

git clone https://github.com/dinhquan/codexbot.git
cd codexbot
npm install
npm link

2. Configure

Run the setup wizard:

codexbot onboard

You'll be asked to choose a platform (Telegram or Slack), enter your bot tokens, and set a working directory — the folder where the agent will operate.

Configuration is stored in ~/.codexbot/config.json. Run codexbot onboard again at any time to update it.

3. Start

codexbot start

That's it. The bot launches in the background, connects to your chat platform, and is ready to accept prompts.

Usage

Managing the service

| Command | What it does | |---------|-------------| | codexbot start | Start the bot as a background service (Codex by default) | | codexbot start --claude | Start with Claude instead of Codex | | codexbot start --disable-yolo | Start without auto-accepting agent actions | | codexbot stop | Stop the background service | | codexbot status | Check whether the service is running |

Interactive mode

If you want to test things locally before connecting a chat platform:

codexbot start --interactive

You type messages in the terminal and see the same output that would be sent to Telegram or Slack.

Chat commands

Once the bot is running, send these commands from Telegram or Slack. Both / and $ prefixes work:

| Command | What it does | |---------|-------------| | /status | Show the agent's backend, uptime, and working directory | | /stop | Stop the agent | | /start | Start the agent (add --claude or --codex to switch backends) | | /restart | Restart the agent | | /dir | Show the current working directory | | /dir /path/to/project | Change the working directory (restart to apply) |

Anything else you type is sent directly to the agent as a prompt.

Setting Up Telegram

1. Open Telegram and message @BotFather
2. Create a new bot and copy the token
3. Run codexbot onboard and enter the token
4. Optionally restrict access by entering your Telegram user ID (find it via @userinfobot)
5. Run codexbot start

The bot will register its commands with Telegram automatically, so you'll see them in the autocomplete menu when you type /.

Setting Up Slack

1. Create a new app at api.slack.com/apps
2. Enable Socket Mode and generate an App-Level Token (xapp-...)
3. Add Bot Token Scopes: app_mentions:read, chat:write, im:history, im:read, im:write
4. Subscribe to events: app_mention, message.im
5. Install the app to your workspace and copy the Bot User OAuth Token (xoxb-...)
6. Run codexbot onboard and enter both tokens
7. Run codexbot start

How It Works

When you send a message, codexbot forwards it to the AI agent running in your configured working directory. The agent can read files, edit code, run shell commands, search the web, and more — all autonomously.

Every action the agent takes is streamed back to your chat in real time:

• Text responses — the agent's reasoning and answers
• Tool usage — which files it's reading, editing, or creating
• Command output — shell commands and their results
• File changes — a summary of files added, updated, or deleted

The agent maintains context across messages, so you can have a natural back-and-forth conversation about your code.

Logs and Files

| Path | Purpose | |------|---------| | ~/.codexbot/config.json | Your bot configuration | | ~/.codexbot/codexbot.log | Service logs (useful for debugging) | | ~/.codexbot/codexbot.pid | Process ID of the running service |

License

MIT