Claude Code Web UI Development

You are working on the Claude Code Web UI project - a web-based interface for the `claude` command line tool that provides streaming responses in a chat interface.

Project Architecture

Backend (`backend/` - Port 8080)

Frontend (`frontend/` - Port 3000)

Shared Types (`shared/`)

Development Setup

Prerequisites

Initial Setup

```bash

Install git hooks

lefthook install

lefthook run pre-commit

Configure ports (optional - create .env in project root)

echo "PORT=9000" > .env

```

Running Development Servers

```bash

Backend (from project root)

cd backend

deno task dev # Deno runtime

npm run dev # Node.js runtime

Add --debug for debug logging

Frontend (from project root)

cd frontend

npm run dev

```

**Access**: Frontend at http://localhost:3000, Backend at http://localhost:8080

Code Quality & Testing

Quality Commands (run from project root)

Individual Commands

**Testing Stack**:

Important Development Guidelines

File Operations & Navigation

Code Style & Quality

Avoiding Over-Engineering

Security Best Practices

Key Technical Concepts

Claude CLI Integration

Backend uses Claude Code SDK with:

**Message Types**: System (initialization), Assistant (response), Result (execution summary)

Session Continuity

1. First message starts new Claude session

2. Frontend extracts `session_id` from SDK messages

3. Subsequent messages include `session_id` for context

4. Backend passes `session_id` to SDK via `options.resume`

Claude CLI Path Detection

Universal detection supporting npm, pnpm, asdf, yarn:

1. Auto-discovery in system PATH

2. Script path tracing with temporary node wrapper

3. Version validation with `claude --version`

4. Fallback handling with logging

**Implementation**: `backend/cli/validation.ts`

MCP Integration (Model Context Protocol)

Playwright MCP server for automated browser testing. Configure in claude config:

```json

{

"mcpServers": {

"playwright": {

"type": "stdio",

"command": "npx",

"args": ["@playwright/mcp@latest"]

}

}

}

```

Use by saying "**playwright mcp**" in requests for browser automation.

API Endpoints Reference

- Body: `{ message, sessionId?, requestId, allowedTools?, workingDirectory? }`

Claude Code SDK Type Patterns

```typescript

// Type extraction

const systemMsg = sdkMessage as Extract<SDKMessage, { type: "system" }>;

const assistantMsg = sdkMessage as Extract<SDKMessage, { type: "assistant" }>;

// Content access

for (const item of assistantMsg.message.content) {

if (item.type === "text") {

const text = (item as { text: string }).text;

}

}

// System message (direct access)

console.log(systemMsg.cwd);

```

**Key Points**: System fields are directly on object, Assistant content nested under `message.content`

Pull Request & Release Workflow

Creating PRs

1. Create feature branch: `git checkout -b feature/name`

2. Make changes (Lefthook runs `make check` on commit)

3. Push and create PR:

```bash

gh pr create --title "..." --body "..." --label "feature" --label "frontend"

```

4. Include Type of Change checkboxes and description

5. Request review and merge after approval

Available Labels

🐛 `bug`, ✨ `feature`, 💥 `breaking`, 📚 `documentation`, ⚡ `performance`, 🔨 `refactor`, 🧪 `test`, 🔧 `chore`, 🖥️ `backend`, 🎨 `frontend`

Release Process (Automated with tagpr)

1. Feature PRs merged → tagpr creates release PR

2. Add version labels if needed (minor/major)

3. Merge release PR → automatic tag creation

4. GitHub Actions builds binaries automatically

GitHub Sub-Issues API

```bash

gh issue create --title "Sub-issue" --label "feature"

SUB_ISSUE_ID=$(gh api repos/sugyan/claude-code-webui/issues/NUM --jq '.id')

gh api repos/sugyan/claude-code-webui/issues/PARENT/sub_issues --method POST --field sub_issue_id=$SUB_ISSUE_ID

```

Claude Code Dependency Management

**Policy**: Use fixed versions (no caret `^`) for consistency

**Update Procedure**:

1. Check versions: `grep "@anthropic-ai/claude-code" frontend/package.json backend/deno.json`

2. Update frontend package.json and `npm install`

3. Update backend deno.json imports and `rm deno.lock && deno cache cli/deno.ts`

4. Update backend package.json and `npm install`

5. Verify: `make check`

Single Binary Distribution

```bash

cd backend && deno task build # Local building

```

**Automated**: Push git tags → GitHub Actions builds for Linux/macOS (x64/ARM64)

Project Structure

```

├── backend/ # Server with runtime abstraction

│ ├── cli/ # Entry points and validation

│ ├── runtime/ # Runtime abstraction layer

│ ├── handlers/ # API route handlers

│ ├── history/ # History processing

│ ├── middleware/ # Middleware modules

│ ├── utils/ # Utilities (logger, etc.)

│ └── scripts/ # Build and packaging

├── frontend/ # React application

│ ├── src/

│ │ ├── config/ # API configuration

│ │ ├── utils/ # Utilities and constants

│ │ ├── hooks/ # Custom hooks

│ │ ├── components/ # UI components

│ │ ├── types/ # Type definitions

│ │ └── contexts/ # React contexts

├── shared/ # Shared TypeScript types

└── CLAUDE.md # This documentation

```

Key Design Decisions

1. **Runtime Abstraction**: Platform-agnostic business logic

2. **Universal CLI Detection**: Tracing-based approach for all package managers

3. **Raw JSON Streaming**: Unmodified Claude responses for frontend flexibility

4. **Modular Architecture**: Specialized hooks and components

5. **TypeScript Throughout**: Type safety across all components

6. **Project Directory Selection**: User-chosen working directories for context