A modern web interface for Claude AI code assistant
Claudex GUI is a web-based interface for interacting with Claude AI as a code assistant. Built with Next.js and integrated with the Claude Agent SDK, it provides a seamless experience for AI-powered code development, analysis, and collaboration.
- Real-time streaming responses from Claude AI
- Support for multiple Claude models (Opus, Sonnet, Haiku)
- Agent and Plan modes for different workflows
- Extended thinking mode for complex problems
- Markdown rendering with syntax highlighting
- Code block theme adaptation (light/dark)
- Tool execution visualization (Bash, file operations)
- Clickable local file references
- Sticky user messages for easy context tracking
- Local project folder integration
- Multi-project support with history
- Git information display (branch, commit hash)
- Session persistence and resumption
- Clean, minimalist design inspired by 1Code
- Light and dark theme support
- Responsive layout with custom scrollbars
- Smooth animations and transitions
- Keyboard shortcuts (Enter to send, Shift+Enter for newline)
- Token usage tracking and cost estimation
- Slash commands for quick actions
- Model selector with thinking toggle
- Message history management
- Context indicator
- Node.js 18+ or Bun
- Claude API key (or compatible API endpoint)
- @anthropic-ai/claude-code package (required for Claude Agent SDK)
# Install Claude Code globally (required)
npm install -g @anthropic-ai/claude-code
# Install Claudex GUI
npm install -g claudex-gui
# Run the application
claudex-guiOn first run, you'll be prompted to enter your ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN).
The application will:
- Check for required dependencies
- Build the Next.js application (first run only)
- Find an available port (starting from 3000)
- Start the server at
http://localhost:PORT
You can set these in your shell profile or in ~/.claudex-gui/.env.local:
ANTHROPIC_API_KEY=your_api_key_here
# or
ANTHROPIC_AUTH_TOKEN=your_auth_token_here
# Optional: specify port
PORT=3000- Select a Project: Enter a local project path or browse for a folder
- Start Chatting: Ask Claude about your code, request changes, or get explanations
- Review Changes: View tool execution results and file modifications in real-time
- Track Progress: Monitor token usage and session information in the header
claudex-gui # Start the web server
claudex-gui --setup # Reconfigure API key
claudex-gui --help # Show help message- Framework: Next.js 15 (App Router) + React 19
- Language: TypeScript
- Styling: Tailwind CSS v4
- Database: SQLite + Drizzle ORM
- API: tRPC for type-safe client-server communication
- AI: Claude Agent SDK (@anthropic-ai/claude-agent-sdk)
- UI Components: Radix UI primitives
- Animations: Framer Motion
claudex-gui/
├── app/
│ ├── api/
│ │ ├── trpc/[trpc]/ # tRPC endpoints
│ │ └── claude/stream/ # Claude SSE streaming
│ ├── chat/[projectPath]/ # Chat interface
│ └── page.tsx # Home page
├── components/
│ ├── chat/ # Chat UI components
│ │ ├── chat-header.tsx # Project info header
│ │ ├── chat-input.tsx # Message input
│ │ ├── messages-list.tsx # Message display
│ │ └── chat-markdown-renderer.tsx
│ └── ui/ # Reusable UI components
├── lib/
│ ├── db/ # Database schema & utils
│ ├── trpc/ # tRPC routers
│ │ └── routers/
│ │ ├── projects-simple.ts
│ │ ├── chats-simple.ts
│ │ ├── claude-simple.ts
│ │ ├── git.ts
│ │ └── external.ts
│ └── claude/
│ ├── env.ts # Claude environment config
│ ├── transform.ts # Message transformers
│ └── use-claude-stream.ts # React streaming hook
└── drizzle/ # Database migrations
- User Input → ChatInput component
- Message Cleaning → Remove excessive newlines
- Stream Request →
/api/claude/stream(SSE) - Claude SDK → Process with tools and context
- Transform → Convert SDK events to UI chunks
- Render → Display in MessagesList with markdown
// Projects: Local folder references
projects {
id, name, path, gitRemoteUrl, gitProvider, gitOwner, gitRepo
}
// Chats: Conversation sessions
chats {
id, name, projectId, worktreePath, branch, prUrl
}
// Sub-chats: Individual message threads
subChats {
id, name, chatId, sessionId, mode, messages (JSON)
}# Development
bun run dev # Start dev server with hot reload
# Database
bun run db:generate # Generate migrations from schema
bun run db:push # Push schema changes (dev only)
bun run db:studio # Open Drizzle Studio
# Build
bun run build # Build for production
bun run start # Start production server
# Linting
bun run lint # Run ESLint# Required
ANTHROPIC_API_KEY=your_api_key_here
# Optional
DATABASE_PATH=~/.claudex/data/agents.db # Custom database location- New tRPC Router: Add to
lib/trpc/routers/and register inrouter.ts - New UI Component: Add to
components/with TypeScript types - Database Changes: Update
lib/db/schema/index.tsand runbun run db:generate - Claude Tools: Extend in
lib/claude/env.tstool definitions
Users can switch between Claude models in the chat interface:
- Opus 4.6: Most capable, best for complex tasks
- Sonnet 4.6: Balanced performance and speed
- Haiku 4.5: Fastest, best for simple queries
- Agent Mode: Full autonomy with tool execution
- Plan Mode: Read-only analysis and planning
Enable extended thinking for complex reasoning tasks (increases token usage).
"No ANTHROPIC_API_KEY found"
- Set the environment variable in
.env.local - Restart the development server
"Failed to open file"
- Ensure the project path is absolute and exists
- Check file permissions
Database errors
- Delete
~/.claudex/data/agents.dbto reset - Run
bun run db:pushto recreate schema
Streaming not working
- Check browser console for errors
- Verify API key is valid
- Ensure network connection is stable
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Made with ❤️ for developers who love AI-assisted coding