# claude-code-session-gui

**Repository Path**: ctllin/claude-code-session-gui

## Basic Information

- **Project Name**: claude-code-session-gui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code GUI

给 Claude Code 用的本地 Web 界面：管会话、清缓存、管 MCP、管插件、管 Skill。Vue 3 + Vite，`npm run dev` 即可打开。

> 截图占位：启动后默认进入「会话」页，顶栏切换五个标签。

## 快速开始

```bash
npm install
npm run dev
```

浏览器打开 http://127.0.0.1:5273 。服务绑在 `0.0.0.0` 上，**同一局域网内的其它设备也能访问**（`vite.config.ts` 里 `allowedHosts: true`）。它没有登录、没有 token，所以任何能连到这个端口的设备都能操作你的会话和配置——只在可信网络里开。想只给本机用，把 `host` 改回 `'127.0.0.1'`。

其他命令：

```bash
npm test           # Vitest 全量测试
npm run typecheck  # vue-tsc 类型检查
npm run build      # 构建到 dist/
```

## 它是什么，不是什么

**只做开发态工具**，不是常驻服务。前端和 API 都由 Vite dev server 的中间件提供（`vite.config.ts` 里的 `apiPlugin` 把 `/api` 挂到 `server/http/handle.ts`），关掉进程就没有了。没有端口守护、没有 systemd 单元、没有认证——它假定只有你自己在本机用。

`npm run build` 出来的 `dist/` 只有前端静态资源，**不含 API**：脱离 dev server 它就是一堆打不开数据的页面。想要打包分发得另外上 Node 服务端，当前没做。

## 五个模块

| 标签 | 做什么 |
| --- | --- |
| 会话 | 列出 `~/.claude/projects/` 下所有会话，按项目分组、支持搜索；重命名（写 alias）、打标签、批量删除进回收站、还原、清空回收站。还能生成「新建会话」的 `cd … && claude` 命令供复制。 |
| 缓存 | 统计 `~/.claude/` 各分类占用（projects / temp-clones / shell-snapshots / paste-cache / file-history / backups），勾选后清理。projects 一项不可勾选——那里是会话语料，请回会话页管理。 |
| MCP | 列出 user / project / local 三个 scope 的 MCP server，健康探测、启用/禁用、添加（写 JSON 配置）、移除、登出。响应里的 `env` / `headers` 一律脱敏成 `***`。 |
| 插件 | 「已安装 / 可安装」两个子页；启停、更新、卸载、安装。顶部管理 marketplace（添加 URL 或本地路径、更新、移除）。所有写操作都调 `claude plugin …`。 |
| Skill | 管理源目录池，扫描其中的 `SKILL.md`；一键启用/禁用（在 `~/.claude/skills/` 建/删符号链接），清理断链，接管已有链接。 |

## 数据落在哪

- `~/.claude-gui/` — GUI 自己的状态目录：
  - `session-meta.json`：会话别名与标签
  - `managed-links.json`：本工具创建（或接管）的 skill 符号链接清单
  - `skills-sources.json`：skill 源目录池
  - `trash/`：回收站
- `~/.claude/` — Claude Code 自己的目录。GUI 只在两种情况碰它：调用官方 CLI（`claude mcp …`、`claude plugin …`），或者执行你明确确认过的操作（移动会话进回收站、建立 skill 符号链接）。

## 安全与可逆性

**删除是软删除。** 会话被移进 `~/.claude-gui/trash/`，随时可以还原，原路径冲突时会拒绝还原并提示冲突（HTTP 409）。

**回收站保留 30 天。** 超过 30 天的条目在你下次打开回收站列表时被自动彻底删除，多出来的设置项没必要。

**「清空回收站」不可撤销**，必须原样输入确认词「清空回收站」。**「清理缓存」同样不可撤销**——它会真的删掉 `~/.claude/` 下被勾中的目录。除这两处之外，破坏性操作都能回退。

同一批里发现某个会话「可能正在运行」（两分钟内有写入，或 `~/.claude/sessions/` 里出现它的运行文件），会先跳过并告诉你原因，然后问一次要不要强制移入回收站。

## 实现约束

给打算改这份代码的人：

- 所有外部命令走 `execFile('claude', args)`，参数是数组，`shell: false`。不要改成拼接字符串。
- 任何用户提供的路径片段（sessionId、skill 名、回收站 entryId）先过 `assertSafeSegment` / `resolveSafe`，越界直接 400。
- API 响应里不得出现 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、MCP 的 `env` / `headers` 值。
- `server/` 不许 import `vite`——它要能在纯 Node 下跑测试。

## 测试

`tests/server/`（node 环境，真实临时 home）覆盖会话扫描、回收站、缓存、MCP、插件、skill 链接、HTTP 路由，以及 `e2e.test.ts` 里一条完整链路：列表 → 重命名 → 删除 → 回收站 → 还原，并断言全程响应不含 `sk-` 前缀的凭据。

`tests/src/`（纯 TS 单测）覆盖前端的工具函数。