Correspondents/AGENTS.md

# CLAUDE.md

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

## Project Overview

**Multi-Agent Chat Interface** - A Next.js-based AI chat platform that supports multiple agents configured via environment variables. Users select an agent from a menu on first visit, then chat with that agent. The application integrates with n8n workflows via webhooks, features markdown rendering with syntax highlighting, image uploads, and an interactive diff tool for code changes.

## Development Commands

```bash
npm run dev      # Start Next.js development server (http://localhost:3000)
npm run build    # Create production build
npm start        # Run production server
npm run lint     # Run ESLint checks
```

**Note:** No testing framework is currently configured. Tests should be added when needed.

## Technology Stack

- **Frontend:** Next.js 15.5.4 (App Router), React 19, TypeScript 5
- **Styling:** Tailwind CSS 4.1.9 with PostCSS
- **UI Components:** shadcn/ui (Radix UI primitives), Lucide icons
- **Forms & Validation:** React Hook Form + Zod
- **Markdown:** react-markdown with remark-gfm and rehype-highlight for code syntax
- **Diffs:** Custom pipeline using `diff` library with Highlight.js for colored output
- **Deployment:** Cloudflare Workers/Pages via OpenNextJS + Wrangler

## Project Structure

```
src/
├── app/
│   ├── api/
│   │   ├── agents/route.ts        # GET endpoint - returns available agents from env vars
│   │   └── chat/route.ts          # POST endpoint - routes to selected agent's webhook
│   ├── layout.tsx                 # Root layout with theme provider
│   ├── page.tsx                   # Home page - conditionally renders AgentSelector or ChatInterface
│   └── globals.css                # Tailwind global styles
├── components/
│   ├── agent-selector.tsx         # Agent selection menu (card-based UI)
│   ├── chat-interface.tsx         # Main chat UI component (client-side, per-agent)
│   ├── markdown-renderer.tsx      # Parses markdown + extracts diff-tool blocks
│   ├── diff-display.tsx           # Renders diffs with syntax highlighting
│   ├── diff-tool.tsx              # Diff tool wrapper component
│   ├── header.tsx                 # App header with agent name and switch button
│   ├── mode-toggle.tsx            # Dark/light theme toggle
│   ├── theme-provider.tsx         # Theme context setup
│   ├── DIFF_TOOL_USAGE.md         # In-component documentation
│   └── ui/                        # shadcn/ui component library
└── lib/
    ├── types.ts                   # TypeScript types and interfaces (Agent, Message, ChatRequest, etc.)
    └── utils.ts                   # Utility functions (cn() for classname merging)
```

## Architecture & Data Flow

### Agent Selection Flow
```
User visits site
  ↓
page.tsx checks localStorage for selected agent
  ↓
If no agent: Show AgentSelector
  │   - Fetches agents from GET /api/agents
  │   - Displays agent cards with name + description
  │   - On selection: saves agent to localStorage and shows ChatInterface
  ↓
If agent exists: Show ChatInterface with that agent
```

### Multi-Agent API Pattern
**GET /api/agents**
- Reads environment variables `AGENT_1_URL`, `AGENT_1_NAME`, `AGENT_1_DESCRIPTION`, `AGENT_2_URL`, etc.
- Returns array of available agents: `{ agents: Agent[] }`

**POST /api/chat**
- **Request:** `{ message, timestamp, sessionId, agentId, images? }`
- **Processing:**
  1. Validates agentId is provided
  2. Looks up webhook URL using `getAgentWebhookUrl(agentId)`
  3. Proxies request to agent's specific n8n webhook
  4. Forwards images (base64) if provided
- **Response Format:** Newline-delimited JSON with two message types:
  - `"item"` - Text content rendered directly
  - `"tool_call"` - Structured tools like `{ name: "show_diff", input: {...} }`

### Diff Tool Pipeline
```
n8n webhook response (tool_call: show_diff)
  ↓
/api/chat/route.ts (converts to markdown code block format)
  ↓
MarkdownRenderer (regex extracts diff-tool code blocks)
  ↓
DiffDisplay (renders diffs with Highlight.js syntax highlighting)
```

### Client-Side Architecture
- **State Management:** React hooks (useState, useRef) + localStorage for persistence
- **Agent Persistence:** Selected agent stored in `selected-agent` and `selected-agent-id`
- **Session ID:** Per-agent format `chat-session-{agentId}` stored as `chat-session-{agentId}`
- **Message Storage:** Per-agent messages stored as `chat-messages-{agentId}` in localStorage
- **Image Handling:** Images converted to base64 and included in message payload
- **Auto-scroll:** Maintains scroll position at latest message

### Markdown Processing Details
- Custom regex parser in `MarkdownRenderer` extracts ` ```diff-tool ... ``` ` code blocks
- Replaces diff-tool blocks with placeholders during markdown rendering
- After markdown is rendered, dynamically inserts `<DiffDisplay>` components
- Supports remark-gfm (GitHub-flavored markdown) and rehype-highlight for syntax coloring

## Key Files & Responsibilities

| File | Purpose |
|------|---------|
| `src/lib/types.ts` | Centralized TypeScript types: Agent, Message, ChatRequest, ChatResponse, etc. |
| `src/app/api/agents/route.ts` | GET endpoint - parses env vars and returns available agents |
| `src/app/api/chat/route.ts` | POST endpoint - looks up agent webhook URL and proxies requests |
| `src/app/page.tsx` | Home page - manages agent selection state, conditionally renders AgentSelector or ChatInterface |
| `src/components/agent-selector.tsx` | Agent selection UI - fetches agents, displays cards, handles selection |
| `src/components/chat-interface.tsx` | Main chat UI - handles per-agent messages, image uploads, streaming |
| `src/components/header.tsx` | App header - displays agent name and "Switch Agent" button |
| `src/components/markdown-renderer.tsx` | Parses markdown and extracts diff-tool blocks for custom rendering |
| `src/components/diff-display.tsx` | Renders side-by-side diffs with syntax highlighting using Highlight.js |
| `AGENT_DIFF_TOOL_SETUP.md` | Comprehensive guide for configuring n8n agents to output diff tools |
| `src/components/DIFF_TOOL_USAGE.md` | In-component documentation for the diff tool feature |

## Theme & Styling

- **System:** Tailwind CSS 4 with CSS custom properties and OKLch color space
- **Colors:** Warm light mode (cream/beige) and pure black dark mode
- **Implementation:** `next-themes` with "light" and "dark" variants
- **Toggle:** Mode toggle button in header
- **Global Styles:** `src/app/globals.css` contains theme definitions and Tailwind imports

## Configuration Files

- `tsconfig.json` - TypeScript strict mode, bundler module resolution, `@/*` alias to `src/`
- `next.config.ts` - Next.js configuration
- `open-next.config.ts` - Cloudflare-specific Next.js configuration
- `wrangler.jsonc` - Wrangler (Cloudflare CLI) configuration
- `eslint.config.mjs` - ESLint with Next.js core-web-vitals and TypeScript support
- `components.json` - shadcn/ui component library configuration
- `postcss.config.mjs` - Tailwind CSS plugin configuration

## n8n Webhook Integration

The chat endpoint routes to an n8n workflow via webhook. The workflow should:

1. Accept message input and context from the client
2. Return newline-delimited JSON with messages in one of two formats:
   - `{ "type": "item", "content": "text content" }`
   - `{ "type": "tool_call", "name": "show_diff", "input": { "before": "...", "after": "...", "language": "..." } }`

**Note:** See `AGENT_DIFF_TOOL_SETUP.md` for detailed instructions on configuring n8n agents to use the diff tool feature.

## Common Tasks

### Configuring Agents via Environment Variables
**Local Development (.env.local):**
```
AGENT_1_URL=https://n8n.example.com/webhook/agent-1-uuid
AGENT_1_NAME=Creative Writer
AGENT_1_DESCRIPTION=An AI assistant for creative writing and brainstorming

AGENT_2_URL=https://n8n.example.com/webhook/agent-2-uuid
AGENT_2_NAME=Code Reviewer
AGENT_2_DESCRIPTION=An AI assistant for code review and refactoring
```

**Cloudflare Deployment:**
- Go to Cloudflare dashboard → Workers & Pages → your-project → Settings → Environment variables
- Add the same AGENT_* variables above
- Deploy to apply changes

### Adding a New Agent
1. Add three environment variables:
   - `AGENT_N_URL` - webhook URL for the agent
   - `AGENT_N_NAME` - display name
   - `AGENT_N_DESCRIPTION` - short description
2. On next page reload, new agent appears in AgentSelector
3. No code changes needed

### Modifying Chat Messages or Display
- **Chat UI:** `src/components/chat-interface.tsx`
- **Rendering:** `src/components/markdown-renderer.tsx`
- **State:** Message list stored in component state, persisted to localStorage per agent
- **Per-agent persistence:** Messages saved as `chat-messages-{agentId}`

### Changing Theme Colors
- Edit CSS custom properties in `src/app/globals.css`
- Uses OKLch color space (perceptually uniform)
- Dark mode variant defined with `@custom-variant dark`

### Adding New Tool Types (beyond show_diff)
- **Step 1:** Handle in `/api/chat/route.ts` - convert tool_call to markdown format
- **Step 2:** Add detection logic in `markdown-renderer.tsx` to extract new code block type
- **Step 3:** Create new component similar to `DiffDisplay` and render dynamically

### Switching Between Agents
- Users click "Switch Agent" button in header
- Returns to AgentSelector menu
- Previously selected agents/messages are preserved in localStorage per agent
- No data loss when switching

## Notes for Future Development

### Multi-Agent Features
- **Agent Switching:** Currently requires page reload to agent selector. Could add inline dropdown in header.
- **Agent Management:** UI for adding/editing agents without env vars could improve UX
- **Agent Verification:** Add health checks to verify agents' webhook URLs are reachable
- **Agent Categories:** Could group agents by category/type for better organization

### Image Upload Enhancements
- **Image Storage:** Currently base64 in memory; consider Cloudflare R2 for large images
- **Image Preview:** Add full-screen image viewer for uploaded images
- **Multi-file Upload:** Support multiple file types beyond images

### Performance & Scaling
- **Message Virtualization:** Chat interface uses `useRef` for scroll - consider virtualizing long message lists
- **Storage Size:** localStorage has 5-10MB limit; consider IndexedDB for longer conversations
- **Streaming:** Current implementation reads entire response before parsing; consider streaming HTML as it arrives

### Testing & Quality
- **Testing:** Consider adding Jest or Vitest for component and API testing
- **Error Handling:** Enhance with retry logic for failed webhook calls and better error messages
- **Logging:** Add structured logging for debugging multi-agent interactions

### Accessibility & UX
- **Keyboard Navigation:** Verify keyboard navigation on agent selector cards and custom diff tool
- **ARIA Labels:** Add aria-labels for screen readers on interactive elements
- **Mobile Responsive:** Test agent selector and chat interface on mobile devices