Awesome-ccIDE: Instructions file for Claude Code

CLAUDE.md — ccIDE 项目专用指令

继承自用户全局 ~/.claude/CLAUDE.md 的所有规则（语言、前端三更、安全红线、Skill 优先、解决问题方式等）。以下是本项目的附加规则。

项目概览

ccIDE — 管理 Claude Code 历史 session 的 macOS 原生桌面应用。

• 技术栈：Electron + React + TypeScript + xterm.js + node-pty
• 入口：electron/main.ts (主进程) / src/App.tsx (渲染进程)
• 数据源：~/.claude/projects/*/sessions-index.json + ~/.claude/history.jsonl
• 自定义名称存储：~/.claude-session-manager/session-names.json

同步规则（用户主导推送节奏）

默认：只做本地修改 + 本地 .app 更新，不自动推送远端。

每次改动的默认流程（无用户指示时）

# 1. 编译检查
cd ~/ccIDE && npx tsc --noEmit

# 2. 打包
npm run dist

# 3. 安装到本地 Applications
rm -rf /Applications/ccIDE.app && cp -R release/mac-arm64/ccIDE.app /Applications/

# 4. 本地 git commit（但不 push）
git add -A && git commit -m "..."

推送远端时的流程（用户说「推送」/「push」/「发布」时）

一旦推送远端，必须同时更新 DMG Release：

# 1. 推送代码
git push origin main

# 2. 更新 GitHub Release DMG（与 push 绑定，不可分离）
gh release delete v1.0.0 --repo sophiaashi/Awesome-ccIDE --yes
gh release create v1.0.0 \
  --repo sophiaashi/Awesome-ccIDE \
  --title "ccIDE v1.0.0" \
  --notes "macOS Apple Silicon (arm64). Download DMG, drag to Applications, done." \
  release/ccIDE-1.0.0-arm64.dmg

关键规则

• 用户没说「推送」时，不要自动 git push
• 用户说「推送」时，必须同时更新 DMG（push 和 DMG 更新是原子操作）
• 本地 Applications 下的 app 每次改动都要更新（用户会直接测试）

构建输出

文件	用途
dist/	Vite 前端构建产物
dist-electron/electron/main.cjs	编译后的主进程
release/mac-arm64/ccIDE.app	打包的 macOS app
release/ccIDE-1.0.0-arm64.dmg	分发用的 DMG（~123MB，含 Electron 运行时）

架构关键点

• Electron main process 负责：session 数据读取、node-pty 管理、IPC handler
• React renderer 负责：UI 渲染、通过 window.electronAPI 调 IPC
• preload.ts 安全暴露 IPC（contextBridge）
• 开发模式：npm run dev 启动 Vite + Electron 双进程
• 生产模式：main.cjs 用 loadFile('../../dist/index.html') 加载（路径是 dist-electron/electron/ → 上两级 → dist/）

常见陷阱

1. 黑屏问题 → 检查 mainWindow.loadFile 的相对路径
2. Resume 报错 env: node: No such file → pty spawn 必须加 --login 参数 + 显式传完整 PATH
3. icon 外层有灰色底板 → icon 图片必须完全不透明，渐变填满 1024x1024
4. 当前 session 不在列表 → sessions-index.json 可能未及时更新，需扫描 .jsonl 文件补充
5. 多两个 style 属性 → JSX 不允许，合并成一个对象