ccgram 2.0.0__tar.gz

ccgram-2.0.0/.claude/rules/architecture.md

@@ -0,0 +1,142 @@
+# System Architecture
+
+```mermaid
+graph TB
+    subgraph bot["Telegram Bot — bot.py"]
+        direction TB
+        BotCore["Topic routing · /history · /sessions\nStatus messages · Interactive UI\nMessage queue + worker · MarkdownV2"]
+        BotSub1["markdown_v2.py\nMD → MarkdownV2 + expandable quotes"]
+        BotSub2["telegram_sender.py\nsplit_message — 4096 limit"]
+        Terminal["terminal_parser.py + screen_buffer.py\npyte VT100 · interactive UI detection\nspinner parsing · separator detection"]
+    end
+
+    subgraph monitor["SessionMonitor — session_monitor.py"]
+        Mon["Poll JSONL every 2s · mtime cache\nParse new lines · track pending tools\nRead events.jsonl incrementally"]
+    end
+
+    subgraph tmux["TmuxManager — tmux_manager.py"]
+        Tmux["list/find/create/kill windows\nsend_keys · capture_pane\nlist_panes · send_keys_to_pane"]
+    end
+
+    subgraph parsing["TranscriptParser — transcript_parser.py"]
+        TP["Parse JSONL · pair tool_use ↔ tool_result\nExpandable quotes for thinking · history"]
+    end
+
+    subgraph windows["Tmux Windows"]
+        Win["One window per topic/session\nClaude Code · Codex · Gemini"]
+    end
+
+    subgraph hook["Hook — hook.py"]
+        Hook["Receive hook stdin\nWrite session_map.json\nWrite events.jsonl"]
+    end
+
+    subgraph session["SessionManager — session.py"]
+        SM["Window ↔ Session resolution\nThread bindings · message history"]
+    end
+
+    subgraph state["State Files — ~/.ccgram/"]
+        MonState["MonitorState\nbyte offsets per session"]
+        Sessions["Claude Sessions\n~/.claude/projects/\nsessions-index + *.jsonl"]
+    end
+
+    bot -- "Notify\n(NewMessage callback)" --> monitor
+    bot -- "Send\n(tmux keys)" --> tmux
+    monitor --> parsing
+    tmux --> windows
+    windows -- "Claude Code hooks\n(7 event types)" --> hook
+    hook -- "session_map.json\n+ events.jsonl" --> session
+    session -- "reads JSONL" --> Sessions
+    monitor -- "reads" --> MonState
+
+    style bot fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333
+    style monitor fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#333
+    style tmux fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333
+    style parsing fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#333
+    style windows fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333
+    style hook fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#333
+    style session fill:#e8eaf6,stroke:#283593,stroke-width:2px,color:#333
+    style state fill:#f5f5f5,stroke:#616161,stroke-width:2px,color:#333
+```
+
+## Module Inventory
+
+### Provider modules (`providers/`)
+
+| Module        | Description                                                                              |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| `base.py`     | AgentProvider protocol, ProviderCapabilities, event types                                |
+| `registry.py` | ProviderRegistry (name→factory map, singleton cache)                                     |
+| `_jsonl.py`   | Shared JSONL parsing base class for Codex + Gemini                                       |
+| `claude.py`   | ClaudeProvider (hook, resume, continue, JSONL transcripts)                               |
+| `codex.py`    | CodexProvider (resume, continue, JSONL transcripts, no hook)                             |
+| `gemini.py`   | GeminiProvider (resume, continue, whole-file JSON transcripts, no hook)                  |
+| `__init__.py` | `get_provider_for_window()`, `detect_provider_from_command()`, `get_provider()` fallback |
+
+### Core modules (`src/ccgram/`)
+
+| Module             | Description                                                          |
+| ------------------ | -------------------------------------------------------------------- |
+| `cli.py`           | Click-based CLI entry point (run subcommand + all bot-config flags)  |
+| `config.py`        | Application configuration singleton (env vars, .env files, defaults) |
+| `doctor_cmd.py`    | `ccgram doctor [--fix]` — validate setup without bot token           |
+| `status_cmd.py`    | `ccgram status` — show running state without bot token               |
+| `screen_buffer.py` | pyte VT100 screen buffer (ANSI→clean lines, separator detection)     |
+| `cc_commands.py`   | CC command discovery (skills, custom commands) + menu registration   |
+| `screenshot.py`    | Terminal text → PNG rendering (ANSI color, font fallback)            |
+| `main.py`          | Application entry point (Click dispatcher, run_bot bootstrap)        |
+| `utils.py`         | Shared utilities (ccgram_dir, tmux_session_name, atomic_write_json)  |
+
+### Handler modules (`handlers/`)
+
+| Module                     | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `text_handler.py`          | Text message routing (UI guards → unbound → dead → forward)        |
+| `message_sender.py`        | safe_reply/safe_edit/safe_send + rate_limit_send                   |
+| `message_queue.py`         | Per-user queue + worker (merge, status dedup)                      |
+| `status_polling.py`        | Background status polling (1s), auto-close, multi-pane scanning    |
+| `response_builder.py`      | Response pagination and formatting                                 |
+| `interactive_ui.py`        | AskUserQuestion / ExitPlanMode / Permission UI rendering           |
+| `interactive_callbacks.py` | Callbacks for interactive UI (arrow keys, enter, esc)              |
+| `directory_browser.py`     | Directory selection UI for new topics                              |
+| `directory_callbacks.py`   | Callbacks for directory browser (navigate, confirm, provider pick) |
+| `window_callbacks.py`      | Window picker callbacks (bind, new, cancel)                        |
+| `recovery_callbacks.py`    | Dead window recovery callbacks (fresh, continue, resume)           |
+| `screenshot_callbacks.py`  | Screenshot refresh, Esc, quick-key, pane screenshot callbacks      |
+| `history.py`               | Message history display with pagination                            |
+| `history_callbacks.py`     | History pagination callbacks (prev/next)                           |
+| `sessions_dashboard.py`    | /sessions command: active session overview + kill                  |
+| `restore_command.py`       | /restore command: recover dead topics via recovery keyboard        |
+| `resume_command.py`        | /resume command: scan past sessions, paginated picker              |
+| `upgrade.py`               | /upgrade command: uv tool upgrade + process restart                |
+| `file_handler.py`          | Photo/document handler (save to .ccgram-uploads/, notify agent)    |
+| `command_history.py`       | Per-user/per-topic in-memory command recall (max 20)               |
+| `topic_emoji.py`           | Topic name emoji updates (active/idle/done/dead), debounced        |
+| `hook_events.py`           | Hook event dispatcher (Notification, Stop, Subagent*, Team*)       |
+| `cleanup.py`               | Centralized topic state cleanup on close/delete                    |
+| `callback_data.py`         | CB\_\* callback data constants for inline keyboard routing         |
+| `callback_helpers.py`      | Shared helpers (user_owns_window, get_thread_id)                   |
+| `user_state.py`            | context.user_data string key constants                             |
+
+### State files (`~/.ccgram/` or `$CCBOT_DIR/`)
+
+| File                 | Description                                                    |
+| -------------------- | -------------------------------------------------------------- |
+| `state.json`         | Thread bindings + window states + display names + read offsets |
+| `session_map.json`   | Hook-generated window_id→session mapping                       |
+| `events.jsonl`       | Append-only hook event log (all 7 event types)                 |
+| `monitor_state.json` | Poll progress (byte offset) per JSONL file                     |
+
+## Key Design Decisions
+
+- **Topic-centric** — Each Telegram topic binds to one tmux window. No centralized session list; topics _are_ the session list.
+- **Window ID-centric** — All internal state keyed by tmux window ID (e.g. `@0`, `@12`), not window names. Window IDs are guaranteed unique within a tmux server session. Window names are kept as display names via `window_display_names` map. Same directory can have multiple windows.
+- **Hook-based event system** — Claude Code hooks (SessionStart, Notification, Stop, SubagentStart, SubagentStop, TeammateIdle, TaskCompleted) write to `session_map.json` and `events.jsonl`. SessionMonitor reads both: session_map for session tracking, events.jsonl for instant event dispatch (interactive UI, done detection, subagent status, team notifications). Terminal scraping remains as fallback. Missing hooks are detected at startup with an actionable warning.
+- **Multi-pane awareness** — Windows with multiple panes (e.g. Claude Code agent teams) are scanned for interactive prompts in non-active panes. Blocked panes are auto-surfaced as inline keyboard alerts. `/panes` command lists all panes with status and per-pane screenshot buttons. Callback data format extended to include pane_id: `"aq:enter:@12:%5"`.
+- **Tool use ↔ tool result pairing** — `tool_use_id` tracked across poll cycles; tool result edits the original tool_use Telegram message in-place.
+- **MarkdownV2 with fallback** — All messages go through `safe_reply`/`safe_edit`/`safe_send` which convert via `telegramify-markdown` and fall back to plain text on parse failure.
+- **No truncation at parse layer** — Full content preserved; splitting at send layer respects Telegram's 4096 char limit with expandable quote atomicity.
+- Only sessions registered in `session_map.json` (via hook) are monitored.
+- Notifications delivered to users via thread bindings (topic → window_id → session).
+- **Startup re-resolution** — Window IDs reset on tmux server restart. On startup, `resolve_stale_ids()` matches persisted display names against live windows to re-map IDs. Old state.json files keyed by window name are auto-migrated.
+- **Per-window provider** — All CLI-specific behavior (launch args, transcript parsing, terminal status, command discovery) is delegated to an `AgentProvider` protocol. Providers declare capabilities (`ProviderCapabilities`) that gate UX features per-window: hook checks, resume/continue buttons, and command registration. Each window stores its `provider_name` in `WindowState`; `get_provider_for_window(window_id)` resolves the correct provider instance, falling back to the config default. Externally created windows are auto-detected via `detect_provider_from_command(pane_current_command)`. The global `get_provider()` singleton remains for CLI commands (`doctor`, `status`) that lack window context.
+- **Foreign window support (emdash)** — Windows owned by external tools (emdash) use qualified IDs like `emdash-claude-main-abc123:@0` which are valid tmux `-t` targets. Foreign windows are marked `WindowState.external=True` and are never killed by ccgram. Discovery via `tmux list-sessions` filtered by `emdash-` prefix. The `window_resolver` preserves foreign entries during startup re-resolution. All tmux operations (send_keys, capture_pane) route foreign IDs through subprocess instead of libtmux.

ccgram-2.0.0/.claude/rules/message-handling.md

@@ -0,0 +1,40 @@
+# Message Handling
+
+## Message Queue Architecture
+
+Per-user message queues + worker pattern for all send tasks:
+- Messages are sent in receive order (FIFO)
+- Status messages always follow content messages
+- Multi-user concurrent processing without interference
+
+**Message merging**: The worker automatically merges consecutive mergeable content messages on dequeue:
+- Content messages for the same window can be merged (including text, thinking)
+- tool_use breaks the merge chain and is sent separately (message ID recorded for later editing)
+- tool_result breaks the merge chain and is edited into the tool_use message (preventing order confusion)
+- Merging stops when combined length exceeds 3800 characters (to avoid pagination)
+
+## Status Message Handling
+
+**Conversion**: The status message is edited into the first content message, reducing message count:
+- When a status message exists, the first content message updates it via edit
+- Subsequent content messages are sent as new messages
+
+**Polling**: Background task polls terminal status for all active windows at 1-second intervals. Send-layer rate limiting ensures flood control is not triggered.
+
+**Deduplication**: The worker compares `last_text` when processing status updates; identical content skips the edit, reducing API calls.
+
+## Rate Limiting
+
+- Minimum 1.1-second interval between messages per user
+- Status polling interval: 1 second (send layer has rate limiting protection)
+- Automated outbound messages (queue worker, status updates) go through `rate_limit_send()`
+
+## Performance Optimizations
+
+**mtime cache**: The monitoring loop maintains an in-memory file mtime cache, skipping reads for unchanged files.
+
+**Byte offset incremental reads**: Each tracked session records `last_byte_offset`, reading only new content. File truncation (offset > file_size) is detected and offset is auto-reset.
+
+## No Message Truncation
+
+Historical messages (tool_use summaries, tool_result text, user/assistant messages) are always kept in full — no character-level truncation at the parsing layer. Long text is handled exclusively at the send layer: `split_message` splits by Telegram's 4096-character limit; real-time messages get `[1/N]` text suffixes, history pages get inline keyboard navigation.

ccgram-2.0.0/.claude/rules/topic-architecture.md

@@ -0,0 +1,79 @@
+# Topic-Only Architecture
+
+The bot operates exclusively in Telegram Forum (topics) mode. There is **no** `active_sessions` mapping, **no** `/list` command, **no** General topic routing, and **no** backward-compatibility logic for older non-topic modes. Every code path assumes named topics.
+
+## 1 Topic = 1 Window = 1 Session
+
+```mermaid
+graph LR
+    Topic["Topic ID\n(Telegram)"]
+    Window["Window ID\n(tmux @id)"]
+    Session["Session ID\n(Claude)"]
+
+    Topic -- "thread_bindings\n(state.json)" --> Window
+    Window -- "session_map.json\n(written by hook)" --> Session
+
+    style Topic fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333
+    style Window fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333
+    style Session fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#333
+```
+
+Window IDs (e.g. `@0`, `@12`) are guaranteed unique within a tmux server session. Window names are stored separately as display names (`window_display_names` map).
+
+## Mapping 1: Topic → Window ID (thread_bindings)
+
+```python
+# session.py: SessionManager
+thread_bindings: dict[int, dict[int, str]]  # user_id → {thread_id → window_id}
+window_display_names: dict[str, str]        # window_id → window_name (for display)
+```
+
+- Storage: memory + `state.json`
+- Written when: user creates a new session via the directory browser in a topic
+- Purpose: route user messages to the correct tmux window
+
+## Mapping 2: Window ID → Session (session_map.json)
+
+```python
+# session_map.json (key format: "tmux_session:window_id")
+{
+  "ccgram:@0": {"session_id": "uuid-xxx", "cwd": "/path/to/project", "window_name": "project", "provider_name": "claude", "transcript_path": "..."},
+  "ccgram:@5": {"session_id": "uuid-yyy", "cwd": "/path/to/project", "window_name": "project-2", "provider_name": "codex", "transcript_path": "..."}
+}
+```
+
+- Storage: `session_map.json`
+- Written when: Claude Code's `SessionStart` hook fires (always sets `provider_name: "claude"`; other providers have no hook). All 7 hook events also append to `events.jsonl` for instant dispatch.
+- Property: one window maps to one session; session_id changes after `/clear`
+- Purpose: SessionMonitor reads session_map to decide which sessions to watch, and reads events.jsonl for instant event notifications (interactive UI, done detection, subagent status)
+
+## Message Flows
+
+**Outbound** (user → Claude):
+
+```
+User sends "hello" in topic (thread_id=42)
+  → thread_bindings[user_id][42] → "@0"
+  → send_to_window("@0", "hello")   # resolves via find_window_by_id
+```
+
+**Inbound** (Claude → user):
+
+```
+SessionMonitor reads new message (session_id = "uuid-xxx")
+  → Iterate thread_bindings, find (user, thread) whose window_id maps to this session
+  → Deliver message to user in the correct topic (thread_id)
+```
+
+**New topic flow**: First message in an unbound topic → directory browser → select directory → select provider → create window with chosen provider → bind topic → forward pending message.
+
+**Topic lifecycle**: Closing/deleting a topic auto-kills the associated tmux window and unbinds the thread. Stale bindings (window deleted externally) are cleaned up by the status polling loop.
+
+## Session Lifecycle
+
+**Startup cleanup**: On bot startup, all tracked sessions not present in session_map are cleaned up, preventing monitoring of closed sessions.
+
+**Runtime change detection**: Each polling cycle checks for session_map changes:
+
+- Window's session_id changed (e.g., after `/clear`) → clean up old session
+- Window deleted → clean up corresponding session

ccgram-2.0.0/.claude/skills/releasing/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: releasing
+description: Tag version and trigger PyPI + Homebrew release. Use when user says "release", "tag and release", "publish version".
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Bash(git *), Bash(gh *), Bash(make check), Read
+argument-hint: <version> (e.g., 0.3.0)
+model: haiku
+---
+
+# Release v$ARGUMENTS
+
+Tag and publish a new version to PyPI and Homebrew.
+
+## Pre-flight
+
+1. Verify on `main` branch: `git branch --show-current`
+2. Verify working tree is clean: `git status`
+3. Run `make check` — all must pass
+4. Confirm no unpushed commits: `git log origin/main..HEAD --oneline`
+
+## Tag and Push
+
+5. Tag: `git tag v$ARGUMENTS`
+6. Push tag: `git push origin v$ARGUMENTS`
+
+## Monitor
+
+7. Wait 30s, then check: `gh api repos/alexei-led/ccbot/actions/runs --jq '.workflow_runs[0] | "\(.name): \(.status) \(.conclusion // "running")"'`
+8. If publish job failed, show logs and stop
+9. If update-homebrew failed, show logs and stop
+10. Report final status
+
+## Notes
+
+- hatch-vcs generates version from tag: `v0.3.0` → PyPI `0.3.0`
+- Release workflow: `.github/workflows/release.yml`
+- Re-tag if needed: `git tag -d v$ARGUMENTS && git push origin :refs/tags/v$ARGUMENTS && git tag v$ARGUMENTS && git push origin v$ARGUMENTS`

ccgram-2.0.0/.env.example

@@ -0,0 +1,32 @@
+# Telegram Bot Token (required)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# Allowed user IDs (comma-separated, required)
+ALLOWED_USERS=123456789,987654321
+
+# Tmux session name (optional, defaults to "ccgram")
+TMUX_SESSION_NAME=ccgram
+
+# Monitor polling interval in seconds (optional, defaults to 2.0)
+MONITOR_POLL_INTERVAL=2.0
+
+# Multi-instance: Telegram group chat ID this instance owns (optional)
+# When set, this instance only processes updates from this group.                                                                                                                        
+# Get the ID via @userinfobot or @RawDataBot in your group.                                                                                                                            
+# CCGRAM_GROUP_ID=-1001234567890                                                         
+                                                                     
+# Multi-instance: display name for this instance (optional, defaults to hostname)
+# CCGRAM_INSTANCE_NAME=bot-1
+
+# Per-provider launch command overrides (optional)
+# CCGRAM_CLAUDE_COMMAND=my-claude-wrapper (defaults to "claude")
+# CCGRAM_CODEX_COMMAND=my-codex-wrapper (defaults to "codex")
+# CCGRAM_GEMINI_COMMAND=my-gemini-wrapper (defaults to "gemini")
+#
+# Claude config directory (optional, defaults to ~/.claude)
+# For Claude wrappers (ce, cc-mirror, zai) that use a different config location.
+# Affects hook install, command discovery, and session monitoring.
+# CLAUDE_CONFIG_DIR=~/.claude-custom
+
+# Show hidden (dot) directories in the directory browser (optional, defaults to false)
+# CCGRAM_SHOW_HIDDEN_DIRS=false

ccgram-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+      - name: Lint
+        run: uv run ruff check src/ tests/
+      - name: Type check
+        run: uv run pyright src/ccgram/
+      - name: Dependency check
+        run: uv run deptry src
+      - name: Test
+        run: uv run pytest --tb=short -q

ccgram-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+on:
+  push:
+    tags:
+      - v*
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+      - run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+  update-homebrew:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+      - name: Extract version
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - name: Generate formula
+        run: uv run scripts/generate_homebrew_formula.py "${{ steps.version.outputs.VERSION }}" > ccgram.rb
+      - name: Push to homebrew-tap
+        env:
+          GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          git clone "https://x-access-token:${GITHUB_TOKEN}@github.com/alexei-led/homebrew-tap.git" tap
+          cp ccgram.rb tap/Formula/ccgram.rb
+          cd tap
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/ccgram.rb
+          git commit -m "ccgram ${{ steps.version.outputs.VERSION }}"
+          git push
+  github-release:
+    needs:
+      - publish
+      - update-homebrew
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          body: |
+            Automated release for `${{ github.ref_name }}`.
+            Includes published PyPI package and Homebrew formula updates.

ccgram-2.0.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+*.egg
+
+# Build & Distribution
+build/
+dist/
+sdist/
+wheels/
+src/ccgram/_version.py
+
+# Virtual Environments
+.venv/
+.env
+
+# Testing & Coverage
+.hypothesis/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+coverage.json
+
+# Type Checking & Linting
+.mypy_cache/
+.ruff_cache/
+
+# Go module cache (external)
+pkg/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Claude Code (keep .claude/ tracked)
+.claude/settings.local.json
+
+# Spec (keep .spec/ tracked)
+
+# ai artificats to skip
+.brainstorming/
+
+
+# ralphex progress logs
+progress*.txt
+
+# Dev run lock
+.ccgram-dev-run.lock.d/

ccgram-2.0.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# 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]
+
+## [2.0.0] - 2026-03-16
+
+### Changed
+
+- **BREAKING**: Renamed project from `ccbot` to `ccgram` (CCGram)
+- **BREAKING**: CLI command renamed from `ccbot` to `ccgram`
+- **BREAKING**: Config directory changed from `~/.ccbot/` to `~/.ccgram/`
+- **BREAKING**: Environment variables renamed from `CCBOT_*` to `CCGRAM_*`
+- Hook command changed from `ccbot hook` to `ccgram hook`
+- PyPI package name changed from `ccbot` to `ccgram`
+- Default tmux session name changed from `ccbot` to `ccgram`
+
+### Migration
+
+- Old `CCBOT_*` environment variables still work as fallback with deprecation warnings
+- `ccgram hook --install` detects and replaces legacy `ccbot hook` entries
+- `ccgram hook --uninstall` removes both old and new hook entries
+- Session map keys with `ccbot:` prefix are auto-migrated on load
+- If `~/.ccgram/` doesn't exist but `~/.ccbot/` does, a migration hint is logged
+
+## [1.0.0] - 2026-02-22
+
+### Added
+
+- Multi-provider support: Claude Code, OpenAI Codex CLI, and Google Gemini CLI as agent backends
+- Per-topic provider selection via directory browser (Claude default, Codex, Gemini)
+- Auto-detection of provider from externally created tmux windows
+- Provider-aware recovery UI (Fresh/Continue/Resume adapt to each provider's capabilities)
+- Gemini CLI terminal status detection via pane title and interactive UI patterns
+- Codex and Gemini transcript parsing with provider-specific formats
+- Provider capability matrix gating UX features per-window
+
+### Fixed
+
+- Codex resume syntax corrected to `resume <id>` subcommand (was `exec resume`)
+- Gemini resume accepts index numbers and "latest" (not just UUIDs)
+- Both Codex and Gemini now correctly support Continue (resume last session)
+
+## [0.2.11] - 2026-02-17
+
+### Fixed
+
+- Preserved window display names when the SessionStart hook map is stale, preventing topic/session labels from regressing during state resolution
+
+## [0.2.10] - 2026-02-17
+
+### Added
+
+- Directory favorites sidebar plus starred MRU controls for faster session bootstrapping
+- File handler uploads that forward captions to Claude Code alongside the document payload
+- Notification toggle to pause/resume Telegram alerts per topic
+
+### Changed
+
+- Directory browser now shows status keyboard tweaks for clarity when picking working directories
+- Status keyboard refreshed to better expose screenshot shortcuts and live indicators
+
+### Fixed
+
+- Session polling stability improvements that cover status, screenshot, and message filtering edge cases
+
+## [0.2.0] - 2026-02-12
+
+Major rewrite as an independent fork of [six-ddc/ccbot](https://github.com/six-ddc/ccbot).
+
+### Added
+
+- Topic-based sessions: 1 topic = 1 tmux window = 1 Claude session
+- Interactive UI for AskUserQuestion, ExitPlanMode, and Permission prompts
+- Sessions dashboard with per-session status and kill buttons
+- Message history with paginated browsing (newest first)
+- Auto-discovery of Claude Code skills and custom commands in Telegram menu
+- Hook-based session tracking (SessionStart hook writes session_map.json)
+- Per-user message queue with FIFO ordering and message merging
+- Rate limiting (1.1s minimum interval per user)
+- Multi-instance support via CCBOT_GROUP_ID and CCBOT_INSTANCE_NAME
+- Auto-topic creation for manually created tmux windows (including cold-start)
+- Fresh/Continue/Resume recovery flows for dead sessions
+- /resume command to browse and resume past sessions
+- Directory browser for new topic session creation
+- MarkdownV2 output with automatic plain text fallback
+- Terminal screenshot rendering (ANSI color support)
+- Status line polling with spinner and working text
+- Expandable quote formatting for thinking content
+- Persistent state (thread bindings, read offsets survive restarts)
+- Topic emoji status updates reflecting session state
+- Configurable config directory via CCBOT_DIR env var
+
+### Changed
+
+- Internal routing keyed by tmux window ID instead of window name
+- Python 3.14 required (up from 3.12)
+- Replaced broad exception handlers with specific types
+- Normalized variable naming (full names instead of short aliases)
+- Enabled C901, PLR, N ruff quality gate rules
+
+### Removed
+
+- Non-topic mode (active_sessions, /list, General topic routing)
+- Message truncation at parse layer (splitting only at send layer)
+
+## [0.1.0] - 2026-02-07
+
+Initial release by [six-ddc](https://github.com/six-ddc).
+
+[Unreleased]: https://github.com/alexei-led/ccgram/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/alexei-led/ccgram/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/alexei-led/ccbot/compare/v0.2.11...v1.0.0
+[0.2.11]: https://github.com/alexei-led/ccbot/compare/v0.2.10...v0.2.11
+[0.2.10]: https://github.com/alexei-led/ccbot/compare/v0.2.0...v0.2.10
+[0.2.0]: https://github.com/alexei-led/ccbot/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/alexei-led/ccbot/releases/tag/v0.1.0