aipager 0.2.0__tar.gz

aipager-0.2.0/.env.example

@@ -0,0 +1,15 @@
+# Required
+CLAUDE_TG_BOT_TOKEN=your-bot-token-here
+CLAUDE_TG_CHAT_ID=your-chat-id-here
+
+# Optional: working directory for Claude Code sessions (default: cwd)
+# AIPAGER_WORK_DIR=/path/to/your/project
+
+# Optional: observer bot tokens (read-only mirrors)
+# OBSERVER_BOTS=token1:chatid1,token2:chatid2
+
+# Optional: rich markdown→HTML summaries (default: 1)
+# CLAUDE_RICH_SUMMARIES=1
+
+# Optional: stale busy alert threshold in seconds (default: 1200 = 20min)
+# STALE_BUSY_TIMEOUT=1200

aipager-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

aipager-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest py${{ matrix.python }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e '.[dev]'
+      - run: ruff check aipager tests
+      - run: pytest -q

aipager-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.sock
+.claude/
+tasks/
+PLAN.md
+.pytest_cache/
+.ruff_cache/

aipager-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-16
+
+### Added
+- Depend on [`dtach-bin`](https://pypi.org/project/dtach-bin/) so
+  `pipx install aipager` pulls in a precompiled `dtach` binary for
+  Linux x86_64/aarch64 and macOS x86_64/arm64. No manual system
+  package install needed.
+- GitHub Actions workflows: `test.yml` (ruff + pytest on Python
+  3.10–3.13) and `publish.yml` (build + Trusted Publisher OIDC upload
+  on tag push).
+- `CONTRIBUTING.md` documenting the local dev setup and release flow.
+
+### Changed
+- README leads with `pipx install aipager` as the primary install
+  path; `pip install -e .` demoted to a "Developing locally" section.
+
+## [0.1.0] - 2026-05-16
+
+### Added
+- `pyproject.toml` with hatchling backend
+- MIT license
+- README and Changelog
+- Console script entry points: `aipager`, `aipager-hook`,
+  `aipager-statusline`, `claude-dtach`
+- `aipager` CLI with `start`, `config`, `version` subcommands
+- `aipager config` — interactive setup wizard that patches
+  `~/.claude/settings.json` and writes `~/.config/aipager/config.env`
+- XDG-compliant config path (`~/.config/aipager/config.env`) with cwd
+  `.env` fallback
+- Pure-Python port of the `claude-dtach` session launcher
+- Test suite for state machine, markdown→HTML converter, and config loader
+
+### Fixed
+- Removed hardcoded transcript directory path that worked on only one
+  machine; transcript discovery now scans all project subdirs under
+  `~/.claude/projects/`.

aipager-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to aipager
+
+## Local development
+
+```sh
+git clone https://github.com/dev-aly3n/aipager && cd aipager
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+pytest -q
+ruff check aipager tests
+```
+
+### Running the daemon during development
+
+After `pip install -e .`, four console scripts are on your PATH:
+
+| Script | What it does |
+|---|---|
+| `aipager` | the CLI dispatcher (`start`, `config`, `version`) |
+| `aipager-hook` | Claude Code hook handler — invoked by Claude per event |
+| `aipager-statusline` | Claude Code statusLine — invoked on every tick |
+| `claude-dtach` | launches a Claude Code session under `dtach` |
+
+Tweak code, then `aipager start` runs the daemon with your changes
+(editable install means no reinstall needed for `.py` edits).
+
+### `dtach` during development
+
+`dtach-bin` is a runtime dependency. If it's not yet on PyPI (or you're
+testing changes to it), install from a local checkout:
+
+```sh
+pip install /path/to/dtach-bin
+```
+
+Otherwise `pip install -e '.[dev]'` will pull the published version
+from PyPI.
+
+## Release process
+
+Releases are tag-driven. Tagging a commit on `main` triggers
+`.github/workflows/publish.yml`, which builds `sdist` + `wheel` and
+uploads via PyPI Trusted Publisher (OIDC — no stored API token).
+
+### Cutting a release
+
+1. Bump `version` in `pyproject.toml`
+2. Add a `[X.Y.Z]` section at the top of `CHANGELOG.md`
+3. Commit: `git commit -m "bump version to X.Y.Z"`
+4. Tag: `git tag vX.Y.Z && git push origin main --tags`
+5. CI builds and publishes within ~2 minutes
+
+### First-time PyPI Trusted Publisher setup (one-time)
+
+Before the first OIDC release, you need:
+
+1. A PyPI account at https://pypi.org/account/register/
+2. The first upload done manually with an API token:
+   ```sh
+   pip install build twine
+   python -m build
+   twine upload dist/*
+   ```
+3. Register a Trusted Publisher on PyPI for the project:
+   - Project settings → Publishing → Add a trusted publisher
+   - Provider: GitHub Actions
+   - Owner: `dev-aly3n`
+   - Repository: `aipager`
+   - Workflow file: `publish.yml`
+   - Environment: (leave blank)
+
+After this, all future releases use OIDC. No tokens are stored anywhere.
+
+## Style / linting
+
+```sh
+ruff check aipager tests
+ruff format aipager tests  # if you want auto-formatting
+```
+
+The CI matrix runs Python 3.10 through 3.13 — keep the codebase free of
+3.11+ syntax (no `Self`, no `TypeVarTuple` etc.). Use
+`from __future__ import annotations` for new files that need modern
+typing.
+
+## Commit style
+
+One-liner subject, lowercase imperative mood, ≤72 chars. No commit
+body. Examples:
+
+- `fix transcript path scan to handle multi-cwd setups`
+- `add aipager service subcommand for systemd-user installer`
+
+Squash-merge PRs that have noisy intermediate commits — the main branch
+log should be a clean reading order.

aipager-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev-aly3n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aipager-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: aipager
+Version: 0.2.0
+Summary: Telegram remote-control daemon for Claude Code CLI sessions running in dtach
+Project-URL: Source, https://github.com/dev-aly3n/aipager
+Project-URL: Issues, https://github.com/dev-aly3n/aipager/issues
+Project-URL: Changelog, https://github.com/dev-aly3n/aipager/blob/main/CHANGELOG.md
+Author-email: dev-aly3n <66creation@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,dtach,remote-control,telegram,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: dtach-bin>=0.9
+Requires-Dist: python-telegram-bot>=20
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aipager
+
+Telegram remote-control for [Claude Code](https://claude.com/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
+
+Requires Python 3.10+. **`dtach` is installed automatically** via the
+[`dtach-bin`](https://pypi.org/project/dtach-bin/) dependency — no
+separate system package needed.
+
+```sh
+pipx install aipager
+```
+
+(or `uv tool install aipager`, or `pip install aipager` into a venv —
+all work the same.)
+
+Linux ARM and macOS users on Apple Silicon get the same one-command
+install; the dtach binary ships as pre-built wheels for each platform.
+
+> **Homebrew support is coming in v0.3** as `brew install <user>/tap/aipager`,
+> which uses the system `dtach` instead of the bundled one.
+
+## Configure
+
+```sh
+aipager config
+```
+
+Interactive wizard — asks for your Telegram bot token (from
+[@BotFather](https://t.me/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
+
+```sh
+aipager start
+```
+
+The daemon stays in the foreground. Launch a Claude session in another
+terminal:
+
+```sh
+claude-dtach dev
+```
+
+The daemon discovers the session within seconds and Telegram starts
+mirroring it. To survive logout, use `screen`, `tmux`, or a systemd-user
+unit (template at `scripts/aipager.service.example` — full `aipager
+service install` automation lands in v0.4).
+
+## 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
+
+```sh
+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](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aipager-0.2.0/README.md

@@ -0,0 +1,84 @@
+# aipager
+
+Telegram remote-control for [Claude Code](https://claude.com/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
+
+Requires Python 3.10+. **`dtach` is installed automatically** via the
+[`dtach-bin`](https://pypi.org/project/dtach-bin/) dependency — no
+separate system package needed.
+
+```sh
+pipx install aipager
+```
+
+(or `uv tool install aipager`, or `pip install aipager` into a venv —
+all work the same.)
+
+Linux ARM and macOS users on Apple Silicon get the same one-command
+install; the dtach binary ships as pre-built wheels for each platform.
+
+> **Homebrew support is coming in v0.3** as `brew install <user>/tap/aipager`,
+> which uses the system `dtach` instead of the bundled one.
+
+## Configure
+
+```sh
+aipager config
+```
+
+Interactive wizard — asks for your Telegram bot token (from
+[@BotFather](https://t.me/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
+
+```sh
+aipager start
+```
+
+The daemon stays in the foreground. Launch a Claude session in another
+terminal:
+
+```sh
+claude-dtach dev
+```
+
+The daemon discovers the session within seconds and Telegram starts
+mirroring it. To survive logout, use `screen`, `tmux`, or a systemd-user
+unit (template at `scripts/aipager.service.example` — full `aipager
+service install` automation lands in v0.4).
+
+## 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
+
+```sh
+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](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aipager-0.2.0/aipager/OBSERVERS.md

@@ -0,0 +1,44 @@
+# Observer Bots
+
+Read-only Telegram bots that mirror notifications from the primary bot. They receive summaries, warnings, and errors — but can't control sessions.
+
+## Setup
+
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Start a chat with the bot and send `/start`
+3. Get your chat ID (send a message, then check `https://api.telegram.org/bot<TOKEN>/getUpdates`)
+4. Add to `.env`:
+
+```
+OBSERVER_BOTS=<bot_token>:<chat_id>
+```
+
+Multiple observers (comma-separated):
+
+```
+OBSERVER_BOTS=111:AAA_first:12345,222:BBB_second:67890
+```
+
+The format is `token:chat_id` — parsing uses the **last** colon as delimiter (bot tokens contain an internal colon).
+
+5. Restart the daemon
+
+## What observers receive
+
+| Event | Example |
+|-------|---------|
+| Idle summary | "Finished" + response text (+ .txt file for long responses) |
+| API error | "Anthropic servers overloaded" (no retry button) |
+| Context warning | "Context at 82% — auto-compact soon" |
+| Compacting | "Compacting" |
+| Compact done | "Compacted: 82% → 4%" |
+
+## What observers DON'T receive
+
+- Busy animations / spinner
+- Tool call updates
+- Permission prompts (Allow/Deny)
+- AskUserQuestion dialogs
+- Any inline keyboards or buttons
+
+Observers are completely stateless — fire-and-forget sends. A failing observer never affects the primary bot.

aipager-0.2.0/aipager/__init__.py

@@ -0,0 +1,8 @@
+"""aipager — Telegram remote control for Claude Code sessions."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("aipager")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

aipager-0.2.0/aipager/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m aipager` — delegates to the CLI."""
+
+from aipager.cli import main
+
+if __name__ == "__main__":
+    main()

aipager-0.2.0/aipager/_dtach_redraw.py

@@ -0,0 +1,95 @@
+"""Force a TUI redraw in a dtach session by bouncing the PTY window size.
+
+dtach has no screen buffer — reattaching shows a blank screen. TUI apps
+(Ink/React) only redraw on genuine dimension changes due to three
+independent same-size guards (Linux kernel, Node.js, Ink).
+
+`redraw(name)` changes the PTY size to (rows-1, cols), waits 50ms, then
+restores (rows, cols) — forcing two genuine SIGWINCH signals and a full
+redraw.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import struct
+import subprocess
+import sys
+import termios
+import time
+
+
+def find_pty(session_name: str) -> str | None:
+    """Find the PTY slave device for a claude-dtach session's child process."""
+    try:
+        result = subprocess.run(
+            ["pgrep", "-f", f"dtach -n.*/claude-dtach-{session_name}\\.sock"],
+            capture_output=True, text=True, timeout=5,
+        )
+        dtach_pid = result.stdout.strip().split("\n")[0]
+        if not dtach_pid:
+            return None
+    except Exception:
+        return None
+
+    try:
+        result = subprocess.run(
+            ["pgrep", "-P", dtach_pid],
+            capture_output=True, text=True, timeout=5,
+        )
+        child_pid = result.stdout.strip().split("\n")[0]
+        if not child_pid:
+            return None
+    except Exception:
+        return None
+
+    try:
+        pty = os.readlink(f"/proc/{child_pid}/fd/1")
+        if pty.startswith("/dev/pts/"):
+            return pty
+    except Exception:
+        pass
+    return None
+
+
+def bounce_size(pty_path: str) -> bool:
+    """Bounce PTY dimensions: (rows-1) then restore. Triggers two SIGWINCHs."""
+    try:
+        fd = os.open(pty_path, os.O_RDWR | os.O_NOCTTY)
+    except OSError:
+        return False
+    try:
+        buf = fcntl.ioctl(fd, termios.TIOCGWINSZ, b"\x00" * 8)
+        rows, cols, xpix, ypix = struct.unpack("HHHH", buf)
+        if rows <= 1:
+            return False
+        fcntl.ioctl(fd, termios.TIOCSWINSZ,
+                    struct.pack("HHHH", rows - 1, cols, xpix, ypix))
+        time.sleep(0.05)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ,
+                    struct.pack("HHHH", rows, cols, xpix, ypix))
+        return True
+    except Exception:
+        return False
+    finally:
+        os.close(fd)
+
+
+def redraw(session_name: str) -> bool:
+    """Bounce PTY size for the given session — returns True on success."""
+    pty = find_pty(session_name)
+    if not pty:
+        return False
+    return bounce_size(pty)
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(f"Usage: {sys.argv[0]} <session-name>", file=sys.stderr)
+        return 1
+    return 0 if redraw(sys.argv[1]) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())