aipager
Claude is one more chat.
Your Claude Code sessions in Telegram, next to your family, your friends and your team.
They run on your own computer. You follow them, answer them and steer them from wherever you are.
Website · Install · Docs · Security · Changelog
Read this in: Español · Русский · Português (Brasil) · 简体中文 · Français · Deutsch · 한국어 · العربية · Bahasa Indonesia · Українська · Italiano · Türkçe · فارسی · Tiếng Việt
You write in Telegram. aipager types it into Claude Code on your computer, and one card edits itself as the turn runs.
Why aipager
|
📟 One live card per turn |
⚡ Talk to it mid-turn |
✅ Answer with a tap |
|
🛡️ Three permission modes |
👥 Made for teams |
🔒 Nothing in the middle |
A quick tour
Questions come to you
When Claude asks you something or wants permission, the question lands in your chat with a button for each answer, and the pinned bar says what needs you. Your tap is typed into the session as if you were at the keyboard, and the terminal shows the same answer.
Three permission modes
Every session is in one of three modes, changed any time with /mode, even while Claude works.
| Mode | What happens |
|---|---|
💬 Ask/mode ask |
Claude asks before each action. |
🤖 Auto, the default/mode auto |
Claude Code's own safety check runs the safe actions and stops the risky ones for you to decide. |
🔓 Full access/mode full |
Everything runs with no checks. For admins, and for you in your own private chat with the bot. |
Ask and Auto switch in place, with no restart. Going to or from Full access restarts the session and keeps the conversation. Questions from Claude still come to you in every mode.
Your team, in one group
Add the bot to a group and give each member a role: owner, admin, user or read_only. In the group the bot acts only on commands, replies to its messages and mentions (@aipagerbot fix the tests, /web run the tests), and each message runs with its sender's role: a tool the role may not use is refused before it runs. A user or read_only member works only inside their own root folder (~/aipager-users/<label> by default). Other people can also have their own private chat with the bot.
To set it up, add the bot to the group as an admin (so it can pin the group's status bar), run aipager config again and pick Add a group scope. The wizard adds each member with a role, asks for the members' root folder and reloads the running daemon.
A dashboard inside Telegram
/app opens the Mini App: your sessions with Stop, End, Restart, Rename and the mode switch, a diff viewer for every Write and Edit, the settings and, for the owner, Report a problem. It is served by the daemon itself and is on by default, and every request is checked against Telegram's signature. If you are in more than one chat, a row of chat names at the top switches between them. Turn it off with aipager miniapp disable, or point it at your own URL (how).
Fifteen languages
- Speaks English, Español, Русский, Português (Brasil), 简体中文, Français, Deutsch, 한국어, العربية, Bahasa Indonesia, Українська, Italiano, Türkçe, فارسی and Tiếng Việt.
- Pick one with
/language, or let a private chat follow your Telegram app. - Persian and Arabic read right to left, with their own digits.
- Only aipager's own words change. Your sessions do not: Claude answers in the language you write to it.
- This README and the docs are translated too.
And the small things
- Many sessions, one bot. A plain message goes to the session you last talked with; reply to one of a session's messages to talk to that one, or send
/x1 <message>. - Nothing gets mixed up. A message sent while a prompt or a question is open waits until you answer, so it is never read as the answer.
- Photos, files and voice. Voice messages are turned into text on your computer, with the optional
voiceextra. - It tells you. Context warnings, compaction, a session that ended and one that went quiet.
- Sessions outlive everything. Claude runs inside
dtach, so it keeps working after you close the terminal, lose SSH or restart the daemon.
How it works
Claude Code runs in a real terminal, inside dtach, so nobody has to keep a window open. Each step fires a hook that sends one datagram to the aipager daemon over a local socket, and the daemon edits a message in your chat. Your answers travel back the same way: a verdict to the hook holding the call, or keystrokes into the session. The terminal stays the source of truth. More in the architecture.
Install
Linux or macOS, any architecture. You need Claude Code, logged in on this computer, and a Telegram bot: create one with @BotFather and press Start in it.
curl -fsSL https://aipager.run/install | sh # uv, pipx or Homebrew: whichever you have
aipager config # your bot token, your chat, Claude Code's hooks
aipager service install # keeps the daemon running after you log out
aipager session api # Claude Code in this folder, and in your chat
The installer uses uv if you have it, else pipx, else (on macOS) Homebrew, and installs uv when none is there. dtach comes with aipager (the dtach-bin package), so there is nothing else to install. aipager config is a wizard: it checks the bot token and your chat, then adds aipager's hooks to ~/.claude/settings.json for you. You never edit a file by hand.
Let a coding agent install it for you
Have Claude Code, or any agent with a shell? Create the bot, press Start in it, and 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. For scripts, aipager setup --token-file FILE --chat-id ID sets aipager up with no questions (the setup command).
Other ways to install
uv tool install aipager # uv: recommended on macOS, it brings its own Python
pipx install aipager # pipx
brew install dev-aly3n/tap/aipager # Homebrew, on macOS and Linuxbrew (see the note below)
nix profile install github:dev-aly3n/aipager # Nix: claude is not included (see below)
snap install aipager # Snap: strict confinement, claude inside, workspaces under ~/
Or run it in Docker, with Python, Node, claude and dtach inside.
Homebrew on macOS 26 (Tahoe)
The formula works when Homebrew's python@3.12 bottle and your Xcode Command Line Tools are in sync, but they drift apart from time to time. On macOS 26 the install fails with a pyexpat _XML_SetAllocTrackerActivationThreshold symbol error (upstream issue). Updating Xcode and the Command Line Tools usually fixes it, but uv tool install aipager avoids it altogether. The formula takes dtach from Homebrew and installs aipager into a Homebrew-managed Python environment.
Docker
A self-contained image with Python, Node, claude and dtach, good for a VPS, a NAS or a Raspberry Pi where you do not 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 folders you want Claude to edit under /workspace. The ~/.claude mount carries your Claude credentials and conversation history: run claude on the host once to log in, or docker exec -it aipager claude to log in inside the container.
Tags: latest, 1.3, 1.3.7 (semver track + minor track).
Nix
nix run github:dev-aly3n/aipager -- --version
nix profile install github:dev-aly3n/aipager
Builds aipager from source against pinned nixpkgs. dtach comes from Nix; claude does not, so install it separately (nix profile install nixpkgs#nodejs && npm install -g @anthropic-ai/claude-code, or follow Anthropic's docs).
NixOS and Home Manager
Add aipager as a flake input and take its package into environment.systemPackages:
{
inputs.aipager.url = "github:dev-aly3n/aipager";
outputs = { self, nixpkgs, aipager, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
modules = [({ pkgs, ... }: {
environment.systemPackages = [
aipager.packages.${pkgs.system}.default
];
})];
};
};
}
aipager service install then sets up a systemd user unit.
Everyday use
In Telegram
| Send | To |
|---|---|
/status |
See this chat's sessions, each with its state and buttons. |
/new x1 |
Start a session named x1. /new x1 fix the tests also sends its first message. |
/x1 |
Make x1 the session your messages go to. /x1 <message> sends a message straight to it. |
/stop |
Interrupt the running turn and drop what is queued. |
/mode |
Switch between Ask, Auto and Full access. |
/app |
Open the Mini App. |
/language |
Pick the language aipager speaks in this chat. |
/update |
Update aipager and Claude Code, then restart in place (admins). |
/help |
A short guide by task. |
Every command, button and setting is in docs/commands.md.
On the command line
aipager start # the daemon, in the foreground
aipager session dev # start a session named dev here, or attach to it
aipager session dev --continue # pick up the last Claude conversation in this folder
aipager session dev -- --resume abc1234 # any other claude flag goes through as it is
aipager doctor # check the install
To leave a session without stopping Claude, close the terminal or the tmux pane: the session keeps running, and the same command attaches to it again.
aipager service install keeps the daemon running in the background: a systemd user unit on Linux (~/.config/systemd/user/aipager.service) or a launchd agent on macOS (~/Library/LaunchAgents/com.aipager.daemon.plist). Either way the daemon runs in your home folder, where a new session starts unless you pick another folder. aipager service start, stop, status, logs and uninstall manage it.
Security
- No aipager server. The daemon talks to the Telegram Bot API with your own bot token. There is no aipager account and no aipager service.
- No open port. The daemon listens on loopback only. The Mini App goes out through a Cloudflare tunnel where every request must carry Telegram's signature, and
aipager miniapp disableturns it off. - Every answer on the record. Each Allow, Deny and answer is appended to
~/.claude/aipager-audit.jsonl, with who tapped it in a group. - Claude Code still decides. Your Claude Code settings say what needs asking. aipager relays the question and never elevates: no sudo, and everything runs as your user.
The full picture, including what protects your Claude credential, is in the security model.
FAQ
How is this different from Claude's mobile apps?
Claude's apps talk to Anthropic's hosted assistant. aipager connects you to a Claude Code session running on your own computer: your repository, your tools, your environment.
Does my code leave my computer?
aipager sends to Telegram only what you see in your chats, with your own bot token; there is no aipager server in between. Claude Code itself talks to Anthropic as it always does.
What is dtach?
A tiny terminal detacher. It keeps Claude Code alive after the terminal closes or SSH drops, so an answer you send an hour later still reaches a live session. It comes with aipager.
What if Claude goes off the rails?
Prompts wait for your tap, /stop interrupts the turn and drops anything queued, /kill ends the session, and buttons from a finished turn refuse.
How do I update it?
Send /update: it checks aipager and Claude Code and installs what is new, and 🔄 Restart now brings the daemon back, under a service or not. Your sessions keep running through it. On the command line, aipager update upgrades through the installer that owns aipager.
I use Bedrock or Vertex. Do the model buttons work?
The keyboard's Model menu and the Mini App offer Claude Code's family aliases (sonnet, opus, haiku, fable, opusplan) and pinned models such as claude-opus-5-5 and claude-sonnet-5-5. On the Anthropic API an alias resolves to the latest model in its family. On Bedrock and Vertex the same alias may resolve to an older snapshot, depending on what your provider offers; send /model <full-id> to pick an exact model.
What does it cost?
Nothing. aipager is MIT licensed, the bot is yours, and Claude Code keeps using whatever plan or key it already uses.
Documentation
| Page | What is in it |
|---|---|
| Commands | Every command, button, setting and command-line option |
| Groups and team mode | Roles, root folders, who can tap what, the trust model |
| Security | The trust boundary, secrets, the audit log, the network |
| Hooks | What each Claude Code hook does in aipager |
| Architecture | The daemon's parts, files and sockets |
| Troubleshooting | aipager doctor and fixes for common problems |
| Problem reports | What a report contains, and when one is offered |
| Install with an agent | The guide a coding agent follows |
Contributing
git clone https://github.com/dev-aly3n/aipager.git && cd aipager
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
systemd-run --user --scope -q -p MemoryMax=2G -p MemorySwapMax=0 \
.venv/bin/python -m pytest -q -p no:cacheprovider
ruff check aipager tests
dtach comes with the dtach-bin dependency, so nothing else is needed. Run the tests under a memory cap as above (on macOS, without systemd-run): a runaway test can otherwise take the machine's memory. The release process is in CONTRIBUTING.md.
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for aipager 1.3.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| aipager-1.3.7.tar.gz | 7.8 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aipager-1.3.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 9.9 MB
Release files / aipager-1.3.7.tar.gz
| Download URL | aipager-1.3.7.tar.gz |
|---|---|
| Size | 7.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
215d59a3e83949c3867d47edf8b77d360a41f4617f347284db47763b75143ca9
|
|
BLAKE2b-256 checksum How to use checksums |
295dde1a37984abf243c964461cb97170f6a835d1533d5ec6a9dee0f4ca3f73c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / aipager-1.3.7-py3-none-any.whl
| Download URL | aipager-1.3.7-py3-none-any.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
84b535fbfbd8c8a02e40b370a8b30d2cca50614bdc78bad1e9032a8c67d4b1c1
|
|
BLAKE2b-256 checksum How to use checksums |
2af5caad6c999ccc2fca984cf315c0dad8881e877917b2264946a6776de89bdd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for aipager 1.3.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for aipager-1.3.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
