Add CCWeb: React web gateway to Claude Code sessions

.claude/rules/architecture.md

@@ -30,7 +30,7 @@
 │  SessionMonitor         │    │  TmuxManager (tmux_manager.py)  │
 │  (session_monitor.py)   │    │  - list/find/create/kill windows│
 │  - Poll JSONL every 2s  │    │  - send_keys to pane            │
-│  - Detect mtime changes │    │  - capture_pane for screenshot  │
+│  - Detect size changes  │    │  - capture_pane for screenshot  │
 │  - Parse new lines      │    └──────────────┬─────────────────┘
 │  - Track pending tools  │                   │
 │    across poll cycles   │                   │

.claude/rules/message-handling.md

@@ -32,7 +32,7 @@ Per-user message queues + worker pattern for all send tasks:
 
 ## Performance Optimizations
 
-**mtime cache**: The monitoring loop maintains an in-memory file mtime cache, skipping reads for unchanged files.
+**File size fast path**: The monitoring loop compares file size against the last byte offset, 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.
 

.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cmd.exe:*)",
+      "Bash(pip show:*)",
+      "Bash(python3:*)",
+      "Bash(\"/c/Users/krisd/AppData/Local/Programs/Python/Python314/python.exe\":*)",
+      "Bash(uv run:*)",
+      "Bash(~/.local/bin/uv run:*)",
+      "Bash(ls:*)"
+    ]
+  }
+}

ccbot-workshop-setup.md

@@ -0,0 +1,310 @@
+# CCBot Workshop Setup Guide
+
+Complete setup from a fresh Windows machine to running CCBot with Claude Code sessions accessible via Telegram.
+
+---
+
+## Prerequisites
+
+Before you begin, you'll need:
+
+- Windows 10 (version 2004+) or Windows 11
+- A Telegram account
+- A Claude Code subscription (Claude Pro/Team/Enterprise)
+- Your project repositories cloned into `C:\GitHub\`
+
+---
+
+## Part 1: Install WSL and Ubuntu
+
+Open **PowerShell as Administrator** and run:
+
+```powershell
+wsl --install
+```
+
+This installs WSL 2 with Ubuntu. Restart your computer when prompted.
+
+After restart, Ubuntu will open automatically and ask you to create a username and password. Remember these — you'll need the password for `sudo` commands.
+
+Once you're at the Ubuntu prompt, update everything:
+
+```bash
+sudo apt update && sudo apt upgrade -y
+```
+
+---
+
+## Part 2: Install Core Tools
+
+### Node.js (required for Claude Code)
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+Verify:
+
+```bash
+node --version
+npm --version
+```
+
+### Claude Code
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Add npm global bin to your PATH if not already there:
+
+```bash
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Verify Claude Code works:
+
+```bash
+claude --version
+```
+
+### tmux
+
+```bash
+sudo apt install -y tmux
+```
+
+### uv (Python package manager)
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then:
+
+```bash
+source ~/.bashrc
+```
+
+---
+
+## Part 3: Create a Telegram Bot
+
+1. Open Telegram and search for **@BotFather**
+2. Send `/newbot`
+3. Follow the prompts to name your bot
+4. BotFather gives you a **bot token** — save it (looks like `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+### Get your Telegram user ID
+
+1. Search for **@userinfobot** in Telegram
+2. Start a chat with it
+3. It replies with your numeric user ID — save it
+
+### Create a Telegram group
+
+1. Create a new group in Telegram
+2. Name it something like "Workshop Sessions"
+3. Add your bot to the group
+4. Go to group settings → **Topics** → Enable topics (use list format)
+5. Make the bot an **admin** of the group
+
+---
+
+## Part 4: Install CCBot Workshop
+
+```bash
+uv tool install git+https://github.com/JanusMarko/ccbot-workshop.git
+```
+
+Verify it installed:
+
+```bash
+which ccbot
+```
+
+If it's not found, add the path:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+### Configure CCBot
+
+Create the config directory and environment file:
+
+```bash
+mkdir -p ~/.ccbot
+nano ~/.ccbot/.env
+```
+
+Paste the following, replacing the placeholder values with your actual token and user ID:
+
+```
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+ALLOWED_USERS=your_telegram_user_id_here
+TMUX_SESSION_NAME=ccbot
+CLAUDE_COMMAND=claude --dangerously-skip-permissions
+CCBOT_BROWSE_ROOT=/mnt/c/GitHub
+```
+
+Save with `Ctrl+O`, exit with `Ctrl+X`.
+
+The `CCBOT_BROWSE_ROOT` setting ensures the directory browser always starts from your `C:\GitHub\` folder when creating new sessions.
+
+### Install the Claude Code hook
+
+This lets CCBot track which Claude session runs in which tmux window:
+
+```bash
+ccbot hook --install
+```
+
+Or manually add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{ "type": "command", "command": "ccbot hook", "timeout": 5 }]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Part 5: Starting CCBot
+
+### First time startup
+
+```bash
+tmux new -s ccbot
+```
+
+Inside the tmux session:
+
+```bash
+ccbot
+```
+
+You should see log output confirming the bot started, including your allowed users and Claude projects path.
+
+### Detach from tmux
+
+Press `Ctrl+b`, release, then press `d`. CCBot keeps running in the background. You can close the terminal — it stays alive.
+
+### Start a session from Telegram
+
+1. Open your Telegram group
+2. Create a new topic (name it after your project, e.g. "PAIOS")
+3. Send a message in the topic
+4. CCBot shows a directory browser starting from `C:\GitHub\` — tap your project folder
+5. Tap **Select** to confirm
+6. A new tmux window is created with Claude Code running in that directory
+7. Your message is forwarded to Claude Code
+
+### View sessions in the terminal
+
+```bash
+tmux attach -t ccbot
+```
+
+Switch between windows using `Ctrl+b` then the window number (shown in the bottom bar). For example:
+
+- `Ctrl+b` then `1` → ccbot process (don't close this)
+- `Ctrl+b` then `2` → first Claude Code session
+- `Ctrl+b` then `3` → second Claude Code session
+
+Detach again with `Ctrl+b` then `d`.
+
+---
+
+## Part 6: Daily Usage
+
+### Starting CCBot after a reboot
+
+```bash
+tmux new -s ccbot || tmux attach -t ccbot
+ccbot
+```
+
+Then `Ctrl+b` then `d` to detach.
+
+### Useful Telegram commands
+
+Send these in a topic:
+
+- `/screenshot` — see what the terminal looks like right now
+- `/history` — browse conversation history
+- `/esc` — send Escape key (toggles plan mode, same as Shift+Tab)
+- `/cost` — check token usage
+- `/kill` — kill the session and delete the topic
+
+### Ending a session
+
+Close or delete the topic in Telegram. The tmux window is automatically killed.
+
+### Multiple projects
+
+Create a new topic for each project. CCBot's design is **1 topic = 1 window = 1 session**. Each topic can run a separate Claude Code session in a different project directory.
+
+### Switching between phone and desktop
+
+From your phone, just use Telegram — all interaction goes through topics.
+
+To switch to your desktop terminal:
+
+```bash
+tmux attach -t ccbot
+```
+
+Navigate to the right window with `Ctrl+b` then the window number. You're in the same session with full scrollback.
+
+---
+
+## Part 7: Uninstall and Reinstall
+
+Use this after pushing updates to your fork.
+
+### Stop CCBot
+
+```bash
+tmux attach -t ccbot
+```
+
+Press `Ctrl+C` to stop ccbot. Stay in the tmux session.
+
+### Uninstall the current version
+
+```bash
+uv tool uninstall ccbot
+```
+
+### Install the updated version
+
+```bash
+uv tool install git+https://github.com/JanusMarko/ccbot-workshop.git
+```
+
+If you're getting a cached version and not seeing your changes, force a fresh install:
+
+```bash
+uv tool install --force git+https://github.com/JanusMarko/ccbot-workshop.git
+```
+
+### Verify and restart
+
+```bash
+which ccbot
+ccbot
+```
+
+Then `Ctrl+b` then `d` to detach.
+
+Your `~/.ccbot/.env` configuration and `~/.ccbot/state.json` session state are preserved across reinstalls — you don't need to reconfigure anything.

ccweb/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+ccweb — React web gateway to Claude Code sessions via tmux. Replaces the Telegram interface with a browser-based UI.
+
+Tech stack: Python (FastAPI + WebSocket), React (TypeScript + Vite + Tailwind), tmux (libtmux).
+
+## Common Commands
+
+```bash
+# Backend
+cd ccweb && uv run ruff check ccweb/backend/       # Lint
+cd ccweb && uv run ruff format ccweb/backend/       # Format
+cd ccweb && pip install -e .                         # Install backend
+
+# Frontend
+cd ccweb/frontend && npx tsc -b --noEmit            # Type check
+cd ccweb/frontend && npx vite build                  # Production build
+cd ccweb/frontend && npm run dev                     # Dev server (:5173)
+
+# Run
+ccweb                    # Start server (default :8765)
+ccweb install            # Install hook + global commands
+ccweb hook               # SessionStart hook handler
+```
+
+## Documentation Wiki — IMPORTANT
+
+The `docs/` directory contains all user-facing documentation, rendered both as repo-readable markdown AND in the in-app wiki at `/wiki`.
+
+**When you change any feature, endpoint, component, protocol message, configuration option, or user-facing behavior, you MUST update the corresponding doc file in `docs/`.** This is not optional — the wiki is the primary user documentation.
+
+Doc files use YAML frontmatter (`title`, `description`, `order`) for wiki sidebar sorting. Internal links use relative paths (`../features/sessions.md`).
+
+Key doc locations:
+- `docs/getting-started/` — installation, setup, quickstart
+- `docs/configuration/` — env vars, preferences
+- `docs/features/` — one file per feature
+- `docs/architecture/` — system design, protocol reference
+- `docs/troubleshooting/` — common issues, debugging
+
+## Architecture
+
+- Backend: `ccweb/backend/` — FastAPI server, WebSocket handler, session management
+- Core modules: `ccweb/backend/core/` — forked from ccbot (tmux_manager, session_monitor, terminal_parser, etc.)
+- Frontend: `frontend/src/` — React components, hooks, protocol types
+- State: `~/.ccweb/` — state.json, session_map.json, monitor_state.json, preferences.json
+- Docs: `docs/` — markdown wiki files
+
+## Key Design Constraints
+
+- **Single user** — no multi-user auth
+- **File-based decision grids** — skills write JSON to `.ccweb/pending/`, backend polls, AskUserQuestion blocks Claude
+- **WebSocket protocol** — all real-time comms via typed JSON messages (see `ws_protocol.py` / `protocol.ts`)
+- **Forked modules** — core/ modules are forks from ccbot with import paths adapted; `~/.ccweb/` state is fully separate from `~/.ccbot/`