Gemini-CLI-UI: A Web Interface for the Google Gemini CLI Coding Assistant

Gemini-CLI-UI provides a clean, responsive web interface for Google’s Gemini CLI. It moves the AI coding experience beyond the terminal, offering a visual dashboard to manage active projects, track sessions, and modify code with the same power as the original CLI but with improved accessibility.

The interface is designed for desktops, tablets, and smartphones. Mobile users benefit from touch optimizations and gesture support. You can also add the application to your home screen, where it functions as a lightweight Progressive Web App (PWA).

Coding Features

• Integrated Chat: Communicate directly with the Gemini CLI for real-time coding assistance.
• Embedded Terminal: Gain full shell access through the integrated terminal window.
• Visual Input: Upload images to the interface to ask Gemini questions about visual assets or diagrams.

File & Version Control

• File Browser: Navigate your project via an interactive tree view with built-in syntax highlighting. Create, rename, or delete files and folders, and perform live edits directly in the browser.
• Git Integration: Monitor changes, stage files, commit updates, and switch between branches without leaving the UI.

Sessions & Models

• Session Management: Resume previous chats, manage multiple concurrent sessions, and track your interaction history. Sessions are organized by project and timestamp and synchronized across all your devices.
• Model Selection: Switch between various Gemini models, including Gemini 1.5 Pro (and subsequent releases).
• YOLO Mode: A specialized mode that bypasses all confirmation prompts to accelerate your workflow. This feature should be used with caution.

Security

• Strict Permissions: All Gemini CLI tools are disabled by default; you only enable the specific features you require.
• Authentication: Uses a SQLite-based authentication system featuring bcrypt-hashed passwords.
• Protection: Includes JWT tokens, session timeouts, and built-in protection against SQL injection.

Quick Start

Prerequisites: Node.js v20 or higher and a configured installation of the Gemini CLI.

Installation Steps:

1. Clone the repository:

   git clone [email protected]:cruzyjapan/Gemini-CLI-UI.git
   cd geminicliui
   

2. Install dependencies:

   npm install
   

3. Configure the environment:

   cp .env.example .env
   # Edit .env to match your local configuration
   

   Note: The .env file is excluded from the repository for security. Ensure you copy it from .env.example before proceeding.

4. Launch the application:

   # Start in development mode with hot-reloading
   npm run dev
   

5. Access the UI: Open your browser to http://localhost:4009 (the default port can be modified in your .env file).

Architecture

The application is built on three core components:

• Frontend (React + Vite): Handles the chat interface, file editor, and all visual elements.
• Backend (Express + WebSocket): Manages REST APIs, real-time messaging, and Gemini CLI integration.
• Gemini CLI: The underlying AI coding engine developed by Google.

Backend Details (Node.js + Express)

• Serves the REST API and static files on port 4008 by default.
• Utilizes a WebSocket server for chat updates and project refreshing.
• Orchestrates Gemini CLI processes.
• Manages sessions, the file system API, and user authentication via the geminicliui_auth.db SQLite database.

Frontend Details (React + Vite)

• Powered by React 18 using modern hooks.
• Features the CodeMirror editor for robust syntax highlighting.
• Styled with Tailwind CSS for a mobile-first, responsive design.
• Runs on port 4009 by default (configurable via .env).

Database Configuration

• File Path: server/database/geminicliui_auth.db
• Type: SQLite 3
• Initialization: The database is automatically generated when the server first starts.

User Table Structure (geminicliui_users):

The database includes two indexes: idx_geminicliui_users_username for optimized lookups and idx_geminicliui_users_active for filtering active users.

Troubleshooting

No Gemini project found

• Ensure the Gemini CLI is installed and accessible in your system path.
• Run the gemini command at least once within your project directory to initialize it.
• Verify that the ~/.gemini/projects/ directory exists and has the correct read/write permissions.

File browser issues

• Verify the permissions of your project directory using ls -la in the terminal.
• Confirm the project path is valid and readable by the Node.js process.
• Review the server console logs for specific error messages.
• Note: For security reasons, the browser cannot access system directories outside of the designated project folder.

Model selection does not persist

• After selecting a new model in the settings menu, ensure you click "Save settings."
• If issues persist, clear your browser’s local storage and reconfigure.
• Confirm that the desired model name is correctly displayed in the main chat interface.