aipager 0.3.4

Telegram remote-control daemon for Claude Code CLI sessions running in dtach

aipager

Telegram remote-control for Claude Code CLI sessions. Run Claude inside a detached terminal (dtach), drive it from your phone — read responses, send prompts, approve permission requests, switch sessions — without an SSH session staying open.

Install

Linux or macOS, any architecture. dtach is installed automatically via the dtach-bin dependency — no separate system package needed.

One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/dev-aly3n/aipager/main/install.sh | sh

This auto-detects uv / pipx / brew and uses whichever is already on your system. If none is present, it bootstraps uv (Astral's Python tool manager) and installs through it.

uv

uv tool install aipager     # if uv is already installed

— or to install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install aipager

uv bundles its own Python interpreter, so this works on any macOS / Linux version regardless of what system Python is doing.

pipx

pipx install aipager

Homebrew tap (macOS, Linuxbrew)

brew install dev-aly3n/tap/aipager

Pulls dtach from Homebrew's standard formula and installs aipager into a Homebrew-managed Python venv.

Heads-up: if you're on macOS Tahoe (26.x), the brew path may fail at pip install time with a pyexpat _XML_SetAllocTrackerActivationThreshold symbol error — that's a known Homebrew Python bottle issue unrelated to aipager. Use the uv path instead (it's not affected) until Homebrew rebuilds the bottles for Tahoe.

Configure

aipager config

Interactive wizard — asks for your Telegram bot token (from @BotFather) and chat ID, validates them, then patches ~/.claude/settings.json to wire the necessary hooks automatically. You never edit any file by hand.

Run

aipager start

The daemon stays in the foreground. Launch a Claude session in another terminal:

aipager session dev

This creates (or reattaches to) a dtach session named claude-dev running Claude Code. The aipager daemon discovers it within seconds and Telegram starts mirroring it. Re-run the same command to reattach later; detach with Ctrl-\.

If the dtach session was killed (machine reboot, etc.) but you want to pick up the Claude conversation from disk, add --resume:

aipager session dev --resume    # resume the last claude conversation in this cwd

You can also pass --resume <session-id> (or any other claude flag) through as trailing args:

aipager session dev -- --resume abc1234

Run as a service (survives logout)

aipager service install

On Linux this writes a systemd-user unit at ~/.config/systemd/user/aipager.service and starts it. On macOS it writes a launchd plist at ~/Library/LaunchAgents/com.aipager.daemon.plist and bootstraps it. Subcommands: start, stop, status, logs, uninstall.

What it does

• Mirrors Claude Code session state to Telegram: busy/idle, tool calls, context %, cost, line counts
• Lets you reply to messages to inject prompts back into the session
• Surfaces permission prompts and AskUserQuestion dialogs as Telegram inline keyboards
• Notifies on context warnings, compaction, session end, and stalls
• Supports multiple concurrent sessions with one bot
• Optional read-only observer bots

Developing locally

git clone <repo-url> aipager && cd aipager
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
pytest -q

When iterating on code changes you'll generally want to also install dtach-bin from a local checkout — or pip install dtach-bin — so the runtime can find dtach on PATH.

Release process is in CONTRIBUTING.md.

License

MIT — see LICENSE.