wallfacer

wallfacer 是一款终端会话管理工具，为 Claude Code、Cursor CLI、Kiro CLI 和 Codex 提供统一的只读索引与元数据覆盖层。它将分散在 ~/.claude/projects/、~/.cursor/chats/、~/.kiro/sessions/cli/、~/.codex/sessions/ 中的无标题JSONL/哈希目录会话聚合到本地SQLite数据库，支持命名、标记、分组、搜索、恢复与安全删除。

核心原则：永不修改原始代理文件，所有元数据独立存储于 ~/.local/share/wallfacer/；删除操作默认移入回收站，仅 --purge 永久移除。提供TUI全屏浏览器与CLI子命令双前端，共享同一索引，支持 --json 输出供脚本集成。安装通过Homebrew或Go，需Go 1.22+。

核心架构：只读索引 + 元数据覆盖层

数据流设计

[代理原始会话文件] ---(只读扫描)---> [wallfacer SQLite索引]
                                          ↑
[用户元数据: 标题/标签/项目] --------------┘

• 扫描策略：仅读取每个会话文件头部获取工作目录、时间戳、首条提示词（自动标题），避免全量解析大文件
• 增量同步：每次命令前自动sync，仅处理新增/变更文件，百级会话仍毫秒响应
• 元数据隔离：标题、标签、项目存于独立SQLite表，删除索引文件仅丢失覆盖层，原始对话完好
• 多文件会话处理：Kiro/Cursor的transcript+sidecar+scratch目录作为原子单元移动/删除，避免残留

安全机制

双前端使用范式

TUI模式（交互式浏览器）

wallfacer  # 无参数启动

• 布局：左侧会话列表（项目/标签/目录/时间/代理），右侧详情面板（<100列时自动隐藏）
• 核心快捷键：
  • / 模糊搜索（标题/项目/目录/标签/代理）
  • P/T/A 循环筛选项目/标签/代理，x清除
  • n 新建会话（选代理→目录→标题→项目→标签）
  • enter 恢复会话（终端移交代理，退出后返回TUI）
  • r/t/p 重命名/编辑标签/设置项目
  • d 删除（确认→回收站）
• 代理选择：新建时单行选择器，Claude Code默认预选；单适配器时跳过

CLI模式（脚本友好）

wallfacer new ~/proj --agent cursor --title "Refactor auth" --tag backend
wallfacer resume "refactor auth"      # 标题或ID前缀匹配
wallfacer list --project api --json   # JSON输出供jq处理
wallfacer search "database migration" # 跨字段搜索
wallfacer tag add abc123 urgent       # 引用ID前缀或精确标题

• 引用解析：<ref> 支持ID前缀（5f2）或精确标题（"smoke test"），歧义时列出候选
• 自动拾取：wallfacer外启动的会话下次sync自动纳入，无需导入
• 管道安全：非TTY环境（| less/脚本）裸命令打印帮助而非开TUI；更新检查仅stderr输出，不污染--json

部署与兼容性要点

安装选项

# Homebrew（macOS/Linux）
brew tap pradipta/wallfacer https://github.com/pradipta/wallfacer
brew install pradipta/wallfacer/wallfacer
# 后续升级：brew upgrade wallfacer

# Go install
go install github.com/pradipta/wallfacer@latest  # 需Go 1.22+

# 预编译二进制
# Releases页面下载对应平台归档

代理适配现状

已知限制

• ❌ 不支持VS Code GUI版Cursor/Claude（仅CLI会话）
• ❌ 回收站无内置restore命令，需手动mv恢复
• ❌ 标签/项目无层级结构，纯扁平字符串
• ⚠️ 首次扫描大量会话时可能短暂阻塞，后续增量同步快速
• ⚠️ 代理更新若改变会话文件格式，需等待wallfacer适配器更新

最佳实践与工作流整合

会话组织策略

• 项目分组：以代码仓库或业务域为项目单位（api/frontend/infra）
• 标签体系：按状态（wip/done/blocked）、类型（bugfix/feature/refactor）、优先级（urgent）三维打标
• 命名规范：[类型] 简要描述（如[fix] Auth token expiry race condition）

脚本集成示例

# 每日备份活跃项目会话
wallfacer list --project api --json | jq -r '.[].id' | xargs -I{} cp ~/.local/share/wallfacer/sessions/{} ~/backups/

# CI中查找相关历史会话
wallfacer search "payment webhook" --json | jq '.[] | select(.agent=="claude") | .title'

# 批量清理已完成会话
wallfacer list --tag done --json | jq -r '.[].id' | xargs wallfacer rm

故障排查

• TUI空白 → 检查~/.local/share/wallfacer/权限，或删除重建索引
• 会话未显示 → 运行wallfacer sync强制重扫
• 恢复失败 → 确认代理CLI在PATH中，且原始会话文件未被外部删除
• JSON输出异常 → 确保未混用TUI模式，检查stderr是否有更新检查干扰