@fonz/tgcc 0.5.5 → 0.5.6

package/README.md

@@ -1,84 +1,109 @@
 # @fonz/tgcc
 
-**Telegram ↔ Claude Code bridge** — run Claude Code sessions from Telegram with full streaming, inline editing, and multi-agent support.
+**Telegram ↔ Claude Code bridge** — run Claude Code sessions from Telegram with full streaming, session management, and multi-agent support.
 
-## What is TGCC?
+## Quick Start
 
-TGCC bridges the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) to Telegram, turning any Telegram bot into a full Claude Code client.
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
 
-- **Streaming output** — CC responses stream into a single Telegram message that updates in place (no message spam)
-- **Multi-agent** — run one bot per project/repo, each with its own config, model, and permissions
-- **Session management** — resume, switch, and list sessions with inline keyboard buttons
-- **Permission relay** — CC permission prompts appear as inline buttons (Allow / Deny / Allow All)
-- **Thinking display** — thinking content shown as expandable blockquotes (collapsible in Telegram)
-- **Sub-agent threading** — sub-agent tool calls appear as threaded replies to the main message
-- **Staleness detection** — detects when a session was modified externally (e.g. from VS Code) and reconnects
-- **Usage stats** — per-turn token counts and cost shown as a subtle footer
-- **CLI tool** — send messages from your terminal, manage agents and repos
-- **HTML formatting** — code blocks with syntax highlighting, bold, italic, links
+npm install -g @fonz/tgcc
+tgcc init        # walks you through setup
+tgcc run         # test in foreground
+tgcc install     # install as a user service
+```
 
-## Architecture
+## What it does
 
-```
-User ──► Telegram ──► TGCC ──► Claude Code CLI (stream-json)
-                      │
-              config.json (agents, repos, permissions)
-              state.json (sessions, models, per-user overrides)
-```
+TGCC bridges the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) to Telegram. Each Telegram bot becomes a full Claude Code client.
 
-TGCC runs as a persistent service. Each configured agent connects to its own Telegram bot. When a user sends a message, TGCC spawns (or reuses) a Claude Code process using the `stream-json` protocol, forwards the message, and streams the response back to Telegram with edit-in-place updates.
+- **Streaming** — responses stream into a single message that updates in place
+- **Sessions** — resume, switch, and list sessions. Roam between Telegram and the CC CLI on the same session
+- **Multi-agent** — one bot per project, each with its own config and permissions
+- **Permission relay** — CC permission prompts appear as inline buttons
+- **MCP tools** — CC can send files, images, and voice back via built-in MCP server
+- **Markdown → Telegram HTML** — code blocks, bold, italic, links, tables, all rendered properly
+- **Usage stats** — per-turn token counts and cost
 
-**Key design decisions:**
-- **Config-driven** — everything in `~/.tgcc/config.json`, hot-reloaded on changes
-- **Unix sockets** — CLI communicates with the running service via per-agent sockets in `/tmp/tgcc/ctl/`
-- **MCP bridge** — CC can send files, images, and voice back to the user via a built-in MCP server
-- **State-aware hang detection** — distinguishes between API waits, tool execution (checks child processes), and real hangs
+## Service Management
 
-## Quick Start
+```bash
+tgcc install     # Install & start as a user service (systemd/launchd)
+tgcc start       # Start the service
+tgcc stop        # Stop the service
+tgcc restart     # Restart the service
+tgcc uninstall   # Remove the service
+tgcc logs        # Tail service logs
+tgcc run         # Run in the foreground (no service)
+```
+
+## CLI Commands
 
 ```bash
-# Install
-npm install -g @fonz/tgcc
+# Setup
+tgcc init                              # Interactive setup
 
-# Create a Telegram bot via @BotFather, get the token
+# Agents
+tgcc agent add mybot --bot-token <token>
+tgcc agent remove mybot
+tgcc agent rename mybot newname
+tgcc agent list
 
-# Register an agent
-tgcc agent add mybot --bot-token 123456:ABC-DEF --repo ~/myproject
+# Repos
+tgcc repo add .                        # Add current directory
+tgcc repo add . --name=myrepo          # Add with explicit name
+tgcc repo add ~/code/backend           # Add a path
+tgcc repo remove --name=myrepo
+tgcc repo assign --agent=mybot --name=myrepo
+tgcc repo clear --agent=mybot
+tgcc repo list
 
-# Start the service
-tgcc
+# Messaging (while service is running)
+tgcc message "fix the login bug"
+tgcc message "deploy" --agent=mybot --session=abc123
+tgcc status
+tgcc status --agent=mybot
 
-# Send your bot a message on Telegram!
+# Permissions
+tgcc permissions set mybot dangerously-skip
 ```
 
+## Telegram Commands
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Welcome message |
+| `/new` | Start a fresh session |
+| `/sessions` | List recent sessions with resume buttons |
+| `/resume <id>` | Resume a session by ID |
+| `/repo` | Switch repo with inline buttons |
+| `/model <name>` | Switch model |
+| `/permissions` | Set permission mode |
+| `/status` | Process state, model, repo, cost |
+| `/cancel` | Abort current CC turn |
+| `/catchup` | Summarize external CC activity |
+
 ## Configuration
 
-Config lives at `~/.tgcc/config.json`. TGCC creates it automatically when you run `tgcc agent add`.
+Config lives at `~/.tgcc/config.json` (created by `tgcc init`).
 
 ```jsonc
 {
   "global": {
-    "ccBinaryPath": "claude",     // Path to claude CLI binary
-    "logLevel": "info",
-    "mediaDir": "~/.tgcc/media",
-    "socketDir": "/tmp/tgcc",
-    "stateFile": "~/.tgcc/state.json"
+    "ccBinaryPath": "claude",
+    "logLevel": "info"
   },
   "repos": {
-    "myproject": "/home/user/myproject",
-    "backend": "/home/user/backend"
+    "myproject": "/home/user/myproject"
   },
   "agents": {
     "mybot": {
       "botToken": "123456:ABC-DEF...",
-      "allowedUsers": ["123456789"],  // Telegram user IDs
+      "allowedUsers": [],
       "defaults": {
-        "model": "claude-sonnet-4-20250514",
         "repo": "myproject",
-        "permissionMode": "acceptEdits",
-        "maxTurns": 30,
-        "idleTimeoutMs": 600000,
-        "hangTimeoutMs": 300000
+        "permissionMode": "bypassPermissions"
       }
     }
   }
@@ -89,177 +114,23 @@ Config lives at `~/.tgcc/config.json`. TGCC creates it automatically when you ru
 
 | Mode | Description |
 |------|-------------|
-| `dangerously-skip` | Skip all permission prompts (⚠️ use with care) |
-| `acceptEdits` | Auto-accept file edits, prompt for everything else |
-| `default` | CC's built-in permission flow — prompts appear as inline buttons in Telegram |
-| `plan` | Plan-only mode, no tool execution |
-
-### Repo Registry
-
-Repos are named shortcuts for project paths. Register them once, use everywhere:
-
-```bash
-tgcc repo add myproject ~/code/myproject
-tgcc repo add backend ~/code/backend
-tgcc repo assign mybot myproject    # Set as agent's default
-```
-
-In Telegram, `/repo` shows an inline keyboard to switch repos on the fly.
-
-## Telegram Commands
-
-| Command | Description |
-|---------|-------------|
-| `/start` | Welcome message, register bot commands |
-| `/help` | List all commands |
-| `/new` | Start a fresh session |
-| `/sessions` | List recent sessions with Resume/Delete buttons |
-| `/resume <id>` | Resume a session by ID |
-| `/session` | Current session info |
-| `/status` | Process state, model, repo, uptime, cost |
-| `/cost` | Show session cost |
-| `/model <name>` | Switch model (takes effect on next spawn) |
-| `/permissions` | Set permission mode with inline buttons |
-| `/repo` | Switch repo with inline buttons |
-| `/cancel` | Abort current CC turn (sends SIGINT) |
-| `/catchup` | Summarize external CC activity on the same repo |
-| `/ping` | Liveness check |
-
-### Examples
+| `dangerouslySkipPermissions` | Skip all prompts |
+| `acceptEdits` | Auto-accept edits, prompt for commands |
+| `default` | Full permission flow via inline buttons |
+| `plan` | Plan-only, no tool execution |
 
-**Start a conversation:**
-> You: Fix the auth middleware to handle expired tokens
-
-> Bot:
-> <blockquote expandable>💭 Thinking<br>Looking at the auth middleware...</blockquote>
->
-> I've updated `src/middleware/auth.ts` to handle expired tokens gracefully...
->
-> *↩️ 1.2k in · 450 out · $0.0034*
-
-**Permission prompt (when not using bypass mode):**
-> 🔐 CC wants to use `Write`
-> ```{"file_path": "src/auth.ts", ...}```
->
-> `[✅ Allow]` `[❌ Deny]` `[✅ Allow All]`
-
-**Switch repos:**
-> `/repo`
->
-> Current repo: `~/myproject`
->
-> `[myproject]`
-> `[backend]`
-> `[➕ Add]` `[❓ Help]`
-
-## CLI Commands
-
-The `tgcc` CLI communicates with the running service via Unix sockets.
-
-```bash
-# Start the service (foreground)
-tgcc
-
-# Send a message to a running agent
-tgcc message "fix the login bug" --agent mybot
-tgcc msg "deploy to staging" --agent mybot --session abc123
-
-# Check status
-tgcc status
-tgcc status --agent mybot
-
-# Agent management
-tgcc agent add mybot --bot-token <token> --repo ~/project
-tgcc agent remove mybot
-tgcc agent rename mybot newname
-tgcc agent list
-tgcc agent repo mybot backend    # Set default repo
-
-# Repo management
-tgcc repo add myproject ~/code/myproject
-tgcc repo remove myproject
-tgcc repo assign mybot myproject
-tgcc repo clear mybot
-tgcc repo list
+## Architecture
 
-# Permissions
-tgcc permissions set mybot dangerously-skip
 ```
-
-## Features in Detail
-
-### Streaming with Edit-in-Place
-
-CC output streams into a single Telegram message. As CC produces text, TGCC edits the same message with the accumulated content (throttled to ~1 edit/second to respect Telegram rate limits). When the message gets too long (~4000 chars), it splits into a new message.
-
-### HTML Formatting
-
-All output uses Telegram's HTML parse mode:
-- Code blocks → `<pre><code class="language-python">...</code></pre>`
-- Inline code → `<code>...</code>`
-- Bold, italic, strikethrough, links — all converted from CC's markdown
-
-### Thinking in Expandable Blockquotes
-
-When CC thinks, the thinking content is captured and displayed as a collapsible blockquote:
-
-```html
-<blockquote expandable>💭 Thinking
-Analyzing the auth middleware pattern...
-</blockquote>
+User ──► Telegram ──► TGCC ──► Claude Code CLI (stream-json)
+                        │
+                  config.json ─── agents, repos, permissions
+                  state.json ─── sessions, per-user overrides
 ```
 
-Users can tap to expand and see what CC was thinking.
-
-### Sub-Agent Activity
-
-When CC spawns sub-agents (via `dispatch_agent`, `Task`, etc.), TGCC sends a threaded reply:
-
-> 🔄 Sub-agent spawned: `dispatch_agent`
-> *(updates with input preview, then ✅ on completion)*
-
-### Smart Hang Detection
+TGCC runs as a persistent service. When a user sends a message, it spawns (or resumes) a Claude Code process using the `stream-json` protocol, streams the response back with edit-in-place updates.
 
-TGCC tracks CC's activity state and checks for active child processes before declaring a hang:
-- **Tool executing** with active children → extend timer
-- **Waiting for API** → extend timer (API can be slow)
-- **No activity** for hangTimeoutMs → truly hung, kill and notify
-
-### Session Staleness Detection
-
-If you use the same CC session from both Telegram and VS Code, TGCC detects the modification when you next message from Telegram. It shows a summary of what happened externally and reconnects cleanly.
-
-## How It Works with Claude Code
-
-TGCC uses CC's `stream-json` protocol:
-
-1. **Spawn** — `claude -p --input-format stream-json --output-format stream-json --verbose --include-partial-messages`
-2. **Initialize** — Send `control_request` with `subtype: "initialize"` (SDK handshake)
-3. **Messages** — Write JSON user messages to stdin, parse NDJSON events from stdout
-4. **Streaming** — `stream_event` wraps inner events: `message_start`, `content_block_start`, `content_block_delta` (text, thinking, image), `content_block_stop`, `message_stop`
-5. **Permissions** — CC sends `control_request` with `subtype: "can_use_tool"`, TGCC relays to Telegram and sends `control_response` back
-6. **Sessions** — `--resume <id>` reconnects to an existing session, same JSONL files as the VS Code extension
-7. **Results** — `result` event with cost, token usage, success/error status
-
-Sessions are fully interoperable with the VS Code Claude Code extension — the same `~/.claude/projects/` JSONL files are used by both.
-
-## Project Structure
-
-```
-src/
-├── cli.ts           # CLI tool (tgcc command)
-├── bridge.ts        # Core orchestrator (TG ↔ CC)
-├── cc-process.ts    # CC process lifecycle management
-├── cc-protocol.ts   # CC stream-json protocol types & parser
-├── streaming.ts     # Stream accumulator (edit-in-place, splitting)
-├── telegram.ts      # Telegram bot (grammY)
-├── config.ts        # Config loading, validation, hot-reload
-├── session.ts       # Session store, staleness, catchup
-├── ctl-server.ts    # Unix socket server for CLI communication
-├── mcp-bridge.ts    # MCP server for CC → TG file/image/voice
-├── mcp-server.ts    # MCP tool definitions
-└── index.ts         # Entry point
-```
+Sessions are fully interoperable with the VS Code Claude Code extension — same `~/.claude/projects/` JSONL files.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonz/tgcc",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "Telegram ↔ Claude Code CLI bridge",
   "type": "module",
   "main": "dist/index.js",