\n\n## Features\n\n- **Multi-session chat** — Up to 3 conversations side-by-side, organised into reorderable session groups that persist across refreshes\n- **Streaming responses** — Real-time WebSocket streaming with fine-grained status (thinking / writing / tool use) and predicted next-prompt suggestions after each turn\n- **Permission management** — Visual tool-usage approval with per-session and global persistence, plan-mode approval with \"stop & take over\", and `Shift+Tab` permission-mode cycling\n- **Git integration** — Status, diff, branches, stashes, AI-generated commit messages, and rewinding tracked files to any point in the conversation\n- **Background tasks** — Background an in-flight task (`Ctrl+B`), watch subagents, and follow their progress live\n- **App plugins (Mods)** — Install plugins from a marketplace or a local directory to add menus, commands, settings, and panels to the app shell; each plugin runs its own trusted background service\n- **Image paste** — Drag & drop or paste images directly into the chat (inline multimodal content)\n- **Session search** — Full-text message search with highlighted matches and jump-to-result\n- **AI recaps** — One-click AI-generated summaries of a session\n- **MCP** — Configure global servers, add dynamic per-session servers, reconnect/toggle at runtime, and complete OAuth elicitation inline\n- **Keyboard shortcuts** — `Cmd+K` command palette and a full set of global shortcuts\n- **Themes & skins** — Dark / light / system modes with selectable skins (default, glow, Anthropic, high-contrast)\n- **Flexible config** — Model, permission mode, MCP servers, thinking/effort level, and more via in-app settings or `config.json`\n- **LAN access** — Scan a QR code to use from your phone on the same network\n\nEach chat session holds its own stateful `Query` (the SDK's streaming async generator), so multi-turn conversations, mid-run interruption, model switching, and permission-mode changes all drive a live subprocess.\n\n## Quick start\n\nInstall globally from npm and run:\n\n```bash\nnpm i -g claude-react-web\nclaude-react-web\n```\n\nOr run it without installing via `npx`:\n\n```bash\nnpx claude-react-web\n```\n\nEither way launches the server on `http://127.0.0.1:3456` and opens your browser.\n\n\nRun from source instead\n\n```bash\ngit clone https://github.com/LoopGe/claude-react-web.git\ncd claude-react-web\nnpm install\nnpm run build\nnpm run start\n```\n\n\n\nOn first run a starter `~/.claude-react-web/config.json` is scaffolded. Set your Anthropic credentials there before sending messages — the server forwards them to the Claude SDK subprocess:\n\n```json\n{\n \"authToken\": \"sk-ant-...\",\n \"baseUrl\": \"https://api.anthropic.com\"\n}\n```\n\n`authToken` is sent as a Bearer token, so it works against both the official API and Anthropic-compatible proxies (point `baseUrl` at the relay). You can also fill these in from the in-app settings panel. See [CONFIG.md](./CONFIG.md) for every field.\n\n### CLI options\n\n```\nclaude-react-web [options]\n -p, --port Server port (default: 3456)\n --host Bind host (default: 127.0.0.1). Use 0.0.0.0 to\n allow LAN access — this REQUIRES a web access\n token (auto-generated if --token is omitted).\n --token Shared web access token required to use the UI.\n Auto-generated when the host is non-loopback.\n -o, --open Open browser on start (default)\n --no-open Do not open a browser window\n --cwd Default cwd advertised to new sessions\n --model Default model advertised to new sessions\n --state-dir Where session metadata + config.json are kept\n (default: ~/.claude-react-web)\n --claude-binary Path to the claude CLI binary (overrides\n CLAUDE_CODE_BINARY / PATH auto-detection)\n --disable-app-plugins Disable the App Plugins (Mods) subsystem\n --safe-mode Load app plugins in safe mode — static UI\n contributions only, no background subprocesses\n -V, --version Print version and exit\n -h, --help Show help\n```\n\nWhen bound to a non-loopback host the server prints a token-bearing URL (plus a scannable QR code) so you can open the already-authenticated UI from a phone on the same network.\n\n### Terminal commands\n\nRun with no command to start the web server. Pass a subcommand to manage the\nsame persisted config the UI edits — headless and scriptable (`--json` for\nstructured output, `--yes` to confirm destructive verbs, `--state-dir `\nto target a non-default state dir):\n\n```\nclaude-react-web mcp list | add | update | remove | enable | disable | test \nclaude-react-web marketplace add | list | remove \nclaude-react-web app-plugin marketplace add | list | remove \nclaude-react-web app-plugin list | install : | uninstall \nclaude-react-web config get [key] | set \nclaude-react-web sessions list | delete \nclaude-react-web doctor\nclaude-react-web update\n```\n\n`claude-react-web doctor` runs local environment checks and exits non-zero when\nsomething is broken; `claude-react-web update` checks the npm registry for a\nnewer release. `claude-react-web --help` prints the full flags for a\ncommand.\n\n### Environment variables\n\nAnthropic credentials live in `config.json` (`authToken` / `baseUrl`), not in env vars — the server injects them into each SDK subprocess. The variables below tune the server itself and are all optional:\n\n| Variable | What it does | Default |\n| --- | --- | --- |\n| `CLAUDE_CODE_BINARY` | Path to the `claude` CLI binary (same as `--claude-binary`) | auto-detected on `PATH` |\n| `LOG_LEVEL` | Log verbosity (`error` / `warn` / `info` / `debug` / `trace`) | `info` |\n| `LOG_SCOPES` | Comma-separated scope filter for logs | all scopes |\n| `DEBUG_SESSION` | Set to `1` to force `LOG_LEVEL=debug` (back-compat alias) | — |\n| `EVENT_LOOP_PROBE` | Set to `0` to disable the event-loop stall probe | enabled |\n\nAny other `ANTHROPIC_*` variable in the environment is forwarded to the SDK subprocess as-is (except `ANTHROPIC_API_KEY`, which is intentionally stripped in favour of the `authToken` Bearer flow).\n\n### Configuration file\n\nMost server-side defaults (model list, recap model, commit-message model, upload limits, history cap, max group panels, etc.) are configured via `~/.claude-react-web/config.json`. See [CONFIG.md](./CONFIG.md) for the full field reference, or copy [`config.example.json`](./config.example.json) to get started:\n\n```bash\nmkdir -p ~/.claude-react-web\ncp config.example.json ~/.claude-react-web/config.json\n```\n\n## Develop\n\n```bash\nnpm install\nnpm run dev # tsx watch server (:3456) + vite (:5174, /api proxied)\nnpm run typecheck\nnpm run lint\nnpm test\n```\n\nUseful scripts:\n\n| Script | What it does |\n| ------------------- | -------------------------------------------------------- |\n| `npm run dev` | Hot-reloading server + Vite dev server side by side |\n| `npm run build` | `vite build` → `dist/client` then esbuild → `dist/cli.mjs` |\n| `npm run typecheck` | `tsc --noEmit` for both browser and Node tsconfigs |\n| `npm run lint` | ESLint (includes `react-hooks`) |\n| `npm run format` | Prettier write |\n| `npm test` | Vitest (server unit tests + client hook tests) |\n| `npm run verify` | `typecheck` + `lint` + `test` + `build` in one go |\n\n## Architecture\n\n```mermaid\ngraph TB\n Browser[\"Browser UI React 19 · components · hooks · session-store\"]\n Browser <-->|\"WebSocket (multiplexed) + REST /api\"| Routers\n\n subgraph Server[\"Hono Server · port 3456\"]\n direction TB\n Gate[\"Auth gate (web token / LAN) · CORS · body-limit\"]\n Routers[\"REST routers /api/* + WebSocket hub\"]\n Gate --> Routers\n end\n\n subgraph SM[\"Session Manager — one live session per tab\"]\n direction TB\n Pool[\"Session pool\"]\n Pump[\"Session Pump → history ring (500) → fan-out + task state\"]\n Broker[\"Permission Broker (canUseTool)\"]\n Dialogs[\"Dialog / Elicitation brokers (refusal fallback · MCP OAuth)\"]\n Health[\"Health Monitor (stuck-session GC)\"]\n Pool --> Pump & Broker & Dialogs & Health\n end\n\n Reg[\"Provider Registry (pluggable AgentProvider)\"]\n Claude[\"claude provider → SDK Query\"]\n SDK[\"Claude Agent SDK spawns claude CLI subprocess\"]\n Anthro[\"Anthropic Messages API recap · commit-message · plugin ai-broker\"]\n Stores[\"Disk-backed stores sessions.json · config.json · MCP · marketplace→plugins · snippets · UI state · app-plugins\"]\n Plugins[\"App Plugins (Mods) marketplace · local installs · per-plugin Node service\"]\n Git[\"Git Layer — git.ts owns all execution\"]\n Disk[(\"~/.claude/projects/ full transcripts · resumed via options.resume\")]\n\n Routers --> Pool\n Pool --> Reg --> Claude --> SDK\n Broker -.->|canUseTool| Claude\n Dialogs -.->|onUserDialog / elicitation| Claude\n Routers --> Anthro\n Routers --> Stores\n Routers --> Plugins\n Pump --> Git\n Claude --> Disk\n Pump -.->|history-reader| Disk\n```\n\n```\nserver/\n cli.ts # bin entry — argv, startup banner, QR, browser open\n app.ts # Hono app: auth gate, CORS, body-limit, route mounting, static serve\n routes/ # REST routers: sessions, permissions, uploads, recap, config, health,\n # marketplace (mp), git-write, update, search, skills, hooks, dialog,\n # elicitation, reset, usage, ui-state\n session-manager.ts # multi-session pool, provider wiring, WS fan-out, idle GC\n session-pump.ts # drains each provider stream → history ring + subscribers + task state\n providers/ # AgentProvider interface + registry; claude provider wraps the SDK Query\n permission-broker.ts # parks canUseTool requests until the client decides\n elicitation-broker.ts # MCP OAuth elicitation requests\n user-dialog-broker.ts # user dialogs (refusal-fallback prompt)\n subagent-watcher.ts # tracks background Agent dispatches → TaskRecordUi seeds\n session-health.ts # stuck-session detector (mid-turn silence GC)\n recap.ts # AI session summaries, via anthropic-api.ts\n commit-message.ts # AI commit messages, via anthropic-api.ts\n compact-summary.ts # session compaction summaries\n history-reader.ts # reads ~/.claude/projects transcripts; resume / fork anchors\n ws.ts # WebSocket hub (single connection, multiplexed channels)\n git.ts # owns ALL git execution (runGit); git-broadcast.ts debounces mutations\n git-routes.ts # read-only git endpoints (status, diff, log)\n fs-routes.ts # directory-only browser for the cwd picker\n mcp-config.ts # global MCP server store; mcp-routes.ts exposes it\n mp-store.ts # homegrown git-repo marketplace → injects Options.plugins\n snippet-store.ts # composer text macros (snippet-routes.ts)\n ui-state-store.ts # session groups + sidebar order (json-file-store.ts backed)\n app-plugins/ # Mods: manager, store, per-plugin Node process, marketplace, host API\n config.ts # centralised defaults from config.json\n persistence.ts # ~/.claude-react-web/sessions.json read/write\n auth.ts # web-access token gating (LAN)\n exec.ts # child_process helpers; process-monitor.ts watches subprocesses\n update-checker.ts # in-app upgrade detection (update-routes.ts)\n log.ts # createLogger(scope) — all diagnostics go through this\n\nshared/ # types + logic shared by server and client\n # ws-protocol, tasks, elicitation, user-dialog, rewind, reset, usage,\n # account-info, app-plugins, hooks, skills, mcp-types, permission-request,\n # search/, …\n\nsrc/\n App.tsx # multi-panel chat grid, sidebar, settings overlay, command palette\n components/ # Chat, Composer, MessageList, SessionList, GitPanel, TasksPanel,\n # CommandPalette, MarketplaceTab, McpInstaller, AppPluginsTab,\n # UsagePanel, RecapWindow, SubagentOverlay, …\n hooks/ # useWsHub, useChatStream, usePastedImages, usePermissionChannel,\n # useGitStatus, useUpdateInfo, useUiState, useSessionRecap, useTaskInfo, …\n session-store/ # client-side message store (reducer + selectors, IDB transcript cache)\n search/ # full-text message search (extract, match, highlight)\n app-plugins/ # plugin UI contributions (menus, commands, panels)\n```\n\nThe server keeps one live provider session per tab — the default `claude` provider wraps the SDK `Query`, and `session-pump.ts` drains it, fanning each SDK message out to every WebSocket subscriber via a single multiplexed connection per tab. Metadata is persisted in `~/.claude-react-web/sessions.json`, so sessions survive restarts; the SDK itself stores full conversation history in `~/.claude/projects/` and resumes them via `options.resume`. Server-side defaults (model list, recap model, commit-message model, upload limits, etc.) are centralised in `config.ts` and configurable via `~/.claude-react-web/config.json` — see [CONFIG.md](./CONFIG.md).\n\nThe separate **App Plugins (Mods)** system (`server/app-plugins/`, `shared/app-plugins/`, `src/app-plugins/`) lets plugins extend the app shell with menus, commands, settings, and panels. Each plugin's background code runs in its own trusted Node subprocess over JSON-RPC/stdio; plugins are installed from a marketplace repo (the official catalog lives in [`plugins/`](./plugins/), published as a separate lightweight GitHub repo) or a local directory. `--disable-app-plugins` and `--safe-mode` control the subsystem at launch.\n\n## Contributing\n\nIssues and pull requests welcome. The codebase has 2,500+ tests across ~170 files covering the session pool, persistence, git execution, permission broker, WebSocket hub, app-plugin runtime, keyboard shortcuts, and the client hooks — please keep them green (`npm test`).\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}
![\"claude-react-web](\"docs/screenshots/homepage.png\")
\n