Claude Code UI - Next.js

Modern web interface for Claude Code CLI and Cursor CLI built with Next.js 15, powered by v0 components, and deployed on Vercel.

🎯 Overview

Claude Code UI is a comprehensive web application that provides a beautiful, responsive interface for interacting with Claude Code and Cursor CLI tools. Built with modern technologies and best practices, it offers:

• Real-time AI Chat Interface - Communicate with Claude and Cursor AI
• Integrated Terminal - Direct CLI access through web browser
• File Management - Browse, edit, and manage project files
• Git Integration - Full Git workflow support
• Production Monitoring Dashboard - Real-time error tracking, CI/CD monitoring, and system health
• Intelligent Caching - Redis-backed caching with automatic fallback
• Performance Monitoring - Comprehensive API and database performance tracking
• Automated Reporting - Scheduled reports with email delivery
• Mobile Responsive - Works perfectly on all devices
• High Performance - Optimized for speed and scalability

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm 10+
• Claude Code CLI or Cursor CLI installed
• Git

Installation

1. Clone the repository

   git clone https://github.com/your-org/claude-code-ui-nextjs.git
   cd claude-code-ui-nextjs

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Start development server

   npm run dev

5. Open in browser

   http://localhost:3000
   

🏗️ Architecture

The application follows a modern, scalable architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   API Routes    │    │  External APIs  │
│   (Next.js)     │◄──►│ (Next.js API)   │◄──►│ Claude/Cursor   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Components    │    │   WebSocket     │    │   File System   │
│   (v0 + shadcn) │    │   (Real-time)   │    │   (Local/Cloud) │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Technology Stack

Frontend

• Next.js 15 - React framework with App Router
• React 19 - Latest React with concurrent features
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• v0 Components - AI-generated UI components
• shadcn/ui - High-quality React components

Backend

• Next.js API Routes - Serverless API endpoints
• Vercel Edge Functions - Ultra-fast serverless functions
• WebSockets - Real-time communication
• NextAuth.js - Authentication solution
• Prisma - Database ORM
• Redis Caching - High-performance distributed caching
• SSE (Server-Sent Events) - Real-time notifications
• Performance Monitoring - Response time tracking and analytics

Infrastructure

• Vercel - Hosting and deployment
• PostgreSQL - Primary database
• Redis - Caching and session storage
• Vercel Blob - File storage
• Sentry - Error tracking and monitoring
• GitHub Actions - CI/CD pipeline integration

🔑 Environment Variables

Copy .env.example to .env and configure:

# Required - Basic Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-generated-secret-here

# Required - AI Provider API Keys (choose one or both)
CLAUDE_API_KEY=your-claude-api-key
CURSOR_API_KEY=your-cursor-api-key

# Optional - Additional providers
OPENAI_API_KEY=your-openai-api-key

# Optional - Database (for production)
DATABASE_URL=postgresql://username:password@localhost:5432/claude-code-ui

Generating Secrets

For NEXTAUTH_SECRET, generate a secure random string:

openssl rand -base64 32

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Installation Guide - Step-by-step setup
• Architecture Overview - System design and structure
• Integration Guide - External services setup (Sentry, GitHub, Email)
• Caching & Performance - Optimization strategies
• API Reference - HTTP endpoints
• Component Library - UI components
• Deployment Guide - Production deployment

🔧 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm run type-check   # Run TypeScript checks

# Database commands
npm run db:generate  # Generate Prisma client
npm run db:push      # Push schema to database
npm run db:migrate   # Run migrations
npm run db:seed      # Seed database with sample data
npm run db:setup     # Complete database setup

Project Structure

claude-code-ui-nextjs/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── dashboard/         # Dashboard pages
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── chat/             # AI chat interface
│   ├── file-manager/     # File explorer
│   ├── terminal/         # Terminal emulator
│   ├── layout/           # Layout components
│   └── ui/               # Base UI components
├── lib/                   # Utilities and helpers
├── types/                 # TypeScript type definitions
├── docs/                  # Documentation
└── public/               # Static assets

🔌 API Endpoints

Monitoring Dashboard

• GET /api/metrics/overview - System health overview
• GET /api/metrics/sentry - Error tracking metrics
• GET /api/metrics/cicd - CI/CD pipeline health
• GET /api/metrics/conflicts - Merge conflict tracking

Reports & Notifications

• GET /api/reports - Get scheduled reports
• POST /api/reports/generate - Generate report on-demand
• GET /api/reports/history - Report history with pagination
• GET /api/notifications/sse - Real-time notification stream
• GET /api/notifications - List notifications

Cache & Performance

• GET /api/cache - Cache statistics
• DELETE /api/cache?tag=metrics - Invalidate cache by tag
• GET /api/monitoring/performance - Performance metrics

Chat Integration

• POST /api/claude - Send messages to Claude AI
• POST /api/cursor - Execute Cursor CLI commands

Terminal

• POST /api/terminal - Execute terminal commands
• GET /api/terminal - List terminal sessions
• DELETE /api/terminal - Close terminal session

File Management

• GET /api/files - List directory contents
• POST /api/files - Create/write files
• DELETE /api/files - Delete files

WebSocket

• WS /api/ws - Real-time communication

🚀 Deployment

Deploy to Vercel

1. One-click deploy using the button above
2. Configure environment variables in Vercel dashboard
3. Set up custom domain (optional)

Manual Deployment

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

# Set environment variables
vercel env add NEXTAUTH_SECRET
vercel env add CLAUDE_API_KEY
# ... add other required variables

🔒 Security

• Environment Variables - Sensitive data stored securely
• NextAuth.js - Industry-standard authentication
• CORS Protection - Cross-origin request filtering
• Rate Limiting - API abuse prevention
• Input Validation - SQL injection protection

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🙏 Acknowledgments

• Claude Code CLI - AI-powered development
• Cursor IDE - AI code editor
• v0 - AI component generation
• Next.js - React framework
• Vercel - Deployment platform

---

Built with ❤️ using Next.js, v0, and Vercel