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.

aipager.run · Docs · Changelog · Issues

Install

Have a coding agent (Claude Code, or any agent with a shell)? Create a
bot with @BotFather, press Start in it, and
make sure you are logged in to Claude Code on this machine. Save the
bot token to a file your agent never has to read (paste the token,
press Enter, then Ctrl-D):

mkdir -p ~/.config/aipager
rm -f ~/.config/aipager/bot-token
(umask 077 && cat > ~/.config/aipager/bot-token)
chmod 600 ~/.config/aipager/bot-token

Then give your agent this prompt:

Install aipager for me by following https://aipager.run/agent.md. My Telegram bot token is in ~/.config/aipager/bot-token and my Telegram user id is <your id>.

If you do not know your Telegram user id, say so instead; the agent
can find it.

The guide it follows, including how to hand over the token safely, is
docs/install-with-an-agent.md. To
install it yourself, read on.

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 (recommended on macOS)

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 — it
sidesteps the Homebrew-Python-vs-Xcode breakage described under the
Homebrew section below.

pipx

pipx install aipager

Homebrew tap (macOS, Linuxbrew)

Note: uv tool install aipager is the recommended path on
macOS. The brew formula works when Homebrew's [email protected] bottle
and your Xcode / Command Line Tools are in sync, but they
periodically drift apart — most recently on macOS Tahoe
(26.x), where install fails with a
pyexpat _XML_SetAllocTrackerActivationThreshold symbol error
(upstream issue).
Updating Xcode + Command Line Tools usually fixes it, but it's
easier to just use uv.

brew install dev-aly3n/tap/aipager

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

Docker

Self-contained image with python, node, claude and dtach baked in
— good for VPS / NAS / Pi deployments where you don't want a Python
or Node toolchain on the host. Multi-arch (amd64, arm64).

# 1. Run the setup wizard once (interactive)
docker run --rm -it \
  -v "$HOME/.claude:/home/aipager/.claude" \
  -v aipager-config:/home/aipager/.config/aipager \
  ghcr.io/dev-aly3n/aipager:latest config

# 2. Start the daemon (background, auto-restart)
docker run -d --restart=unless-stopped --name aipager \
  -v "$HOME/.claude:/home/aipager/.claude" \
  -v aipager-config:/home/aipager/.config/aipager \
  -v "$PWD:/workspace" \
  ghcr.io/dev-aly3n/aipager:latest

Mount the directories you want claude to edit under /workspace. The
~/.claude mount carries over your claude credentials and
conversation history — run claude on the host once to authenticate,
or docker exec -it aipager claude for an interactive login in the
container.

Tags: latest, 0.7, 0.7.20 (semver track + minor track).

Nix flake

nix run github:dev-aly3n/aipager -- --version
nix profile install github:dev-aly3n/aipager

Builds aipager from source against pinned nixpkgs deps. dtach is
provided by Nix; claude is not — install it separately
(nix profile install nixpkgs#nodejs && npm install -g @anthropic-ai/claude-code, or follow Anthropic's docs).

For declarative NixOS / Home Manager configs, add aipager as a flake
input and pick its package up from environment.systemPackages:

{
  inputs.aipager.url = "github:dev-aly3n/aipager";

  outputs = { self, nixpkgs, aipager, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [{
        environment.systemPackages = [
          aipager.packages.${pkgs.system}.default
        ];
      }];
    };
  };
}

aipager service install will then wire up a systemd-user unit.

Group mode (multi-user)

aipager runs by default as a 1:1 DM bot. To use it in a Telegram
group with several developers, add the bot to the group (as an admin,
so it can pin the group's status bar), re-run aipager config and
pick Add a group scope. The wizard offers you (the owner of your
own DM) as the group's owner, then adds each member with a role (owner / admin / user /
read_only), and reloads the running daemon. In the group the bot
acts only on commands, replies to its messages and mentions
(@aipagerbot fix the tests, /jim run the tests); each message runs
with its sender's role. Adding a user grants them code-execution
rights on the host: see docs/groups.md for the
full trust model.

AUR (Arch Linux)

yay -S aipager           # or paru, pikaur — any AUR helper

System dtach and python-telegram-bot come from pacman; install
the Anthropic claude CLI separately
(sudo pacman -S npm && sudo npm install -g @anthropic-ai/claude-code).
PKGBUILD lives at packaging/aur/ for review.

Snap

snap install aipager

Strict-confinement snap that bundles python + node + claude +
dtach + aipager. Because of snap's sandbox model, workspaces must
live under ~/ (e.g. ~/projects/foo). Manifest at
packaging/snap/.

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.

Setting aipager up for someone from a script or a coding agent?
aipager setup --token-file FILE --chat-id ID does the same with no
prompts (see the setup command
and the guide for agents).

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; to leave without stopping Claude, close the terminal or tmux
pane (the session keeps running).

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
• Sends your messages to Claude immediately, even mid-turn — send
  several and Claude queues them itself, exactly like typing in the
  terminal. 👀 means sent, 👍 means Claude picked it up
• Holds a message while a permission or question prompt is open, so it
  can never be swallowed as an answer to that dialog — then delivers it
  once you respond
• Surfaces permission prompts and AskUserQuestion dialogs as Telegram
  inline keyboards; buttons from an already-finished task refuse
  instead of acting on your current work
• Creates sessions from chat: /new walks name → mode → model → folder
• Notifies on context warnings, compaction, session end, and stalls
• Supports multiple concurrent sessions with one bot; optional
  multi-user team mode with roles and per-tool rules
  (docs/groups.md)
• Optional read-only observer bots

Mini App

/app opens a dashboard inside Telegram — live session list with
stop / kill / restart / rename / permission controls, a diff viewer
for Write/Edit changes, and settings. It is served by the daemon
itself and is on by default; every request is verified against
Telegram's initData signature. If you belong to more than one chat
(your DM and a group), a row of chat names at the top switches between
them. Manage it with
aipager miniapp enable|disable|status, or point it at your own URL
instead of the managed tunnel — see
docs/security.md.

Note on model buttons (Bedrock / Vertex users)

The persistent keyboard's Model submenu sends /model sonnet,
/model opus, /model haiku, and /model opusplan — Claude Code's
aliases. On the Anthropic API these resolve to the latest model in
each family. On Bedrock and
Vertex the same aliases may resolve to older snapshots depending on
your provider's available versions. If you target those backends and
want a specific model, tap the alias as a starting point, then /model <full-id> from chat.

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.