WebAgent

A terminal-style web UI for ACP-compatible agents — Copilot CLI, Claude Code, Gemini CLI, and more.

Quick Start

Prerequisites: Node.js 22.6+, an ACP-compatible agent installed and authenticated.

npm install -g @lelouchhe/webagent
webagent                                     # start on port 6800
webagent --config /path/to/config.toml       # custom config

Or run directly: npx @lelouchhe/webagent

Data (SQLite database, uploaded images) is stored in ./data/ by default. See Configuration & Operations for daemon mode, TOML settings, and agent setup.

Architecture

Browser ←── REST + SSE ──→ Server ←── ACP ──→ Agent CLI
  (thin client)            (Node.js)           (copilot/claude/gemini)

The frontend is a standard browser client that talks to the server over REST + SSE. The API is the boundary — anyone can build their own client.

| Module | Role | |---|---| | routes.ts | REST API + static files (full API reference) | | event-handler.ts | ACP event routing → SSE broadcast | | session-manager.ts | Session state, buffers, bash processes | | bridge.ts | ACP bridge — agent subprocess lifecycle | | store.ts | SQLite persistence (WAL mode) | | daemon.ts | Background service with crash recovery |

Tech stack: Node.js + TypeScript (--experimental-strip-types), SQLite (better-sqlite3), Zod validation, esbuild bundling.

Frontend source lives in public/js/*.ts, bundled by esbuild into a single content-hashed JS file. See Client Architecture.

Documentation

| Document | Contents | |---|---| | Features | Chat, images, bash, sessions, slash commands, keyboard shortcuts, themes | | Configuration & Operations | TOML config, daemon commands, agent setup, upgrading | | API Reference | REST endpoints, SSE events, implementation details | | ACP Integration | Client extensions, protocol scope, current limits | | Client Architecture | Frontend modules, data flow, conventions | | Development | Building from source, dev mode, testing, publishing | | Auto-Start on Boot | launchd, systemd, crontab, Windows Task Scheduler |