A Node.js web application that provides a browser-based interface for managing Claude Code CLI projects. Specifically optimized for Raspberry Pi environments with a simplified interface focused on project selection and terminal interaction.
- 🌐 Web-based Interface: Browser-based interface for Claude Code CLI management
- 🖥️ Terminal Integration: Real-time terminal interface using xterm.js
- 📁 Project Management: Easy project selection and management
- 🔄 Real-time Communication: WebSocket-based real-time updates
- 🍓 Raspberry Pi Optimized: Lightweight and optimized for ARM devices
- 🔒 Optional Authentication: Configurable authentication system
- 📊 System Monitoring: Built-in system information and status monitoring
- Node.js 18.0.0+
- NPM 8.0.0+
- Claude Code CLI installed and configured
- Clone the repository:
git clone <repository-url>
cd claudeCodeUi- Install dependencies:
npm install- Start the application:
# Development mode
npm run dev
# Production mode
npm start
# With PM2 process manager (recommended for production)
npm run pm2:start- Open your browser and navigate to:
http://localhost:3000
- Select a Project: Use the sidebar to browse and select your Claude Code projects
- Terminal Interface: Interact with Claude Code CLI through the integrated terminal
- Real-time Updates: All terminal output and project changes are updated in real-time
- Session Management: Multiple terminal sessions are supported with auto-reconnection
Configuration files are located in the config/ directory:
config/default.json- Development configurationconfig/production.json- Production overridesecosystem.config.js- PM2 deployment configuration
Key configuration options:
- Server port and host settings
- Claude executable path
- Authentication settings
- WebSocket timeouts
- Logging levels
For production deployment, use PM2:
# Start with PM2
npm run pm2:start
# Stop PM2 process
npm run pm2:stop
# Restart PM2 process
npm run pm2:restart
# Delete PM2 process
npm run pm2:delete
# View PM2 status
pm2 status- Supported OS: Linux, macOS
- Architecture: ARM64, x64
- Memory: Minimum 256MB RAM (optimized for 128MB on Raspberry Pi)
- Node.js: 18.0.0 or higher
- Browser: Modern browsers with WebSocket support
/api/status- Application health and status/api/projects- Project management operations/api/claude- Claude AI integration endpoints/api/system- System monitoring information
├── server/ # Backend Express.js application
│ ├── app.js # Main application entry
│ ├── socket-handler.js # WebSocket event handling
│ ├── middleware/ # Express middleware
│ ├── routes/ # API route definitions
│ ├── services/ # Core business logic
│ └── utils/ # Utilities and helpers
├── public/ # Frontend static files
│ ├── index.html # Main application page
│ └── assets/ # CSS, JS, and library files
├── config/ # Configuration files
└── logs/ # Application logs
npm run dev # Start development server with nodemon
npm start # Start production server
npm run pm2:start # Start with PM2 process manager- Port already in use: Change the port in
config/default.json - Claude CLI not found: Update the Claude executable path in configuration
- WebSocket connection failed: Check firewall settings and CORS configuration
- Memory issues on Raspberry Pi: Ensure PM2 memory limits are properly configured
Application logs are stored in the logs/ directory:
app.log- General application logserror.log- Error logs only
This project is licensed under the MIT License.
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
For issues and questions, please refer to the project's issue tracker.