https://github.com/xudong963/conductor_mobile
Continue to code your ideas in your phone with conductor (https://docs.conductor.build/)
https://github.com/xudong963/conductor_mobile
agents coding-agent coding-assistant llm telegram
Last synced: about 2 months ago
JSON representation
Continue to code your ideas in your phone with conductor (https://docs.conductor.build/)
- Host: GitHub
- URL: https://github.com/xudong963/conductor_mobile
- Owner: xudong963
- License: apache-2.0
- Created: 2026-03-28T13:30:50.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-03-31T16:32:16.000Z (2 months ago)
- Last Synced: 2026-04-04T07:17:43.258Z (about 2 months ago)
- Topics: agents, coding-agent, coding-assistant, llm, telegram
- Language: TypeScript
- Homepage: https://xudong963.github.io/bringing-conductor-to-my-phone/
- Size: 374 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Telegram Conductor Bridge
Control the local Conductor instance from Telegram.
This bridge must run on the same Mac that already has Conductor installed and initialized. It reads the local Conductor database and launches the local Codex binary from that machine; it is not a remote bridge for controlling another computer's Conductor instance.
## Conductor <-> Telegram Mapping
- A Conductor repository is the repo you pick in Telegram.
- A Conductor workspace is the branch context you pick in Telegram.
- A Conductor session is the current chat you continue from Telegram.
- In forum-enabled supergroups, one Conductor chat is bound to one dedicated Telegram topic.
- In private chats, or in chats without topics, the conversation stays in the current Telegram chat instead.
The current version supports:
- Browsing repos
- Browsing and switching branches with workspace descriptions
- Browsing and switching chats
- Continuing existing Codex sessions
- Creating a new Conductor chat on the current branch
- Automatically creating a Telegram topic for a new Conductor chat when the current conversation supports topics
- Basic queueing
- Streamed text updates inside dedicated Telegram topics
- A single-message paginated context viewer
- Basic `requestUserInput` and plan feedback flows
- Telegram slash command syncing
## Prerequisites
- The program is started on a Mac where Conductor is already installed and has been opened at least once
- Node.js 22 or newer is installed
- Conductor is already installed and has been used on macOS
- The local Conductor DB exists at:
`~/Library/Application Support/com.conductor.app/conductor.db`
- The local Codex binary exists at:
`~/Library/Application Support/com.conductor.app/bin/codex`
- A Telegram Bot token is available
- If you want to use the bridge in a forum-enabled Telegram supergroup, the bot should be added as an administrator so it can create topics and manage its status/context messages. In private chats, administrator permissions are not required.
## Setup
1. Install dependencies
```bash
npm install
```
2. Copy the environment template and fill it in
```bash
cp .env.example .env
```
3. Set at least these two variables
- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_ALLOWED_CHAT_IDS`
Set `TELEGRAM_ALLOWED_CHAT_IDS` to the Telegram chat IDs that may use the bridge. Separate multiple IDs with commas.
`BRIDGE_DB_PATH` defaults to `.context/bridge.db`. The current version creates this directory on startup, so `.context/` does not need to exist in advance.
## Run
Run the bridge on the same computer where Conductor is installed:
```bash
npm start
```
Development mode:
```bash
npm run dev
```
## Keep It Running on macOS
If you want the bridge to stay available after login, use a user `LaunchAgent` via `launchd`.
`Launchpad` is only an app launcher; it does not keep a CLI process alive.
If you set this up, make sure the process starts from the repo root so it can find `.env` and `.context/`.
If your Node.js installation only exists in an interactive shell setup such as `nvm`, `launchd` may not see it.
## Telegram Commands
- `/start` or `/home`: return to the home screen
- `/repos` or `/workspaces`: choose a repo
- `/branches`: choose a branch
- `/chats` or `/sessions`: choose a chat
- `/status`: open or refresh the current chat's status panel
- `/stop`: interrupt the current turn
- `/queue`: inspect the current chat queue
- `/context [N]`: open a paginated single-message context viewer with older/newer, refresh, and close controls
- `/new`: make the next plain-text message create a new chat on the current branch
- `/new_workspace`: make the next plain-text message create a new workspace in the current repo
- `/help`: show help
On startup the bridge calls Telegram `setMyCommands`, so these slash commands also appear in the mobile command picker.
## Basic Flow
1. Open a private chat with the bot in Telegram, or a forum-enabled supergroup where the bot is present, and send `/start`
2. Tap `Switch Repo`
3. Select a repo
4. Tap `Switch Branch`
5. Select a branch in that repo
6. Tap `Switch Chat`
7. Select an existing chat
8. In topic-enabled supergroups, the bridge opens that chat's dedicated topic and streams follow-up output there
9. Send plain text in the chat or its dedicated topic to continue the current chat
10. For a quick command reference, send `/help` or tap `Help` on the home screen
Create a new chat:
1. Select a repo and branch first
2. Tap `New Chat Here` or send `/new`
3. Your next message will create a new Conductor chat and switch to it automatically
4. If the current Telegram conversation supports topics, the bridge also creates a dedicated topic for that new chat and sends follow-up updates there
5. Existing chats reuse their previously bound topic, so one Conductor chat stays attached to one Telegram topic
Create a new workspace:
1. Select a repo and branch first, or open a repo's branch list
2. Tap `New Workspace` or `New Workspace Here`, or send `/new_workspace`
3. Send the branch name as your next message, for example `berlin` or `feature/demo`
4. The bridge creates a git worktree, writes the Conductor workspace row, and switches you to the new branch
## Output Model
- `/status` creates or refreshes a reusable status panel when you want a compact status view.
- `/context [N]` opens a separate context preview card; paging and refresh actions only update that single message.
- In topic-enabled chats, each Conductor chat streams as a normal assistant message inside its dedicated topic instead of using the status panel.
- The context preview stays scoped to the current topic instead of the whole Telegram chat.
- Both the status panel and the context preview can be closed to keep the Telegram chat tidy.
## Notes
- The current version supports a single user across the allowed Telegram chats
- The current version only supports Codex sessions
- The process will not start if `TELEGRAM_BOT_TOKEN` is not set
- If the token is invalid, the bridge starts but Telegram long polling will keep returning `401`