跳转到正文
xclaude
文档目录

快速开始

安装 AASC 桌面应用或源码版，开启你的第一个会话。

准备工作

  • Claude Code，或 Codex CLI 0.130 及更新版本；Codex 钩子需要自行启用。
  • macOS 与 Linux 需要 jq，用于将事件匹配到正确终端；Windows 钩子使用 PowerShell。没有 jq 时仍会发送事件，但缺少 PID、TTY 等终端信息。
# macOS
brew install jq
# Ubuntu / Debian
sudo apt-get install jq

安装

桌面版与源码版提供相同的控制面板。

桌面应用

在下载页选择 macOS（Apple 芯片）、Windows 或 Linux，并按对应步骤安装。服务已内置，无需安装 Node.js。桌面安装向导会检查工具、安装钩子，并要求设置访问密码。没有密码时，只有本机能够访问。

从源码运行

需要 Node.js 22.12 及更新版本和 Git：

git clone https://github.com/coding-by-feng/ai-agent-session-center.git
cd ai-agent-session-center
npm install
npm rebuild better-sqlite3 node-pty
npm run build
npm start

每次启动都会注册钩子，并打开 http://localhost:3333。更多说明见源码运行。

安装向导

源码版运行 npm run setup 后，会询问六项设置并启动服务：

  1. 服务端口，默认 3333。
  2. 需要接入的 AI CLI，默认 Claude Code，可添加 Codex。
  3. 钩子密度，默认 medium，见配置。
  4. 调试模式，默认关闭。
  5. 会话历史保留选项：12、24、48 小时或 7 天，默认 24 小时。该选项会写入配置，但当前服务端不读取它。
  6. 控制面板密码。源码向导中可选；至少 8 字符，包含大小写字母、数字和特殊字符。

第一个会话

  1. 启动控制面板。
  2. 在终端运行 claude 或 codex。
  3. 会话卡片出现在 LIVE 看板。可选的 3D 视图默认关闭。
  4. 点击会话，查看终端、项目文件、对话、笔记与提示词队列。

也可点击会话栏的 +，或空白 LIVE 页的 + NEW 创建会话，详见终端与 SSH。

状态含义

  • idle：空闲。
  • prompting：已发送提问，正在开始处理。
  • working：正在运行工具。
  • approval：等待你授权工具调用。
  • input：等待你回答问题。
  • waiting：本轮已完成，等待下一条提问。
  • ended：会话已结束，卡片保留，可继续恢复。

颜色随主题变化。可选 3D 视图中，空闲与等待状态在休息区；提问与工作状态在桌前；授权请求显示黄色，问题请求显示紫色。

从其他设备访问

在其他设备打开 http://运行电脑地址:3333，端口以实际配置为准：

  • 必须先设置密码，否则其他设备会被拒绝。
  • 会话需要显式共享：点击会话的 Share，或在设备菜单中启用 Share new sessions with my devices。
  • 普通 HTTP 连接应使用可信网络或 VPN。拥有密码意味着可以操作运行环境中的终端，应像 SSH 权限一样保护。

Android 应用见手机页，iPhone 通过 TestFlight 提供，是否开放以页面为准。从 2.10.60 起，设备菜单中提供 Pair a phone or computer；旧版本需要启用 phonePairing。配对手机可通过 Tailscale 连接，详见设备访问配置。

服务启动选项

源码版在 -- 后传入参数：

npm start -- --port 4444
npm start -- --no-open
npm start -- --debug

分别指定端口、不自动打开浏览器、开启详细日志。

安装内容与数据位置

Claude Code 钩子写入 ~/.claude/settings.json，脚本位于 ~/.claude/hooks/dashboard-hook.sh（Windows 为 dashboard-hook.ps1）；Codex 钩子写入 ~/.codex/config.toml，脚本位于 ~/.codex/hooks/dashboard-hook.sh。

钩子还会设置终端标签标题，并在 <project>/.claude/last-session-id 写入会话 ID。状态栏脚本 dashboard-statusline.sh 会复制到 Claude hooks 目录，但不会注册进你的设置；仅传给 AASC 自己启动的 Claude 会话，以读取套餐用量，同时保留原有状态栏。

Claude 钩子带有 "_source": "ai-agent-session-center"，可用 npm run uninstall-hooks 移除。源码数据位于仓库 data/；macOS 桌面数据位于 ~/Library/Application Support/ai-agent-session-center/。