Pocket Operator

Leave your desk, keep your Codex session alive, and reply from your phone.

Pocket Operator is now the product name and the primary repository name. The legacy Python import path telegram_codex_controller remains temporarily supported for compatibility, while the forward-looking module path is pocket_operator.

It turns Telegram into a practical mobile console for Codex and other terminal-based agents running on your own machine. The core use case is simple:

you start a Codex session on your computer, step away from your desk, and still want to monitor it, answer it, continue it, and recover it from your phone.

This is not a raw stdout mirror. It gives you:

one editable session card instead of endless log spam
direct reply routing back into the exact running session
INDEX + ALERTS + one topic per session when you need a full mobile console

Dogfooding proof: the project itself was developed entirely over Telegram from a phone.

Start here:

Screenshots:

The Killer Use Case

Most remote-development tools assume you want a full remote shell. That is not the problem this project solves.

The problem is narrower and more common:

you already have a valuable local Codex session running
you leave your desk
the session keeps working, blocks on human input, or needs a follow-up instruction
you want to handle that from your phone without losing the original session context

That is the product:

keep the existing session
see the current state clearly
send the next instruction from Telegram
continue the same line of work without reopening everything

Why Not SSH?

Option	Works well for	Friction on a phone	Why Pocket Operator exists
SSH	full terminal control	too much raw output, weak prioritization, awkward on mobile	Pocket Operator is optimized for session status and intervention, not full shell work
Remote desktop	visual access to the exact desktop	clumsy on mobile, too much UI overhead	Pocket Operator gives you a purpose-built mobile control surface
Pocket Operator	continuing a running Codex session	narrower scope than a full shell by design	that narrower scope is what makes it fast and usable on a phone

What It Also Supports

The main use case is existing-session takeover, but the project also supports:

New long-running jobs Start named tmux tasks from Telegram and keep them alive independently of your current shell.
SDK-backed sessions Start and continue Codex or Claude SDK sessions through the sidecar runner.
Multi-session operations Run a Telegram supergroup as a compact multi-agent control console with one topic per session.

Why It Matters

If you already run Codex, Claude, research scripts, or builds locally, the hardest part usually starts after launch:

you lose visibility as soon as you leave the machine
multiple sessions become hard to distinguish on a phone
a task pauses for input and you do not notice in time
the fallback is reading noisy terminal output with no hierarchy

This project turns that into a cleaner mobile workflow:

Clear status: one session card per workflow
Clear priority: INDEX for overview, ALERTS for intervention
Low noise: cards are edited in place
Direct intervention: respond from Telegram without recreating the session
Preserved context: keep the exact local session that is already doing useful work

Good Fit Scenarios

you run multiple Codex, Claude, or research-agent sessions at the same time
you have long jobs that may require login, approval, or a short human reply
you already have valuable local terminal state and do not want to migrate all of it
you want overnight or weekend monitoring from your phone
you want to package agent operations as a usable product, not a pile of personal scripts

Key Capabilities

Multi-Session Agent Console

track many sessions in parallel
support three session sources: tmux, existing Terminal.app windows, and SDK sessions
keep separate status, summary, log access, and reply routing per session

Real-Time State Lights

🟢 running: active and healthy
🟡 waiting: waiting for human input, login, approval, or confirmation
🔴 error: failed or detected as abnormal
✅ done: completed
⚫ stopped: intentionally stopped or no longer present
⚪ idle: ready but inactive

Mobile-First Information Architecture

one editable INDEX card for the whole console
one ALERTS stream or topic for waiting, error, done, and stuck states
one topic per session for detailed inspection and direct interaction
coalesced card updates to reduce Telegram noise
full logs exported as documents when needed

Remote Control

/codex to start new Codex CLI work
/run to launch long-running tmux tasks
/agent_* to manage SDK-backed Codex or Claude sessions
/mirror to attach existing Terminal.app Codex windows
/focus to bring the corresponding Terminal tab to the foreground
/send, reply-to-card, or topic message routing to push input back into the right session

Clear Session Identity

persistent aliases for ttysNNN sessions, for example session-alpha
topic titles that follow current state, such as 🟢 session-alpha or 🔴 mobile-layout
INDEX ordering that highlights error and waiting states first
compact summaries optimized for small screens

Security and Control

restrict access with AUTHORIZED_USER_IDS
keep /shell disabled by default
export logs without exposing a full remote shell workflow
suitable for private developer machines or controlled internal environments

Recommended Telegram Workspace

The best product shape is:

one Telegram supergroup
Topics / Forum enabled
one INDEX topic
one ALERTS topic
one topic per session, agent, or tracked window

A Telegram supergroup is not a separate app. It is Telegram’s larger group type. When Topics are enabled, the group behaves like a multi-page control console.

Architecture

Phone (Telegram)
      │
      ▼
Telegram Bot
      │
      ▼
Command Router
      │
      ├── Telegram console manager
      │     ├── editable session cards
      │     ├── INDEX summary
      │     ├── ALERTS topic/feed
      │     └── optional forum topics
      ├── SDK assistant runner
      ├── Terminal mirror watcher
      ├── Codex CLI task launcher
      ├── Optional shell runner
      └── tmux session manager
              │
              ▼
         tmux sessions

Commands and Interaction

The sections above describe the product. This section covers the operating surface you use in Telegram.

Common commands

/start — show help
/help — show help
/ping — health check
/forum_on — enable forum/topic mode for the current console chat
/forum_off — disable forum/topic mode for the current console chat
/forum_bootstrap — create INDEX, ALERTS, and topics for current sessions
/index_here — bind the current chat/topic as INDEX
/alerts_here — bind the current chat/topic as ALERTS
/open <session> — bind a tracked session to the current topic and refresh its status card
/focus <mirror-session> — bring an existing Terminal Codex tab to the front
/topic_create <session> [topic name] — create and bind a forum topic for a session
/send <session> <text> — send text directly to a mirror/tmux/agent session
/find <session> <pattern> — search recent logs/transcript/history
/recent_errors [limit] — show recent error/waiting sessions
/sessions — list tracked sessions
/run <name> <command...> — start a named task in tmux
/codex <name> <prompt...> — start a Codex task using the configured Codex command template
/logs <session> — export full tmux logs, mirror history, or assistant transcripts, usually as a .log document
/tail <session> [lines] — return a short on-demand summary instead of starting a stream
/stop <name> — stop a session
/shell <command...> — run a shell command when enabled
/agents — list tracked SDK-backed Codex or Claude sessions
/agent_new <assistant> <name> [cwd] — create a named SDK session
/agent <name> <prompt...> — continue a named SDK session
/agent_log <name> — show recent transcript for a named SDK session
/agent_cwd <name> <cwd> — change SDK session working directory and clear resume state
/agent_stop <name> — delete a tracked SDK session
/mirror [status|on|off|snapshot [tty-or-alias]|alias <tty-or-alias> <alias>|unalias <tty-or-alias>|aliases] — manage Terminal mirroring
/mirrors — alias for /mirror
Reply to a status card or routed event, or just send a plain text message inside that session topic — automatically send text back to the mirrored Terminal tab, tmux session, or SDK assistant session

Status cards now include inline keyboard actions for the most common flows:

Continue
Refresh
Recent
Focus for mirrored Terminal sessions
Stop for tmux and SDK assistant sessions

Examples:

/run research codex exec "Analyze parser edge cases"
/codex ontology Build an ontology plan for repository structure
/agent_new codex triage ./workspace
/agent triage "Summarize the repo structure"
/agent_log triage
/forum_on
/forum_bootstrap
/index_here
/alerts_here
/open triage
/topic_create triage
/send session-alpha Reply with the single word ok.
/focus session-alpha
/mirror alias ttys003 ocna-vpn
/mirror snapshot ocna-vpn
/open ocna-vpn
/find ocna-vpn yubikey
/recent_errors
/mirror snapshot
/mirrors
/logs ontology
/tail ontology
/stop ontology
/sessions

Recommended mobile flow:

Watch the editable INDEX message for overall state.
Use the INDEX buttons to refresh the overview, surface recent errors, or open a specific session.
Watch ALERTS for errors, waiting-for-human-input, completion, and stuck sessions.
Use the inline buttons on a session card for continue, refresh, recent output, focus, and stop.
Reply directly to that session card, or type inside that session topic, when you need to send text back into the session.

The bot also registers high-frequency commands through setMyCommands, so they appear directly in Telegram’s command picker.

Mirror sessions keep the real ttysNNN routing key internally, but you can attach a persistent alias like ocna-vpn so status cards, topics, and alerts are easier to recognize.

Releases

This repository supports two release paths:

Push a version tag from your machine:

git tag v0.1.0
git push origin v0.1.0

Run the Release workflow manually from the GitHub Actions UI and provide:
- a tag such as v0.1.0
- an optional target ref such as main or a commit SHA
- an optional custom title
- optional release notes

If notes are left empty, GitHub release notes are generated automatically.

Requirements

Python 3.11+
Node.js 20+
tmux
a Telegram bot token created through @BotFather
your Telegram numeric user id for authorization
Codex CLI installed locally if you want /codex
macOS Terminal.app if you want to mirror existing local windows
a Telegram supergroup with Topics enabled if you want the recommended one-topic-per-session layout

Quick Deployment

Choose one of these paths:

3-minute fast demo if you want to prove the core value quickly
15-minute full console if you want the complete INDEX + ALERTS + topics workflow

3-Minute Fast Demo

If you want the shortest possible path to the core experience, do this:

Run:

./scripts/install.sh
./scripts/doctor.sh

Edit .env and set:
- TELEGRAM_BOT_TOKEN
- AUTHORIZED_USER_IDS
Start the controller:

./scripts/run_service.sh

In Terminal.app, run the deterministic demo session:

./scripts/demo_phone_takeover.sh

Open Telegram, talk to the bot, and route a reply back into that same terminal session.

This is the fastest way to prove the core promise:

the same local session keeps going after you leave the desk.

15-Minute Full Console

If you want the full product shape instead of a quick trial:

create a private Telegram supergroup
enable Topics / Forum
add the bot
run /forum_on
run /forum_bootstrap
use INDEX, ALERTS, and one topic per session

This is the mode to use when you want:

multiple concurrent sessions
better mobile information hierarchy
ongoing operations, not just a one-off demo

These steps are written for first-time setup with the recommended product shape:

the controller runs on your computer
Telegram on your phone is the operator interface
one supergroup hosts the full console
INDEX + ALERTS + one topic per session is the default layout

Step 0: Decide on the deployment shape

The recommended shape is not a one-on-one bot chat. It is:

one Telegram supergroup
Topics / Forum enabled
the bot added to that supergroup
INDEX, ALERTS, and session topics living inside the group

If you only want a fast local trial, you can start with a direct bot chat. For long-term use, multi-session visibility, and cleaner mobile navigation, supergroup + topics is the better shape.

Step 1: Create the Telegram bot from your phone

Open @BotFather in Telegram
Send /newbot
Follow the prompts for bot name and username
Save the returned bot token

You will place this token in .env as TELEGRAM_BOT_TOKEN.

Step 2: Decide whether to disable group privacy

If you want plain text typed directly inside a session topic to be routed back to that session, disable the bot’s group privacy mode:

Open @BotFather
Send /setprivacy
Select your bot
Choose Disable

Behavior difference:

Privacy disabled: plain text sent inside a session topic can route back to the session
Privacy enabled: /send and reply-to-card still work, but plain topic text may not reach the bot

Step 3: Create the Telegram supergroup

Create a new Telegram group
Convert or configure it as a supergroup
Enable Topics / Forum
Add your bot to the group
Prefer granting the bot these admin capabilities:
- Manage Topics
- Pin Messages
- Delete Messages

Without topic-management permissions, /forum_bootstrap, automatic topic creation, and message maintenance features may fail.

Step 4: Get your Telegram user id

Open @userinfobot and record your numeric Telegram user id.

You will place it in .env as AUTHORIZED_USER_IDS.

Step 5: Install dependencies on the computer

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
(cd sidecar && npm install)

Install tmux:

macOS:

brew install tmux

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y tmux

Step 6: Configure `.env`

cp .env.example .env

Minimum working configuration:

TELEGRAM_BOT_TOKEN=your_bot_token_here
AUTHORIZED_USER_IDS=123456789
MIRROR_CHAT_IDS=123456789

Recommended product-style configuration:

TELEGRAM_BOT_TOKEN=your_bot_token_here
AUTHORIZED_USER_IDS=123456789
MIRROR_CHAT_IDS=123456789

MIRROR_ENABLED=true
CODEX_COMMAND_TEMPLATE=codex exec "{prompt}"

CONSOLE_FORUM_ENABLED=true
CONSOLE_AUTO_CREATE_TOPICS=true
CONSOLE_SEND_LOG_DOCUMENTS=true
CONSOLE_TOPIC_BUMP_ENABLED=true
CONSOLE_STATUS_SUMMARY_LINES=15
CONSOLE_RUNNING_UPDATE_MIN_INTERVAL_SECONDS=12
CONSOLE_GLOBAL_WRITE_SPACING_SECONDS=2

Deployment notes:

CONSOLE_CHAT_ID can be left empty for the first boot After startup, run /forum_on in the target supergroup and the controller will remember that chat as the main console
CONSOLE_INDEX_TOPIC_ID and CONSOLE_ALERTS_TOPIC_ID can also be left empty They can be created automatically during bootstrap or bound later with /index_here and /alerts_here
If you are the only operator, MIRROR_CHAT_IDS usually only needs your own user id

Fast path

If you want the shortest setup path:

./scripts/install.sh
./scripts/doctor.sh
./scripts/bootstrap.sh

Step 7: Start the service

Run in the foreground:

PYTHONPATH=src python -m pocket_operator.main

Or use the helper script:

./scripts/run.sh

If dependencies are already installed, the lightweight long-running entrypoint is:

./scripts/run_service.sh

For macOS background execution, see docs/launchd.plist.example.

Step 8: Complete first-time mobile binding

After the service is running, use this order:

Open a direct chat with the bot and send /start This confirms the bot is online and your AUTHORIZED_USER_IDS setting is correct
Enter your supergroup
Send /forum_on
Send /forum_bootstrap

After that, the recommended result is:

one INDEX topic
one ALERTS topic
one topic per currently known session

If you want to bind things manually:

enter the INDEX topic and run /index_here
enter the ALERTS topic and run /alerts_here
enter any session topic and run /open <session>

Step 9: Run a real mobile smoke test

Recommended smoke test:

Make sure you already have a Codex window on the computer, or run:

/codex demo Explain this repo

In the supergroup, run:

/forum_bootstrap

Confirm that your phone shows:
- INDEX
- ALERTS
- a demo topic, or a topic for the mirrored session
Enter that session topic and try both input paths:
- reply to the status card
- send a plain text message directly in the topic
If the target terminal receives the input, reply routing is working

If privacy mode is still enabled, the plain topic message in step 4 may not work. That is a Telegram limitation, not a controller bug.

Step 10: Start with these commands

After deployment, these are usually the most useful commands:

/forum_on
/forum_bootstrap
/open <session>
/mirror on
/mirror alias <tty> <alias>
/send <session> <text>
/tail <session>
/logs <session>
/recent_errors

For daily use, think of the Telegram workspace like this:

INDEX: control overview
ALERTS: action queue for waiting, errors, completions, and stuck work
session topic: detailed status, logs, and direct reply path for one session

Configuration

All configuration is done via environment variables.

Variable	Required	Default	Description
`TELEGRAM_BOT_TOKEN`	yes	-	Telegram bot token
`AUTHORIZED_USER_IDS`	yes	-	Comma-separated Telegram user IDs allowed to use the bot
`MIRROR_CHAT_IDS`	no	`AUTHORIZED_USER_IDS`	Telegram chat IDs that receive automatic Terminal mirror events
`TMUX_BIN`	no	`tmux`	Path to tmux binary
`LOG_LINES_DEFAULT`	no	`80`	Default log lines returned by `/logs`
`POLL_INTERVAL_SECONDS`	no	`3`	Background poll interval for log streaming
`ALLOW_SHELL`	no	`false`	Enable `/shell`
`SHELL_TIMEOUT_SECONDS`	no	`20`	Timeout for `/shell`
`CODEX_COMMAND_TEMPLATE`	no	`codex exec "{prompt}"`	Command template used by `/codex`
`MAX_MESSAGE_CHARS`	no	`3500`	Chunk size for Telegram messages
`SESSION_NAME_PREFIX`	no	`tgc_`	Prefix added to tmux session names
`MIRROR_ENABLED`	no	`true`	Enable automatic mirroring of existing Terminal Codex tabs
`MIRROR_POLL_INTERVAL_SECONDS`	no	`3`	Poll interval for Terminal snapshot diffing
`MIRROR_INITIAL_LINES`	no	`24`	Initial line count sent when a new Terminal Codex tab is attached
`NODE_BIN`	no	`node`	Node executable used for the SDK sidecar
`ASSISTANT_STATE_PATH`	no	`./.state/assistant_sessions.json`	JSON file storing SDK session metadata and resume IDs
`ASSISTANT_SIDECAR_SCRIPT`	no	`./sidecar/runner.mjs`	Node entrypoint used for SDK-backed Codex or Claude sessions
`CONSOLE_CHAT_ID`	no	first chat in `MIRROR_CHAT_IDS`	Main chat or supergroup where the console lives
`CONSOLE_FORUM_ENABLED`	no	`false`	Enable one-topic-per-session delivery inside a forum-enabled supergroup
`CONSOLE_AUTO_CREATE_TOPICS`	no	`true`	Auto-create INDEX, ALERTS, and session topics when forum mode is enabled
`CONSOLE_INDEX_TOPIC_ID`	no	auto	Existing topic id to use for INDEX
`CONSOLE_ALERTS_TOPIC_ID`	no	auto	Existing topic id to use for ALERTS
`CONSOLE_STATUS_SUMMARY_LINES`	no	`15`	Number of important lines to keep in each status card summary
`CONSOLE_STATUS_UPDATE_MIN_INTERVAL_SECONDS`	no	`5`	Minimum interval between status-card edits for the same session
`CONSOLE_RUNNING_UPDATE_MIN_INTERVAL_SECONDS`	no	`12`	Minimum interval for sessions that are simply running normally
`CONSOLE_GLOBAL_WRITE_SPACING_SECONDS`	no	`2`	Global spacing between automatic Telegram card/index writes
`CONSOLE_STUCK_MINUTES`	no	`15`	How long a running session can go without updates before ALERTS marks it stuck
`CONSOLE_COMPLETED_RETENTION_MINUTES`	no	`60`	How long completed/stopped sessions stay visible in INDEX before dropping out
`CONSOLE_TOPIC_BUMP_ENABLED`	no	`true`	Periodically bump active session topics so they stay near the top of the forum list
`CONSOLE_TOPIC_BUMP_MINUTES`	no	`10`	Minimum interval between low-noise active-topic bumps
`CONSOLE_SEND_LOG_DOCUMENTS`	no	`true`	Send full logs/transcripts as `.log` documents instead of large text blobs
`CONSOLE_PIN_STATUS_MESSAGES`	no	`false`	Pin each session status card when created

Security notes

For the full security model, see SECURITY.md.

This bot can control your development machine. Use it carefully.

Recommended safeguards:

Only approve your own Telegram user ID.
Keep /shell disabled unless you truly need it.
Run the bot with a low-privilege user.
Avoid putting secrets directly into commands.
Prefer /codex or /run with known-safe commands.
Keep the machine protected behind your usual OS security controls.
Remember that /agent_* can invoke Codex or Claude with tool access in your local workspace.
If you move the console into a supergroup, keep forum topics restricted to trusted users only.

How `/codex` works

The /codex command builds a shell command from CODEX_COMMAND_TEMPLATE.

Template example:

CODEX_COMMAND_TEMPLATE=codex exec "{prompt}"

Then:

/codex research Investigate SOAP validation edge cases

becomes:

codex exec "Investigate SOAP validation edge cases"

If your local Codex workflow uses a different command, just change the template.

Examples:

CODEX_COMMAND_TEMPLATE=codex exec --profile prod "{prompt}"
CODEX_COMMAND_TEMPLATE=codex run research_agent --input "{prompt}"

Service Mode and Operations

For day-to-day use, the controller should run as a background service rather than inside a temporary interactive shell.

macOS LaunchAgent behavior

On macOS, the recommended mode is a user launchd LaunchAgent.

That gives you:

automatic start after login through RunAtLoad
automatic restart through KeepAlive
access to the logged-in GUI session, which is required for existing Terminal.app mirroring

To keep the Telegram console available after a machine restart, all of these conditions must hold:

the Mac is powered on
the macOS user session is logged in
the machine has network access
the machine is not asleep

Because existing Terminal.app mirroring depends on the GUI session, a LaunchAgent is usually the correct mode for this project. A LaunchDaemon can start earlier, but it does not have the same access to logged-in Terminal windows.

Install or reload the LaunchAgent

Sample files:

macOS: docs/launchd.plist.example
Linux: docs/systemd.service.example

Typical macOS flow:

cp docs/launchd.plist.example ~/Library/LaunchAgents/com.example.pocket-operator.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.pocket-operator.plist
launchctl kickstart -k gui/$(id -u)/com.example.pocket-operator

Service helper scripts

This repository now includes two operational helper scripts:

./scripts/service_status.sh
./scripts/service_restart.sh

The sample LaunchAgent label used in this documentation is com.example.pocket-operator.

If you use a different LaunchAgent label or plist path, override them with:

TGC_LAUNCHD_LABEL
TGC_LAUNCHD_PLIST
TGC_LOG_PATH

Examples:

TGC_LAUNCHD_LABEL=com.example.pocket-operator ./scripts/service_status.sh
TGC_LAUNCHD_PLIST=$HOME/Library/LaunchAgents/com.example.pocket-operator.plist ./scripts/service_restart.sh

Daily operations

Common commands:

./scripts/service_status.sh
./scripts/service_restart.sh
tail -f logs/stderr.log

Optional shell alias

If you want short shell commands for everyday service operations, add aliases like these:

alias tgService="/path/to/repo/scripts/service_restart.sh"
alias tgStatus="/path/to/repo/scripts/service_status.sh"
alias tgLogs="tail -f /path/to/repo/logs/stderr.log"

tmux and mirroring notes

The bot process itself does not need to run inside tmux, though spawned tasks can.
Existing terminal mirroring is macOS-specific because it reads Terminal.app tab contents through AppleScript.
Sessions running in another terminal emulator are not mirrored automatically.

Forum topics are optional but recommended

If CONSOLE_FORUM_ENABLED=true and CONSOLE_CHAT_ID points at a forum-enabled Telegram supergroup, the controller can keep:

one editable INDEX card in an INDEX topic
one ALERTS stream in an ALERTS topic
one status card per session in its own topic
topic titles that follow session state, e.g. 🔴 session-alpha

A practical setup flow is:

In the target supergroup, run /forum_on.
Run /forum_bootstrap once to create INDEX, ALERTS, and topics for currently active sessions.
Run /index_here inside the INDEX topic if you want to rebind it manually later.
Run /alerts_here inside the ALERTS topic if you want to rebind it manually later.
Run /topic_create session-alpha or /topic_create research-alpha to create additional per-session topics.
Use /open <session> inside a topic if you want to rebind or refresh that session card there.
Inside a session topic, you can either reply to the status card or just send plain text in that topic to route input back to the bound session.

Without forum mode, the same architecture still works in a single chat, but session separation is weaker.

Project structure

pocket-operator/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── .env.example
├── README.md
├── SECURITY.md
├── requirements.txt
├── sidecar/
│   ├── package.json
│   └── runner.mjs
├── docs/
│   ├── demo-script-30s.md
│   ├── launchd.plist.example
│   ├── systemd.service.example
│   ├── use-case-mobile-research-monitor.md
│   ├── use-case-multi-agent-operations-console.md
│   └── use-case-overnight-build-watcher.md
├── scripts/
│   ├── bootstrap.sh
│   ├── demo_phone_takeover.sh
│   ├── doctor.sh
│   ├── install.sh
│   ├── service_restart.sh
│   ├── service_status.sh
│   ├── run.sh
│   └── run_service.sh
└── src/
    ├── pocket_operator/
    └── telegram_codex_controller/
        ├── assistant_sessions.py
        ├── __init__.py
        ├── bot.py
        ├── console.py
        ├── config.py
        ├── main.py
        ├── security.py
        ├── session_manager.py
        ├── terminal_mirror.py
        └── utils.py

Troubleshooting

Bot starts but `/codex` fails

Check:

Codex CLI is installed on the same machine
The command works directly in your shell
CODEX_COMMAND_TEMPLATE matches your real Codex CLI syntax

`/agent_*` fails immediately

Check:

sidecar/node_modules exists and npm install completed
node is available to the launch environment
Your local Codex or Claude authentication is already working outside Telegram

Terminal mirroring shows nothing

Check:

The Codex session is running inside macOS Terminal.app
The bot process has permission to automate Terminal.app
MIRROR_ENABLED=true
The Telegram chat ID is present in MIRROR_CHAT_IDS

`tmux not found`

Install tmux and ensure TMUX_BIN points to it if needed.

No response to commands

Check:

Your Telegram user ID is listed in AUTHORIZED_USER_IDS
Your bot token is correct
The bot process is running

Long logs are cut off

Session cards keep only the most recent important lines. Use /logs, /agent_log, or /find when you need deeper detail. By default, full logs are sent as .log documents to avoid chat spam.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github		.github
docs		docs
scripts		scripts
sidecar		sidecar
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Pocket Operator

The Killer Use Case

Why Not SSH?

What It Also Supports

Why It Matters

Good Fit Scenarios

Key Capabilities

Multi-Session Agent Console

Real-Time State Lights

Mobile-First Information Architecture

Remote Control

Clear Session Identity

Security and Control

Recommended Telegram Workspace

Architecture

Commands and Interaction

Common commands

Releases

Requirements

Quick Deployment

3-Minute Fast Demo

15-Minute Full Console

Step 0: Decide on the deployment shape

Step 1: Create the Telegram bot from your phone

Step 2: Decide whether to disable group privacy

Step 3: Create the Telegram supergroup

Step 4: Get your Telegram user id

Step 5: Install dependencies on the computer

Step 6: Configure .env

Fast path

Step 7: Start the service

Step 8: Complete first-time mobile binding

Step 9: Run a real mobile smoke test

Step 10: Start with these commands

Configuration

Security notes

How /codex works

Service Mode and Operations

macOS LaunchAgent behavior

Install or reload the LaunchAgent

Service helper scripts

Daily operations

Optional shell alias

tmux and mirroring notes

Forum topics are optional but recommended

Project structure

Troubleshooting

Bot starts but /codex fails

/agent_* fails immediately

Terminal mirroring shows nothing

tmux not found

No response to commands

Long logs are cut off

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Step 6: Configure `.env`

How `/codex` works

Bot starts but `/codex` fails

`/agent_*` fails immediately

`tmux not found`

Packages