# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Important Rules

- **No backward compatibility**: This is a new project. Do not add any backward-compatible code, deprecated APIs, migration shims, or legacy support. Remove old code entirely when refactoring instead of keeping it around "just in case".
- **Git commits**: When asked to commit, only create the commit (no push). Commit messages must not contain any Claude-related information (no "Co-Authored-By", no "Generated with Claude", etc.).
- **Documentation**: All documentation must be stored under `docs/`. When implementing features based on design documents, update the corresponding document after coding is complete to reflect the current implementation status.

## Project Overview

AI Terminal Assistant is a terminal-based AI coding assistant built with Claude API. It's structured as a **pnpm monorepo** with four packages:

- **@ai-assistant/core** - Agent engine, tools, LSP integration, checkpoint system
- **@ai-assistant/server** - HTTP Server (Hono + Bun) with REST API, WebSocket, SSE
- **@ai-assistant/cli** - Command-line interface with `serve` and `attach` commands
- **@ai-assistant/web** - React frontend (Vite + Tailwind CSS)

## Build & Development Commands

```bash
# Install dependencies (use pnpm, not npm)
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test                                    # All packages
pnpm --filter @ai-assistant/core test        # Single package
pnpm --filter @ai-assistant/core test:watch  # Watch mode

# Start development
pnpm server:dev                              # Start HTTP server (port 3000)
cd packages/web && pnpm dev                  # Start web UI (port 5173)

# CLI commands
cd packages/cli && bun run src/index.ts serve --port 3000
cd packages/cli && bun run src/index.ts attach http://localhost:3000

# Type checking
cd packages/web && pnpm typecheck
cd packages/server && pnpm build
```

## Architecture

### Package Dependencies

```
web / cli
    ↓
  server  →  REST API + WebSocket + SSE
    ↓
   core   →  Agent / Tools / LSP / Checkpoint / Hooks / MCP
```

### Core Package (`packages/core/src/`)

Key modules:
- `core/agent.ts` - Main Agent class using AI SDK's `streamText`
- `tools/` - Tool registry with bash, file operations, search, etc.
- `editors/` - Unified edit mode system (whole/diff/search-replace)
- `lsp/` - Language Server Protocol integration
- `checkpoint/` - Shadow Git checkpoint system
- `hooks/` - Pre/post execution hooks
- `mcp/` - Model Context Protocol client
- `repomap/` - Repository map generation with tree-sitter

### Server Package (`packages/server/src/`)

- `index.ts` - Hono app setup with CORS, auth middleware
- `routes/` - REST endpoints (sessions, tools, config)
- `ws.ts` - WebSocket handler for real-time chat
- `sse.ts` - Server-Sent Events for status updates
- `agent/adapter.ts` - Bridges core Agent to server (dynamic import to avoid build dependency)
- `auth/token.ts` - Token-based authentication (auto-enabled for non-localhost)

### Communication Flow

1. Client connects via WebSocket to `/api/ws/:sessionId`
2. Client sends `{ type: 'message', payload: { content } }`
3. Server calls `processMessage()` → Agent.chat() with streaming callback
4. Server pushes `chunk` events back via WebSocket
5. On completion, server sends `done` event with full response

## Key Design Patterns

### Dynamic Core Module Loading

Server uses dynamic import to avoid build-time dependency on core:
```typescript
const corePath = '@ai-assistant/core';
const core = await import(corePath) as CoreModule;
```

### Tool Registration

Tools are registered in `toolRegistry` with Zod schemas:
```typescript
toolRegistry.register({
  name: 'read_file',
  description: '...',
  parameters: z.object({ path: z.string() }),
  execute: async (params) => { ... }
});
```

### Session Management

Each WebSocket connection binds to a session. Sessions hold:
- Message history
- Status (idle/busy)
- Agent instance (cached per session)

## Configuration

- **Environment**: `ANTHROPIC_API_KEY` required in `.env`
- **Default model**: `claude-sonnet-4-20250514`
- **Server auth**: Auto-generates token when host is not localhost

## Design Documentation

Architecture details are in `docs/design/architecture/gui-server-client.md`, including:
- Implementation roadmap with completion status
- API endpoint specifications
- Communication protocol definitions