ai-terminal-assistant/CLAUDE.md

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

# 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:

const corePath = '@ai-assistant/core';
const core = await import(corePath) as CoreModule;

Tool Registration

Tools are registered in toolRegistry with Zod schemas:

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