CLI Deck

中文 | English

CLI Deck 是一个用于同时运行和管理多个 AI CLI 会话的 Electron 桌面工作台。它把 Codex、Claude Code、OpenCode 或任意自定义 CLI 放在同一个平铺窗口里，并为每个工作目录保存本地项目记忆。

功能特性

• 在应用内启动真实 PTY 终端会话，不依赖抓取外部终端窗口。
• 多 session 自动平铺展示，适合同时跑多个 Codex / Claude / OpenCode 任务。
• 支持自定义 command、arguments、working directory。
• 创建 session 时可选择是否记录到 Memory，适合临时或敏感会话。
• Goal 目标记录：每个工作目录可维护一个一句话目标、任务列表、关联 session 和产出记录，并导出 Markdown。
• session 标题会自动追加当前路径尾部信息，例如 Codex — workspace/tools，长路径只取最后两段。
• 支持 restart、duplicate、rename、copy command、open cwd、close stopped。
• 本地 memory 层：
  • raw terminal log
  • session summary JSON
  • project memory JSON
  • 历史搜索和筛选
  • 项目详情、打开日志、导出 JSON/Markdown、删除项目记忆、清理过期 raw logs
• Settings 面板可配置 presets、默认工作目录、raw log 开关、日志大小和保留天数。

支持平台

当前主要开发和验证环境是 Windows。代码已经支持 macOS / Linux 使用系统 shell 启动 CLI：

• Windows: 使用 powershell.exe
• macOS: 使用 $SHELL，默认 /bin/zsh
• Linux: 使用 $SHELL，默认 /bin/sh

macOS 上建议先按源码方式运行。打包脚本已提供 build:mac 的目录构建目标，但 macOS 打包需要在 macOS 机器上执行。

本地运行

Windows

npm.cmd install
npm.cmd start

如果 Electron 无法写入默认 AppData 目录，可以把运行数据放到项目内：

$env:CLI_DECK_PORTABLE_DATA='1'; npm.cmd start

macOS

先安装 Node.js 20+，然后执行：

npm install
npm start

如果 Codex、Claude Code 或 OpenCode 不在默认 PATH 中，请先确认在普通终端里能直接运行：

codex --version
claude --version
opencode --version

CLI Deck 在 macOS 创建 session 时会通过 $SHELL -lc "<command>" 启动命令，因此会读取你的 shell 登录环境。常见 CLI 路径可放在 ~/.zshrc、~/.zprofile 或你实际使用 shell 的配置文件中。

Linux

npm install
npm start

Linux 使用 $SHELL -lc "<command>" 启动 CLI。请先确认目标 CLI 在普通终端中可直接运行。

构建

Windows 目录版

npm.cmd run build:dir

输出目录：

dist/win-unpacked/CLI Deck.exe

Windows portable / installer

npm.cmd run build

这个目标会使用 NSIS。如果网络无法访问 GitHub，请使用 build:dir，或提前准备 electron-builder 的 NSIS 缓存。

macOS 目录版

需要在 macOS 上执行：

npm run build:mac

输出在 dist/mac* 相关目录中。当前配置是目录构建，适合本地验证；正式分发还需要补充签名、公证和图标配置。

Memory 存储位置

CLI Deck 把会话记忆写在 Electron userData 下，不写入你的源码仓库：

<userData>/memory/
  projects/
    <cwd-hash>.json
  goals/
    <cwd-hash>.json
  sessions/
    <YYYY-MM-DD>/
      <session-id>.log
      <session-id>.json
  exports/
    <project-name>-<hash>.md
    <project-name>-<hash>.json
    <project-name>-goal-<hash>.md

默认策略：

• 单 session raw log 上限 20 MB。
• 普通 raw log 保留 30 天。
• failed session raw log 保留 60 天。
• session JSON summary 和 project memory 会保留。
• Goal 目标记录按工作目录保存，只记录你填写的目标、任务、关联 session 和手动添加的产出。
• 可在 Settings 中调整 raw log 开关、大小和保留天数。

不做什么

当前版本刻意保持本地、确定性和可控：

• 不调用云端 AI API 生成摘要。
• 不执行用户自定义 hook 脚本。
• 不扫描整个源码仓库来自动学习代码。
• 不修改项目源码文件。
• 不 attach 已经运行的外部终端窗口。

开发命令

npm test
npm start

Windows 构建：

npm.cmd run build:dir

macOS 目录构建：

npm run build:mac

项目文档

• 功能设计 PRD 与架构设计
• Memory Layer PRD

仓库内容说明

应该提交到 GitHub：

• src/
• docs/
• scripts/
• README.md
• README_EN.md
• LICENSE
• package.json
• package-lock.json
• .gitignore

不应该提交：

• node_modules/
• dist/
• .electron-cache/
• .electron-builder-cache/
• .localappdata/
• .npm-cache/
• .home/
• .env*
• 日志和临时文件

许可证

Apache-2.0