ccpoke 1.6.15 → 1.6.17

package/README.en.md

@@ -2,15 +2,15 @@
 
 [Tiếng Việt](./README.md) · [中文](./README.zh.md)
 
-> Get Telegram notifications when your AI agent (Claude Code, Cursor, ...) completes a response — with git diff, processing time, and result summary.
+> Two-way interaction with Claude Code, Codex CLI, Cursor CLI and more via Telegram — code anytime, anywhere.
 
 ---
 
 ## Problem
 
-You're using Claude Code or Cursor on your computer. You step away with your phone but have no idea if the AI agent is done yet or what files it changed.
+You're using Claude Code, Codex CLI or Cursor CLI on your computer. You step away with your phone but have no idea if the AI agent is done yet, and you want to send more prompts without opening your laptop.
 
-**ccpoke** is a lightweight bridge between AI agents and Telegram — when any agent finishes, you get a notification right on your phone.
+**ccpoke** is a two-way bridge between AI agents and Telegram — receive notifications, send prompts, answer questions, manage multiple sessions — all from your phone.
 
 ```
 AI agent completes response
@@ -24,31 +24,28 @@ AI agent completes response
 
 ## Supported Agents
 
-| | Claude Code | Cursor |
-|---|---|---|
-| Telegram notifications | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows |
-| 2-way chat (Telegram ↔ Agent) | ✅ macOS · Linux | ❌ |
+| | Claude Code | Codex CLI | Cursor CLI |
+|---|---|---|---|
+| Telegram notifications | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows |
+| 2-way chat (Telegram ↔ Agent) | ✅ macOS · Linux | ✅ macOS · Linux | ✅ macOS · Linux |
 
 Adding new agents is easy via the plugin architecture — contributions welcome!
 
 ## Features
 
-- 🤖 **Multi-agent** — supports Claude Code, Cursor and more
-- 🔔 **Auto notification** — AI agent finishes → Telegram notifies you instantly
-- 📂 **Git diff included** — see changed files without opening your computer
-- ⏱ **Processing time** — know how long the agent took
-- 📝 **Response summary** — quick glance at what the agent replied
-- 🔐 **User whitelist** — only authorized users can use the bot
-- 📄 **Auto-split messages** — long responses are automatically paginated `[1/N]`
+- 🔔 **Push notification** — AI agent done → notification pushed instantly, no polling, no delay
+- 💬 **Two-way interaction** — chat with your AI agent from Telegram, view sessions, send prompts, answer questions, approve permissions
+- 🔀 **Multi-session** — manage multiple AI agent sessions simultaneously, switch quickly, parallel monitoring
 
 ## Requirements
 
 - **Node.js** ≥ 20
+- **tmux** — required for two-way interaction (auto-installed on first run)
 - **Telegram Bot Token** — create from [@BotFather](https://t.me/BotFather)
 
 ## Getting Started
 
-### Option 1: npx (recommended — zero install)
+### Option 1: npx (zero install)
 
 ```bash
 npx -y ccpoke
@@ -56,22 +53,13 @@ npx -y ccpoke
 
 First run → auto setup → start bot. One command, that's it.
 
-### Option 2: Global install (daily use, faster startup)
+### Option 2: Global install (recommended — faster startup)
 
 ```bash
 npm i -g ccpoke
 ccpoke
 ```
 
-### Option 3: Clone repo (for development)
-
-```bash
-git clone https://github.com/kaida-palooza/ccpoke.git
-cd ccpoke
-pnpm install
-pnpm dev
-```
-
 The setup wizard will guide you step by step:
 
 ```
@@ -100,32 +88,17 @@ The setup wizard will guide you step by step:
 ◆  ✓ Connected! User ID: 123456789
 │
 ◇  Select AI agents (space to toggle)
-│  Claude Code, Cursor
+│  Claude Code, Codex CLI, Cursor CLI
 │
 ◆  Config saved
 ◆  Hook installed for Claude Code
-◆  Hook installed for Cursor
+◆  Hook installed for Codex CLI
+◆  Hook installed for Cursor CLI
 ◆  Chat ID registered
 │
 └  🎉 Setup complete!
 ```
 
-<details>
-<summary>Manual setup (without wizard)</summary>
-
-Create `~/.ccpoke/config.json`:
-
-```json
-{
-  "telegram_bot_token": "123456:ABC-xxx",
-  "user_id": 123456789,
-  "hook_port": 9377
-}
-```
-
-Then run `ccpoke setup` to install the hook and register your chat ID.
-
-</details>
 
 ## Usage
 
@@ -138,19 +111,58 @@ npx -y ccpoke
 # Or global install
 ccpoke
 
-# Or local dev
-pnpm dev
 ```
 
-Once running, use Claude Code / Cursor as usual → notifications will arrive on Telegram.
+Once running, use Claude Code / Codex CLI / Cursor CLI as usual → notifications will arrive on Telegram.
+
+### View multi-agent sessions
+
+When running multiple agents in parallel, ccpoke creates a tmux session to manage them. To view:
+
+```bash
+# Regular terminal
+tmux attach
+
+# iTerm2 (native integration)
+tmux -CC attach
+```
+
+### Register Projects
+
+Register projects to create new agent sessions directly from Telegram — no need to open your computer.
+
+**Step 1: Add a project via CLI**
+
+```bash
+ccpoke project
+```
+
+```
+┌  📂 Manage Projects
+│
+◇  Select action
+│  ➕ Add new project
+│
+◇  Project path
+│  /path/to/your/project
+│
+◇  Project name
+│  my-project
+│
+└  ✅ Added: my-project → /path/to/your/project
+```
+
+**Step 2: Create agent sessions from Telegram**
+
+Send `/projects` on Telegram → pick a project → choose agent (Claude Code / Codex CLI / Cursor CLI) → agent starts in a new tmux pane.
 
 ### Telegram Commands
 
-| Command   | Description                                         |
-|-----------|-----------------------------------------------------|
-| `/start`  | Re-register chat (auto during setup, rarely needed) |
-| `/ping`   | Check if bot is alive                               |
-| `/status` | View bot status                                     |
+| Command     | Description                                         |
+|-------------|-----------------------------------------------------|
+| `/start`    | Re-register chat (auto during setup, rarely needed) |
+| `/sessions` | View active AI agent sessions                       |
+| `/projects` | View project list and start new sessions            |
 
 ### Sample Notification
 
@@ -161,11 +173,6 @@ Once running, use Claude Code / Cursor as usual → notifications will arrive on
 Fixed authentication bug in login.go. Main changes:
 - Fix missing error check at line 42
 - Add input validation...
-
-📂 Changes:
-✏️ src/login.go
-➕ src/validator.go
-❌ src/old_auth.go
 ```
 
 ## Uninstall
@@ -178,7 +185,8 @@ ccpoke uninstall
 ┌  🗑️  Uninstalling ccpoke
 │
 ◆  Hook removed from Claude Code
-◆  Hook removed from Cursor
+◆  Hook removed from Codex CLI
+◆  Hook removed from Cursor CLI
 ◆  Removed ~/.ccpoke/ (config, state, hooks)
 │
 └  ccpoke uninstalled

package/README.md

@@ -1,78 +1,66 @@
-# 🐾 ccpoke — AI Agent Notification Bridge
+# 🐾 ccpoke — Cầu nối thông báo AI Agent
 
 [English](./README.en.md) · [中文](./README.zh.md)
 
-> Nhận thông báo Telegram khi AI agent (Claude Code, Cursor, ...) hoàn thành response — kèm git diff, thời gian xử lý, và tóm tắt kết quả.
+> Tương tác 2 chiều với Claude Code, Codex CLI, Cursor CLI và nhiều AI agent khác qua Telegram — lập trình mọi lúc mọi nơi.
 
 ---
 
 ## Vấn đề giải quyết
 
-Bạn đang dùng Claude Code hoặc Cursor trên máy tính. Ra ngoài cầm điện thoại nhưng không biết AI agent đã xong chưa, thay đổi file nào.
+Bạn đang dùng Claude Code, Codex CLI hoặc Cursor CLI trên máy tính. Ra ngoài cầm điện thoại nhưng không biết AI agent đã xong chưa, muốn gửi thêm yêu cầu mà không cần mở laptop.
 
-**ccpoke** là cầu nối nhẹ giữa AI agents và Telegram — khi agent xong việc, bạn nhận notification ngay trên điện thoại.
+**ccpoke** là cầu nối 2 chiều giữa AI agent và Telegram — nhận thông báo, gửi yêu cầu, trả lời câu hỏi, quản lý nhiều phiên làm việc — tất cả từ điện thoại.
 
 ```
-AI agent xong response
+AI agent hoàn thành phản hồi
         ↓
-  Stop Hook trigger
+  Stop Hook kích hoạt
         ↓
-  ccpoke nhận event
+  ccpoke nhận sự kiện
         ↓
-  Telegram notification 📱
+  Thông báo Telegram 📱
 ```
 
-## Hỗ trợ Agent
+## Agent hỗ trợ
 
-| | Claude Code | Cursor |
-|---|---|---|
-| Notification Telegram | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows |
-| Chat 2 chiều (Telegram ↔ Agent) | ✅ macOS · Linux | ❌ |
+| | Claude Code | Codex CLI | Cursor CLI |
+|---|---|---|---|
+| Thông báo Telegram | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows | ✅ macOS · Linux · Windows |
+| Trò chuyện 2 chiều (Telegram ↔ Agent) | ✅ macOS · Linux | ✅ macOS · Linux | ✅ macOS · Linux |
 
-Thêm agent mới qua kiến trúc plugin — contributions welcome!
+Thêm agent mới qua kiến trúc plugin — hoan nghênh đóng góp!
 
 ## Tính năng
 
-- 🤖 **Multi-agent** — hỗ trợ Claude Code, Cursor và mở rộng thêm
-- 🔔 **Notification tự động** — AI agent xong → Telegram nhận tin ngay
-- 📂 **Git diff kèm theo** — biết file nào thay đổi mà không cần mở máy tính
-- ⏱ **Thời gian xử lý** — biết agent chạy bao lâu
-- 📝 **Tóm tắt response** — xem nhanh agent trả lời gì
-- 🔐 **Whitelist user** — chỉ user được phép mới dùng được bot
-- 📄 **Auto-split message** — response dài tự động chia page `[1/N]`
+- 🔔 **Thông báo đẩy** — AI agent xong → Telegram nhận tin ngay, không cần kiểm tra liên tục, không trễ
+- 💬 **Tương tác 2 chiều** — trò chuyện với AI agent từ Telegram, xem phiên làm việc, gửi yêu cầu, trả lời câu hỏi, phê duyệt quyền
+- 🔀 **Đa phiên** — quản lý nhiều phiên AI agent cùng lúc, chuyển đổi nhanh, giám sát song song
 
 ## Yêu cầu
 
 - **Node.js** ≥ 20
+- **tmux** — cần cho tương tác 2 chiều (tự cài khi chạy lần đầu)
 - **Telegram Bot Token** — tạo từ [@BotFather](https://t.me/BotFather)
 
 ## Bắt đầu
 
-### Cách 1: npx (khuyến nghị — zero install)
+### Cách 1: npx (không cần cài đặt)
 
 ```bash
 npx -y ccpoke
 ```
 
-Lần đầu chạy → tự động setup → start bot. Một lệnh duy nhất.
+Lần đầu chạy → tự động thiết lập → khởi động bot. Một lệnh duy nhất.
 
-### Cách 2: Global install (dùng hàng ngày, khởi động nhanh hơn)
+### Cách 2: Cài đặt toàn cục (khuyến nghị — khởi động nhanh hơn)
 
 ```bash
 npm i -g ccpoke
 ccpoke
 ```
 
-### Cách 3: Clone repo (cho development)
-
-```bash
-git clone https://github.com/kaida-palooza/ccpoke.git
-cd ccpoke
-pnpm install
-pnpm dev
-```
-
-Setup wizard sẽ hướng dẫn từng bước:
+Trình hướng dẫn cài đặt sẽ dẫn bạn từng bước:
 
 ```
 ┌  🤖 ccpoke setup
@@ -100,72 +88,91 @@ Setup wizard sẽ hướng dẫn từng bước:
 ◆  ✓ Connected! User ID: 123456789
 │
 ◇  Chọn AI agents (ấn cách để chọn)
-│  Claude Code, Cursor
+│  Claude Code, Codex CLI, Cursor CLI
 │
 ◆  Config saved
 ◆  Hook installed for Claude Code
-◆  Hook installed for Cursor
+◆  Hook installed for Codex CLI
+◆  Hook installed for Cursor CLI
 ◆  Chat ID registered
 │
 └  🎉 Setup complete!
 ```
 
-<details>
-<summary>Thiết lập thủ công (không dùng wizard)</summary>
-
-Tạo file `~/.ccpoke/config.json`:
-
-```json
-{
-  "telegram_bot_token": "123456:ABC-xxx",
-  "user_id": 123456789,
-  "hook_port": 9377
-}
-```
-
-Sau đó chạy `ccpoke setup` để cài hook và đăng ký chat ID.
-
-</details>
 
 ## Sử dụng
 
 ### Khởi động bot
 
 ```bash
-# npx (zero install)
+# npx (không cần cài đặt)
 npx -y ccpoke
 
-# Hoặc global install
+# Hoặc cài đặt toàn cục
 ccpoke
 
-# Hoặc local dev
-pnpm dev
 ```
 
-Bot chạy xong → dùng Claude Code / Cursor bình thường → notification tự đến Telegram.
+Bot chạy xong → dùng Claude Code / Codex CLI / Cursor CLI bình thường → thông báo tự đến Telegram.
 
-### Telegram Commands
+### Xem phiên làm việc đa agent
 
-| Command   | Chức năng                                       |
-|-----------|---------------------------------------------------|
-| `/start`  | Đăng ký lại chat (tự động khi setup, ít khi cần) |
-| `/ping`   | Kiểm tra bot còn sống không                      |
-| `/status` | Xem trạng thái bot                               |
+Khi chạy nhiều agent song song, ccpoke tạo phiên tmux để quản lý. Để xem:
 
-### Notification mẫu
+```bash
+# Cửa sổ dòng lệnh thường
+tmux attach
 
+# iTerm2 (tích hợp gốc)
+tmux -CC attach
 ```
-🤖 Claude Code Response
-📂 my-project | ⏱ 45s
 
-Đã sửa bug authentication trong login.go. Thay đổi chính:
-- Fix missing error check ở dòng 42
-- Thêm input validation...
+### Đăng ký dự án
+
+Đăng ký dự án để tạo phiên agent mới trực tiếp từ Telegram — không cần mở máy tính.
+
+**Bước 1: Thêm dự án qua dòng lệnh**
+
+```bash
+ccpoke project
+```
+
+```
+┌  📂 Quản lý dự án
+│
+◇  Chọn thao tác
+│  ➕ Thêm dự án mới
+│
+◇  Đường dẫn dự án
+│  /path/to/your/project
+│
+◇  Tên dự án
+│  my-project
+│
+└  ✅ Đã thêm: my-project → /path/to/your/project
+```
+
+**Bước 2: Tạo phiên agent từ Telegram**
+
+Gửi `/projects` trên Telegram → chọn dự án → chọn agent (Claude Code / Codex CLI / Cursor CLI) → agent khởi chạy trong ô tmux mới.
+
+### Lệnh Telegram
+
+| Lệnh        | Chức năng                                                   |
+|-------------|-------------------------------------------------------------|
+| `/start`    | Đăng ký lại cuộc trò chuyện (tự động khi cài đặt, ít cần)  |
+| `/sessions` | Xem danh sách phiên AI agent đang hoạt động                 |
+| `/projects` | Xem danh sách dự án và mở phiên mới                         |
+
+### Thông báo mẫu
+
+```
+🤖 Phản hồi Claude Code
+📂 my-project | ⏱ 45 giây
 
-📂 Changes:
-✏️ src/login.go
-➕ src/validator.go
-❌ src/old_auth.go
+Đã sửa lỗi xác thực trong login.go. Thay đổi chính:
+- Sửa thiếu kiểm tra lỗi ở dòng 42
+- Thêm kiểm tra đầu vào...
 ```
 
 ## Gỡ cài đặt
@@ -178,17 +185,18 @@ ccpoke uninstall
 ┌  🗑️  Uninstalling ccpoke
 │
 ◆  Hook removed from Claude Code
-◆  Hook removed from Cursor
+◆  Hook removed from Codex CLI
+◆  Hook removed from Cursor CLI
 ◆  Removed ~/.ccpoke/ (config, state, hooks)
 │
 └  ccpoke uninstalled
 ```
 
-## License
+## Giấy phép
 
 MIT
 
-## Contributors
+## Người đóng góp
 <a href="https://github.com/lethai2597">
   <img src="https://github.com/lethai2597.png" width="50" />
 </a>