Gemini CLI 的桌面和移动界面，它是 Google 官方提供的 AI 辅助编程命令行工具。您可以在本地或远程使用它来查看 Gemini CLI 中的活动项目和会话，并以与在 Gemini CLI 中相同的方式对其进行修改。这为您提供了一个可在任何地方使用的完善界面。

截图

功能

• 响应式设计 - 在桌面、平板和手机上都能无缝运行，因此您也可以在手机上使用 Gemini CLI
• 交互式聊天界面 - 内置聊天界面，可与 Gemini CLI 无缝沟通
• 集成的 Shell 终端 - 通过内置的 shell 功能直接访问 Gemini CLI
• 文件管理器 - 带语法高亮和实时编辑功能的交互式文件树
• Git 管理器 - 查看、暂存并提交您的更改。您还可以切换分支
• 会话管理 - 恢复对话、管理多个会话并跟踪历史记录
• 模型选择 - 可从包括 Gemini 2.5 Pro 在内的多个 Gemini 模型中进行选择
• YOLO 模式 - 跳过确认提示以加快操作速度（请谨慎使用）

快速入门

先决条件

• Node.js v20 或更高版本
• 已安装并配置好 Gemini CLI

安装

1. 克隆仓库：

git clone https://github.com/cruzyjapan/Gemini-CLI-UI.git
cd Gemini-CLI-UI

2. 安装依赖：

npm install

3. 配置环境：

cp .env.example .env
# 根据您的偏好编辑 .env 文件

注意：出于安全考虑，已移除 .env 文件。使用时请务必复制 .env.example 到 .env，并根据需要修改设置。

4. 启动应用：

# 开发模式（支持热重载）
npm run dev

应用程序将按照您在 .env 文件中指定的端口启动。

5. 打开浏览器：
   • 开发环境：http://localhost:4009

安全与工具配置

🔒 重要提示：所有 Gemini CLI 工具默认处于禁用状态。这可以防止潜在的有害操作自动运行。

启用工具

要使用 Gemini CLI 的全部功能，您需要手动启用工具：

1. 打开工具设置 - 点击侧边栏中的齿轮图标
2. 选择性启用 - 仅开启您需要的工具
3. 应用设置 - 您的偏好将被本地保存

关于 YOLO 模式

YOLO 模式（“You Only Live Once”）相当于 Gemini CLI 的 --yolo 标志，可跳过所有确认提示。此模式可加快您的工作速度，但应谨慎使用。

建议做法：先启用基本工具，然后根据需要逐步添加更多工具。您随时可以调整这些设置。

使用指南

核心功能

项目管理

该界面会自动从 ~/.gemini/projects/ 中发现 Gemini CLI 项目，并提供：

• 可视化项目浏览器 - 所有可用项目及其元数据和会话数量
• 项目操作 - 重命名、删除和整理项目
• 智能导航 - 快速访问最近的项目和会话

聊天界面

• 使用响应式聊天或 Gemini CLI - 您可以选择使用适配后的聊天界面，或点击 shell 按钮连接到 Gemini CLI
• 实时通信 - 通过 WebSocket 连接流式传输来自 Gemini 的回复
• 会话管理 - 恢复之前的对话或开始新的会话
• 消息历史 - 包含时间戳和元数据的完整对话历史
• 多格式支持 - 文本、代码块和文件引用
• 图片上传 - 在聊天中上传图片并提问

文件管理器与编辑器

• 交互式文件树 - 浏览项目结构，支持展开/折叠导航
• 实时文件编辑 - 直接在界面中读取、修改和保存文件
• 语法高亮 - 支持多种编程语言
• 文件操作 - 创建、重命名、删除文件和目录

Git 管理器

• 可视化更改 - 实时查看当前更改
• 暂存与提交 - 直接从界面创建 Git 提交
• 分支管理 - 切换和管理分支

会话管理

• 会话持久化 - 所有对话都会自动保存
• 会话组织 - 按项目和时间戳对会话进行分组
• 会话操作 - 重命名、删除和导出对话历史
• 跨设备同步 - 可从任何设备访问会话

移动应用

• 响应式设计 - 针对所有屏幕尺寸优化
• 触控友好界面 - 滑动手势和触控导航
• 移动端导航 - 底部标签栏便于拇指操作
• 自适应布局 - 折叠侧边栏和智能内容优先级排序
• 添加到主屏幕 - 将快捷方式添加到主屏幕后，应用将表现得像 PWA 一样

架构

系统概述

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端          │    │   后端          │    │  Gemini CLI     │
│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  集成           │
└─────────────────┘    └─────────────────┘    └─────────────────┘

后端（Node.js + Express）

• Express 服务器 - 提供 RESTful API 和静态文件服务（端口：4008）
• WebSocket 服务器 - 用于聊天和项目刷新的通信
• Gemini CLI 集成 - 进程创建和管理
• 会话管理 - JSONL 解析和对话持久化
• 文件系统 API - 向用户暴露项目文件浏览器
• 认证系统 - 安全登录和会话管理（SQLite 数据库：geminicliui_auth.db）

前端（React + Vite）

• React 18 - 使用 hooks 的现代组件架构
• CodeMirror - 具有语法高亮功能的高级代码编辑器
• Tailwind CSS - 基于实用程序的 CSS 框架
• 响应式设计 - 以移动设备为先的设计方法

配置详情

端口设置

• API 服务器：端口 4008（默认）
• 前端开发服务器：端口 4009（默认）
• 这些端口可以在 .env 文件中更改

数据库配置

初始设置与表结构

• 数据库文件: server/database/geminicliui_auth.db
• 数据库类型: SQLite 3
• 初始化: 服务器启动时自动创建并初始化

用户表详情

表名: geminicliui_users

列名	数据类型	约束	描述
id	INTEGER	主键自增	唯一用户标识符
username	TEXT	唯一，非空	登录用户名（推荐使用邮箱）
password_hash	TEXT	非空	bcrypt 加密后的密码哈希值
created_at	DATETIME	默认当前时间戳	账户创建时间戳
last_login	DATETIME	可为空	最后登录时间戳
is_active	BOOLEAN	默认 1	账户启用/禁用状态

索引:

• idx_geminicliui_users_username: 用于快速查找用户名
• idx_geminicliui_users_active: 用于筛选活跃用户

首次运行设置

1. 服务器首次启动时，若数据库文件不存在，则会自动创建。
2. 表结构从 server/database/init.sql 中加载。
3. 首次访问时会显示用户注册界面。
4. 第一个注册的用户将被设为管理员。

安全特性

• 密码在存储前使用 bcrypt 进行哈希处理。
• 基于 JWT 的认证系统。
• 具有超时功能的会话管理。
• SQL 注入防护（使用预处理语句）。

故障排除

常见问题及解决方案

“未找到 Gemini 项目”

问题: 界面显示无项目或项目列表为空。 解决方案:

• 确保 Gemini CLI 已正确安装。
• 至少在一个项目目录中运行 gemini 命令以进行初始化。
• 检查 ~/.gemini/projects/ 目录是否存在且权限正确。

文件浏览器问题

问题: 文件无法加载、权限错误、目录为空。 解决方案:

• 检查项目目录权限（在终端中运行 ls -la）。
• 确认项目路径存在且可访问。
• 查看服务器控制台日志以获取详细错误信息。
• 确保未尝试访问项目范围之外的系统目录。

模型选择无效

问题: 选择的模型未生效。 解决方案:

• 在设置中选择模型后，请务必点击“保存设置”。
• 清除浏览器本地存储并重新配置。
• 确认聊天界面中正确显示所选模型名称。

许可证

GNU 通用公共许可证 v3.0 - 详情请参阅 LICENSE 文件。

本项目为开源项目，可在 GPL v3 许可证下自由使用、修改和分发。

原始项目

本项目基于 Claude Code UI（GPL v3.0），并进行了定制化开发。

主要改动:

• 由 Claude CLI 改为 Gemini CLI。
• 添加了基于 SQLite 的认证系统。
• 引入了 Gemini 特有的模型选择功能。
• 增强了对日语的支持。
• 对 UI 进行了调整，并加入了 Gemini 品牌元素。

感谢原始的 Claude Code UI 项目。

致谢

使用的技术

• Gemini CLI - Google 官方 CLI
• React - 用户界面库
• Vite - 快速构建工具及开发服务器
• Tailwind CSS - 实用优先的 CSS 框架
• CodeMirror - 高级代码编辑器

支持与社区

关注最新动态

• 点赞此仓库以表示支持。
• 关注以获取更新和新版本发布。
• 关注项目以接收相关公告。

---

Gemini-CLI-UI 快速上手指南

Gemini-CLI-UI 是一个专为 Google 官方 AI 编程助手 Gemini CLI 设计的桌面与移动端图形界面。它允许你通过浏览器直观地管理项目、进行对话聊天、编辑代码文件以及操作 Git，同时支持本地或远程部署。

环境准备

在开始之前，请确保你的系统满足以下要求：

• Node.js: 版本 v20 或更高。
  • 国内用户建议：可使用 cnpm 或配置 npm 镜像源加速下载。
  • 检查版本：node -v
• Gemini CLI: 必须已安装并完成基础配置。
  • 确保已在终端运行过 gemini 命令至少一次，以初始化项目目录 (~/.gemini/projects/)。
• Git: 用于克隆仓库及管理项目版本控制。

安装步骤

1. 克隆项目仓库

git clone https://github.com/cruzyjapan/Gemini-CLI-UI.git
cd Gemini-CLI-UI

2. 安装依赖

建议使用国内镜像源加速安装过程：

# 使用 npm 原生配置淘宝镜像
npm install --registry=https://registry.npmmirror.com

3. 配置环境变量

复制示例配置文件并修改所需设置（如端口号等）：

cp .env.example .env

注意：出于安全考虑，项目中不包含默认的 .env 文件。请务必执行上述复制操作，并根据需要编辑 .env 文件。

4. 启动应用

以开发模式启动（支持热重载）：

npm run dev

应用将在 .env 文件中指定的端口启动（默认为前端 4009，后端 API 4008）。

基本使用

1. 访问界面

打开浏览器访问：

http://localhost:4009

首次运行时，系统将自动创建 SQLite 数据库并要求你注册管理员账号。

2. 核心功能概览

• 项目浏览：界面会自动扫描 ~/.gemini/projects/ 下的所有 Gemini 项目，点击即可进入。
• 智能对话：
  • 直接在聊天框输入指令与 Gemini 交互。
  • 支持上传图片进行分析。
  • 可切换不同的 Gemini 模型（如 Gemini 2.5 Pro）。
• 文件与 Git 管理：
  • 左侧文件树支持实时查看、编辑和保存代码（带语法高亮）。
  • Git 面板可查看变更、暂存文件、提交代码及切换分支。
• 工具权限控制（重要）：
  • 出于安全考虑，所有 Gemini CLI 工具默认禁用。
  • 点击侧边栏齿轮图标进入设置，按需开启特定工具（如文件写入、终端执行等）。
  • YOLO 模式：开启后可跳过确认提示以加快操作速度，请谨慎使用。

3. 移动端适配

该界面采用响应式设计，可直接在手机浏览器中使用。你也可以选择“添加到主屏幕”，将其作为 PWA（渐进式 Web 应用）安装，获得类似原生 App 的体验。