Gemini CLI Web UI

A desktop and mobile UI for Gemini CLI, Google's official CLI for AI-assisted coding. You can use it locally or remotely to view your active projects and sessions in Gemini CLI and make changes to them the same way you would do it in Gemini CLI. This gives you a proper interface that works everywhere.

Chat View Main interface showing project overview and chat

Setting Setting

Chat View Gemini CLI UI Diagram

Updates to Gemini CLI Web UI

Monaco Code Editor for editing files in Gemini CLI UI
Spec File Generation

• Responsive Design - Works seamlessly across desktop, tablet, and mobile so you can also use Gemini CLI from mobile
• Interactive Chat Interface - Built-in chat interface for seamless communication with Gemini CLI
• Integrated Shell Terminal - Direct access to Gemini CLI through built-in shell functionality
• File Explorer - Interactive file tree with syntax highlighting and live editing
• Git Explorer - View, stage and commit your changes. You can also switch branches
• Session Management - Resume conversations, manage multiple sessions, and track history
• Model Selection - Choose from multiple Gemini models including Gemini 2.5 Pro
• YOLO Mode - Skip confirmation prompts for faster operations (use with caution)

• Node.js v20 or higher
• Gemini CLI installed and configured

1. Clone the repository:

git clone https://github.com/ssdeanx/Gemini-CLI-Web.git cd gemini-cli-web

2. Install dependencies:

npm install

3. Configure environment:

cp .env.example .env # Edit .env with your preferred settings

Note: The .env file has been removed for security. Always copy .env.example to .env when using and modify settings as needed.

4. Start the application:

# Development mode (with hot reload) npm run dev

The application will start at the port you specified in your .env

5. Open your browser:
   • Development: http://localhost:4009

🔒 Important Notice: All Gemini CLI tools are disabled by default. This prevents potentially harmful operations from running automatically.

To use Gemini CLI's full functionality, you'll need to manually enable tools:

1. Open Tools Settings - Click the gear icon in the sidebar
2. Enable Selectively - Turn on only the tools you need
3. Apply Settings - Your preferences are saved locally

YOLO mode ("You Only Live Once") is equivalent to Gemini CLI's --yolo flag, skipping all confirmation prompts. This mode speeds up your work but should be used with caution.

Recommended approach: Start with basic tools enabled and add more as needed. You can always adjust these settings later.

The UI automatically discovers Gemini CLI projects from ~/.gemini/projects/ and provides:

• Visual Project Browser - All available projects with metadata and session counts
• Project Actions - Rename, delete, and organize projects
• Smart Navigation - Quick access to recent projects and sessions

• Use responsive chat or Gemini CLI - You can either use the adapted chat interface or use the shell button to connect to Gemini CLI
• Real-time Communication - Stream responses from Gemini with WebSocket connection
• Session Management - Resume previous conversations or start fresh sessions
• Message History - Complete conversation history with timestamps and metadata
• Multi-format Support - Text, code blocks, and file references
• Image Upload - Upload and ask questions about images in chat

• Interactive File Tree - Browse project structure with expand/collapse navigation
• Live File Editing - Read, modify, and save files directly in the interface
• Syntax Highlighting - Support for multiple programming languages
• File Operations - Create, rename, delete files and directories

• Visualize Changes - See current changes in real-time
• Stage and Commit - Create Git commits directly from the UI
• Branch Management - Switch and manage branches

• Session Persistence - All conversations automatically saved
• Session Organization - Group sessions by project and timestamp
• Session Actions - Rename, delete, and export conversation history
• Cross-device Sync - Access sessions from any device

• Responsive Design - Optimized for all screen sizes
• Touch-friendly Interface - Swipe gestures and touch navigation
• Mobile Navigation - Bottom tab bar for easy thumb navigation
• Adaptive Layout - Collapsible sidebar and smart content prioritization
• Add to Home Screen - Add a shortcut to your home screen and the app will behave like a PWA

• Monaco Editor - Advanced code editor with syntax highlighting and live editing
• Code Completion - Autocomplete features for code snippets and functions
• Syntax Highlighting - Highlighting of different programming languages
• Live Editing - Edit code directly in the editor
• Code Folding - Collapse and expand code blocks for better readability
• Chat Modal - Chat mode that can interact with the Monaco Editor

• Spec File Generation - Generate design, requirements, and tasks files
• Design File Generation - Generate design files for UI
• Requirements File Generation - Generate requirements files for testing
• Tasks File Generation - Generate tasks files for automation
• User Input - User input is used to generate the spec files
• Retry and Save - Retry and save the generated spec files
• Save Spec Files - Save the generated spec files, in the project spec folder
• Use Spec Files - Use the generated spec files in Gemini CLI for further development, features, and more.

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Frontend │ │ Backend │ │ Gemini CLI │ │ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │ └─────────────────┘ └─────────────────┘ └─────────────────┘

• Express Server - RESTful API with static file serving (Port: 4008)
• WebSocket Server - Communication for chats and project refresh
• Gemini CLI Integration - Process spawning and management
• Session Management - JSONL parsing and conversation persistence
• File System API - Exposing file browser for projects
• Authentication System - Secure login and session management (SQLite database: geminicliui_auth.db)

• React 18 - Modern component architecture with hooks
• CodeMirror - Advanced code editor with syntax highlighting
• Tailwind CSS - Utility-first CSS framework
• Responsive Design - Mobile-first approach

• API Server: Port 4008 (default)
• Frontend Dev Server: Port 4009 (default)
• These ports can be changed in the .env file

• Database File: server/database/geminicliui_auth.db
• Database Type: SQLite 3
• Initialization: Automatically created and initialized on server startup

Table Name: geminicliui_users

Indexes:

• idx_geminicliui_users_username: For fast username lookups
• idx_geminicliui_users_active: For filtering active users

1. On first server startup, database file is automatically created if it doesn't exist
2. Table structure is loaded from server/database/init.sql
3. First access displays user registration screen
4. First user is registered as administrator

• Passwords are hashed with bcrypt before storage
• JWT token-based authentication system
• Session management with timeout functionality
• SQL injection protection (prepared statements used)

Problem: The UI shows no projects or empty project list Solutions:

• Ensure Gemini CLI is properly installed
• Run gemini command in at least one project directory to initialize
• Verify ~/.gemini/projects/ directory exists and has proper permissions

Problem: Files not loading, permission errors, empty directories Solutions:

• Check project directory permissions (ls -la in terminal)
• Verify the project path exists and is accessible
• Review server console logs for detailed error messages
• Ensure you're not trying to access system directories outside project scope

Problem: Selected model is not being used Solutions:

• After selecting a model in settings, make sure to click "Save Settings"
• Clear browser local storage and reconfigure
• Verify the model name is displayed correctly in the chat interface

This section outlines the planned enhancements and features to be implemented in future releases, focusing on improving user experience, agent capabilities, and overall system performance.

GNU General Public License v3.0 - see LICENSE file for details.

This project is open source and free to use, modify, and distribute under the GPL v3 license.

This project is based on Claude Code UI (GPL v3.0) with customizations.

graph TD subgraph User A[User] end subgraph Browser (Frontend) subgraph "React UI Components" App(App.jsx) MainContent(MainContent.jsx) Sidebar(Sidebar.jsx) ChatInterface(ChatInterface.jsx) EditorTab(EditorTab.jsx) GitPanel(GitPanel.jsx) Shell(Shell.jsx) ChatSidebar(ChatSidebar.jsx) CodeEditor(CodeEditor.jsx) CodeTabs(CodeTabs.jsx) DarkModeToggle(DarkModeToggle.jsx) EditorFileTree(EditorFileTree.jsx) ErrorBoundary(ErrorBoundary.jsx) FileTree(FileTree.jsx) GeminiLogo(GeminiLogo.jsx) GeminiStatus(GeminiStatus.jsx) ImageViewer(ImageViewer.jsx) LoginForm(LoginForm.jsx) MicButton(MicButton.jsx) MobileNav(MobileNav.jsx) NewCodeEditor(NewCodeEditor.jsx) ProtectedRoute(ProtectedRoute.jsx) QuickSettingsPanel(QuickSettingsPanel.jsx) SetupForm(SetupForm.jsx) TodoList(TodoList.jsx) ToolsSettings(ToolsSettings.jsx) SpecDesign(SpecDesign.jsx) ProgressIndicator(ProgressIndicator.jsx) ThinkingIndicator(ThinkingIndicator.jsx) badge(badge.jsx) button(button.jsx) input(input.jsx) scroll_area(scroll-area.jsx) end subgraph "Contexts" AuthContext(AuthContext.jsx) ThemeContext(ThemeContext.jsx) SettingsContext(SettingsContext.jsx) end subgraph "Hooks" useWebSocket(useWebSocket.js) useAudioRecorder(useAudioRecorder.js) useVersionCheck(useVersionCheck.js) end subgraph "Utils" api(api.js) notificationSound(notificationSound.js) whisper(whisper.js) lib_utils(utils.js) end end subgraph "Node.js Server (Backend)" ExpressServer(Express Server) WebSocketServer(WebSocket Server) GeminiCLIBridg(Gemini CLI Bridge) SessionManager(Session Manager) AuthLayer(Auth Layer) GitAPI(Git API) end subgraph "Local System" GeminiCLIProcess(Gemini CLI Process) ProjectFiles(Project Files) GitRepository(Git Repository) SQLiteDB(SQLite DB) GeminiConfigFiles(gemini config files) end subgraph "External Services" OpenAIWhisperAPI(OpenAI Whisper API) end A -- Interacts --> App App --> MainContent App --> Sidebar App --> DarkModeToggle App --> ErrorBoundary App --> MobileNav App --> ProtectedRoute App --> useVersionCheck MainContent --> ChatInterface MainContent --> EditorTab MainContent --> GitPanel MainContent --> Shell MainContent --> ChatSidebar MainContent --> ImageViewer MainContent --> TodoList MainContent --> SpecDesign Sidebar --> FileTree Sidebar --> GeminiLogo Sidebar --> QuickSettingsPanel Sidebar --> ToolsSettings Sidebar --> api ChatInterface --> CodeEditor ChatInterface --> GeminiStatus ChatInterface --> MicButton ChatInterface --> useWebSocket ChatInterface --> api ChatInterface --> notificationSound EditorTab --> CodeTabs EditorTab --> EditorFileTree EditorTab --> NewCodeEditor SpecDesign --> ProgressIndicator SpecDesign --> ThinkingIndicator AuthContext --> LoginForm AuthContext --> SetupForm MicButton --> useAudioRecorder useAudioRecorder --> whisper App --> AuthContext App --> ThemeContext App --> SettingsContext App --> useWebSocket api --> ExpressServer useWebSocket --> WebSocketServer ExpressServer --> GeminiCLIBridg WebSocketServer --> GeminiCLIBridg ExpressServer --> AuthLayer ExpressServer --> GitAPI ExpressServer --> ProjectFiles ExpressServer --> OpenAIWhisperAPI GeminiCLIBridg --> SessionManager GeminiCLIBridg --> GeminiCLIProcess AuthLayer --> SQLiteDB GitAPI --> GitRepository SessionManager --> GeminiConfigFiles GeminiCLIProcess --> ProjectFiles end 

Major Changes:

• Adapted from Claude CLI to Gemini CLI
• Added authentication system (SQLite-based)
• Gemini-specific model selection feature
• Enhanced Japanese language support
• UI adjustments and Gemini branding

Thanks to the original Claude Code UI project.

• Gemini CLI - Google's official CLI
• React - User interface library
• Vite - Fast build tool and dev server
• Tailwind CSS - Utility-first CSS framework
• CodeMirror - Advanced code editor
• Gemini CLI UI - Orginal project

• Star this repository to show support
• Watch for updates and new releases
• Follow the project for announcements