Claude WebUI

A web-based interface for Claude Agent SDK that provides both single-agent conversations and multi-agent collaboration through an accessible browser interface.

What is Claude WebUI?

Claude WebUI transforms Claude Agent SDK into a powerful web-based development environment with:

Single-Agent Features:

• 🌐 Network access - Use Claude Code from any device on your network (phone, tablet, browser)
• 💬 Real-time streaming - See responses, tool executions, and thinking blocks as they happen
• 📁 Project organization - Group sessions by working directory with drag-and-drop reordering
• 🔧 Rich tool visualization - File diffs, search results, task lists, bash output with syntax highlighting
• 🔒 Granular permissions - Approve tools with smart suggestions and runtime mode switching
• 💾 Persistent sessions - Resume conversations across restarts with full history preservation
• 🎨 Modern Vue 3 UI - Responsive, mobile-first interface with real-time updates

Multi-Agent Features (Legion):

• 🏛️ Multi-agent orchestration - Create teams of specialized AI agents (minions) working together
• 📡 Inter-agent communication - Minions communicate via structured messages in real-time
• 🌳 Hierarchical organization - Parent-children relationships for task decomposition
• 🤖 Autonomous spawning - Minions can dynamically create and dispose of child minions
• 👁️ Complete observability - Timeline view shows all agent activity
• 🔎 Direct Minion Control - Spy view inspects individual minions, interrupt them, treat them as interactive sessions
• 🎛️ Fleet controls - Emergency halt and resume all agents instantly

Quick Start

Prerequisites

• Python 3.13+ installed
• uv package manager (installation guide)
• Claude Code installed and authenticated (you can even re-login in the background to refresh auth tokens)
• Modern browser (Chrome, Firefox, Safari, Edge)

Installation

1. Clone the repository:

git clone https://github.com/EdanStarfire/claudecode_webui.git
cd claudecode_webui

2. Install dependencies:

uv sync

3. Start the server:

uv run python main.py

4. Open your browser:

http://localhost:8000

5. Create your first project:

• Click "New Project" in the sidebar
• Choose a working directory (use folder browser)
• Create a session and start chatting

Optional: Frontend Development

If you want to modify the Vue 3 frontend:

# Terminal 1: Start backend (use test port to avoid conflicts)
uv run python main.py --port 8001 --debug-all

# Terminal 2: Start frontend dev server with hot reload
cd frontend
npm install
npm run dev

# Access dev server at http://localhost:5173

Code Quality

The project uses Ruff for Python linting to maintain code quality:

# Lint specific files you changed
uv run ruff check --fix src/web_server.py src/session_manager.py

# Or use git to find changed files
uv run ruff check --fix $(git diff --name-only --diff-filter=AM | grep '\.py$')

# View violations without fixing
uv run ruff check src/module_name.py

Important: Only run Ruff on files you've modified, not the entire src/ directory. Running --fix on the whole codebase will auto-fix unrelated violations.

Progressive Strictness Strategy: The codebase currently has existing linting violations that are being addressed incrementally. New code must not introduce violations, and violations should be fixed when modifying existing files.

See CLAUDE.md for detailed workflow and requirements.

Core Features

Single-Agent Mode (Standard Sessions)

Use your browser to manage local claude code instances from your phone.

🗂️ Project & Session Management

• Hierarchical organization - Projects group sessions by working directory
• Drag-and-drop reordering - Customize project and session order
• Persistent state - Resume conversations after crashes or restarts
• Session controls - Start, terminate, restart, or reset sessions
• Name customization - Rename projects and sessions for clarity

🛠️ Rich Tool Visualization

Custom UI for every Claude Agent SDK tool:

• File operations - Syntax-highlighted previews for Read, color-coded diffs for Edit/Write
• Search results - Formatted Grep/Glob output with file paths and context
• Todo lists - Visual task tracking (☐ pending, ◐ in-progress, ☑ completed)
• Shell commands - Bash execution w

...