Agent Light

仓库地址：https://github.com/JiayuK/agent-light

macOS 菜单栏 / Windows 系统托盘 + 悬浮面板，实时监控 Cursor、Claude Code、Codex，以及 Claude Desktop 编程模式 的运行状态。

🔴 运行中  →  模型正在生成 / 执行工具
🟡 人工确认  →  需要权限确认、Run Command、AskQuestion 等
🟢 结束    →  空闲 / 任务已完成

每个卡片对应一个独立实例（一个 Cursor 窗口或一个 CLI 会话）。点击卡片可将对应工具窗口切换到前台。

⚠️ macOS 用户必读：必须开启「辅助功能」

Agent Light 依赖 辅助功能 (Accessibility) 读取窗口标题、枚举 Cursor/Claude Desktop 窗口，并在点击卡片时切回对应应用。未开启时应用可以启动，但会出现：

• 检测不到 Cursor / Claude Desktop 窗口，或实例数量不全
• 点击卡片无法聚焦到目标窗口
• Claude Desktop 编程模式识别异常

每台 Mac 只需配置一次：系统设置 → 隐私与安全性 → 辅助功能 → 添加并打开开关：

你怎么启动 Agent Light	要勾选哪个程序
./run-app.sh / ./run.sh	你用的终端（Terminal / iTerm / Warp 等）
双击 Agent Light.app	Agent Light

改完后若仍无效，请退出并重新启动 Agent Light。完整图文步骤见下方 macOS 安装 → 授予辅助功能权限。

快速开始

系统要求

macOS 安装（推荐：独立 app 包）

无需 Python、无需 pip install，下载 zip 解压即用。

1. 下载并解压

1. 打开 Releases 页面
2. 下载 agent-light-x.x.x-macos-app.zip（独立应用，约 20MB）
3. 双击 zip 解压，得到目录（示例）：

agent-light-1.1.0-macos-app/
├── Agent Light.app    # 可拖入「应用程序」文件夹
└── run-app.sh         # 启动脚本（推荐首次使用）

架构：当前 Release 独立包为 Apple Silicon (arm64) 构建。Intel Mac 请改用下方「源码版（macOS 开发者）」的 ./run.sh。

⚠️ 首次打开必读：macOS 可能拦截未签名应用

Agent Light 为开源项目，未做 Apple 开发者签名。从 GitHub 下载后首次启动，系统可能提示「无法打开」或「来自身份不明的开发者」。

任选一种方式放行（只需操作一次）：

1. 右键打开（推荐）
   在 Finder 中 右键 Agent Light.app → 选择 「打开」 → 在弹窗中再次点 「打开」。

2. 系统设置放行
   若双击被拦截，打开 系统设置 → 隐私与安全性，在页面底部找到被阻止的提示，点 「仍要打开」。

3. 终端移除隔离属性（进阶）
   若仍无法打开，在终端执行（将路径换成你的实际解压位置）：

   copy

   xattr -cr "/path/to/agent-light-x.x.x-macos-app/Agent Light.app"
   

放行后，之后可直接双击启动，无需重复上述步骤。

2. 启动应用

方式 A：脚本启动（推荐，尤其首次使用）

在终端进入解压目录：

cd ~/Downloads/agent-light-1.1.0-macos-app   # 改成你的实际路径

chmod +x run-app.sh
./run-app.sh

看到 ✓ Agent Light 已启动 后，菜单栏会出现监控图标，屏幕上方出现悬浮面板。

方式 B：放入「应用程序」后双击

1. 将 Agent Light.app 拖入 /Applications（应用程序）文件夹
2. 按上文 ⚠️ 首次打开必读 完成放行
3. 在启动台或 Finder 中 双击 Agent Light 即可使用

日常双击 app 启动完全可行。需要 stop、install-hooks 等命令时，请回到解压目录执行 ./run-app.sh <子命令>，或使用源码目录的 ./run.sh。

3. 授予辅助功能权限（每台 Mac 只需一次）

这是 macOS 上最关键的一步。 没有辅助功能权限，Hook 状态可能正常，但窗口实例检测、点击聚焦、Claude Desktop 识别都会受影响。

Agent Light 需要通过 macOS 辅助功能 API 读取窗口信息。请按你实际的启动方式授权（开关必须打开）：

系统设置 → 隐私与安全性 → 辅助功能 → 点左下角 🔒 解锁 → 点 + 添加程序 → 打开右侧开关

如何确认已生效：

1. 列表中对应程序右侧开关为蓝色/开启
2. 退出 Agent Light 后重新启动（菜单栏 → 退出，或 ./run-app.sh stop 再启动）
3. 面板里应能看到 Cursor 等窗口卡片；点击卡片能切到对应应用

run-app.sh / run.sh 启动时会自动检测；若缺失会在终端提示，并尝试打开系统设置页面。

仍不生效时：

• 先从辅助功能列表中移除终端或 Agent Light，再重新添加并打开开关
• 系统设置 → 隐私与安全性 → 完全磁盘访问 一般不需要，优先检查辅助功能
• 使用 ./run-app.sh verbose 或 ./run.sh verbose 查看日志：~/.agent-light/logs/agent-light.log

4. 安装 Agent Hooks（建议首次配置）

在解压目录执行：

./run-app.sh install-hooks

或在菜单栏图标中选择 安装 Hook。安装后请重启 Cursor / Claude Code / Codex，再执行一次 Agent 任务。详见下文 Agent Hooks。

常用命令

在含 run-app.sh 的目录执行：

升级：下载新版 zip，解压覆盖（或新目录），再 ./run-app.sh；~/.agent-light/ 中的设置与自定义风格会保留。

Windows x64

方式一：独立包（推荐）

从 Releases 下载 agent-light-x.x.x-windows-x64.zip，解压后：

cd <解压目录>
.\run-app.ps1

方式二：源码运行

git clone https://github.com/JiayuK/agent-light.git
cd agent-light
.\run.ps1

功能与 macOS 对齐：交通灯 / 坤坤 / 自定义风格、「我爱发明」风格管理、Hook 安装提醒、Claude Desktop 编程会话检测。路径自动发现：%APPDATA%\Cursor、%USERPROFILE%\.cursor、.claude、.codex 等。

测试说明：Windows x64 版已在代码层完成开发与 CI 构建，尚未在真实 Windows 设备上人工验证。若在 Windows 上遇到问题，欢迎提 Issue；macOS 版为日常主力平台并已实测。

维护者在本机构建 Windows 包：.\scripts\build-app-win.ps1（需在 Windows x64 上运行）；或推送 tag 后由 GitHub Actions Build Windows x64 自动构建并上传到对应 Release。

源码版（macOS 开发者）

需要本机 Python 3.9+，首次运行会自动 pip install 依赖：

git clone https://github.com/JiayuK/agent-light.git
cd agent-light

chmod +x run.sh
./run.sh

首次运行会自动：

1. 检测本机 Python 3.9+
2. 创建 .venv 并 pip install -e .
3. 后台静默启动（默认不写日志）

看到 ✓ Agent Light 已启动 后，菜单栏会出现监控图标，屏幕上方出现悬浮面板。

不要提交或复制 .venv：虚拟环境与创建它的 Python 绑定，换电脑后删除重建即可：rm -rf .venv && ./run.sh

手动安装（可选）

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
agent-light              # 默认静默
agent-light --verbose    # 启用日志

辅助功能权限（macOS）

上文 macOS 安装第 3 步 与文首 ⚠️ 必读 已说明完整流程。此处为源码版快速对照：

系统设置 → 隐私与安全性 → 辅助功能 → 添加并打开开关：

• ./run-app.sh / ./run.sh → 添加你的终端
• 双击 Agent Light.app → 添加 Agent Light

未开启时：窗口检测不全、点击无法聚焦、Desktop 识别异常。授权后请重启 Agent Light。

常用命令

菜单栏也提供 安装 Hook / 删除 Hook，支持增量安装（见下文）。

Agent Hooks

三种工具的状态均通过 Agent Hooks 获取，比轮询日志更准确。

安装方式

菜单栏 → 安装 Hook，或：

./run.sh install-hooks

Claude Desktop 编程模式与 Claude Code CLI 共用 ~/.claude/settings.json 中的 Hook；安装 Claude Code Hook 后，Desktop 编程会话也会写入同一状态目录。

状态信号目录：~/.agent-light/agent-hooks/states/

增量安装

• 只检测本机已安装的工具（不必三个都有）
• 首次只有 Cursor → 只装 Cursor
• 之后安装了 Codex → 再次点「安装 Hook」会校验 Cursor 是否完整，并新装 Codex
• 已完整配置的工具显示「已安装且配置完整」，不会重复写入
• 安装/删除时合并写入，不会覆盖你原有的其他 Hook

安装后请重启对应 AI 工具，再执行一次 Agent 任务。

Claude Desktop 注意点

Agent Light 会单独显示 Claude Desktop 卡片（与 Claude Code · 终端 区分）。状态读取顺序：

1. Hook 信号（与 CLI 同源，需已安装 Claude Code Hook）
2. 会话日志 fallback（~/.claude/projects/ 下的 JSONL）
3. 无法识别为编程会话时 → 显示 🟢，原因 desktop: 非编程模式（无 Hook）

编程会话的工作目录来自 Claude Desktop 元数据：

~/Library/Application Support/Claude/claude-code-sessions/

若 Desktop 卡片长期 🟢，请确认：已在 编程模式 下运行任务、窗口标题与会话标题一致、且 Claude Code Hook 已安装并重启 Claude Desktop。

从旧版本升级：若曾使用其他命名的 Hook 脚本，请在菜单栏执行一次「删除 Hook」再「安装 Hook」，或运行 ./run.sh uninstall-hooks && ./run.sh install-hooks。

删除 Hook

菜单栏 删除 Hook 会移除所有已安装的 Agent Light Hook（例如 Cursor + Codex），不影响其他 Hook 配置。

路径自动发现

工具配置目录默认自动发现，新用户克隆后一般无需手动配置：

软件未启动时也会根据上述路径与可执行文件判断是否存在，不会盲目创建目录。

验证本机路径是否自动识别成功：

./run.sh paths

输出中 ✓ 表示目录/文件已存在；○ 为预期默认路径（工具首次运行后会创建）。只要「工具检测详情」里显示已安装对应工具，即可直接启动并安装 Hook。

自定义路径（可选）

仅在非标准安装位置时需要。优先级：

~/.agent-light/settings.json > 环境变量 > 自动发现 > 默认路径

settings.json 示例：

{
  "display_mode": "traffic",
  "traffic_on_colors": {
    "running": "#ff2e26",
    "waiting": "#ffd100",
    "idle": "#26e661"
  },
  "tool_paths": {
    "cursor_user_data_dir": "/path/to/Cursor",
    "cursor_config_dir": "/path/to/.cursor",
    "cursor_projects_dir": "/path/to/.cursor/projects",
    "codex_home": "/path/to/.codex",
    "claude_config_dir": "/path/to/.claude",
    "claude_desktop_sessions_dir": "/path/to/claude-code-sessions"
  }
}

环境变量（可选）：

菜单栏与面板

• 拖动面板空白区域可移动位置
• 点击实例卡片可聚焦对应 AI 工具窗口

颜色の神（自定义交通灯颜色）

交通灯模式（display_mode: "traffic"）下，三种状态默认使用红 / 黄 / 绿。通过菜单栏 / 托盘的 颜色の神 可自定义每种状态点亮时的颜色，macOS 与 Windows 均已适配。

使用方式：

• 选择…：打开系统取色器选取颜色（macOS 为 NSColorPanel，Windows 为系统颜色对话框）。
• 手动输入：在输入框填写 #RRGGBB 十六进制颜色，回车或失焦生效。
• 预览：窗口内三个圆点实时显示当前配色。
• 恢复默认：把三种颜色重置为红 / 黄 / 绿（仅修改草稿）。
• 保存：写入配置并立即刷新悬浮面板。

说明：

• 配置持久化在 ~/.agent-light/settings.json 的 traffic_on_colors 字段（仅保存「点亮」颜色）。
• 未点亮状态的暗色会按主色自动推导（约 55% 亮度），无需单独设置。
• 也可直接编辑 settings.json 的 traffic_on_colors；非法或缺失的颜色会回退到对应默认值。
• 仅作用于 交通灯模式；坤坤与自定义图片风格不受影响。
• 设置窗口会出现在鼠标附近。macOS 上打开期间会临时显示 Dock 图标（系统取色器需要常规激活状态），关闭后恢复无 Dock 图标的菜单栏模式。

用户数据目录

所有运行时数据在 ~/.agent-light/（不会随仓库分发）：

~/.agent-light/
├── settings.json       # 显示模式、可选路径覆盖
├── custom_styles.json  # 自定义风格
├── styles/{id}/        # 风格图片资源
├── agent-hooks/        # Hook 状态信号
├── logs/               # 日志（verbose 模式）
└── agent-light.pid     # 进程 ID

卸载

./run.sh stop
rm -rf .venv
rm -rf ~/.agent-light   # 可选：删除配置与自定义风格

开机自启（可选）

将 /path/to/agent-light 替换为你的克隆路径：

PLIST=~/Library/LaunchAgents/com.agent.light.plist
REPO=/path/to/agent-light

cat > "$PLIST" << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agent.light</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-lc</string>
        <string>cd $REPO && ./run.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
</dict>
</plist>
EOF

launchctl load "$PLIST"

常见问题

悬浮窗不显示

./run.sh status          # 确认在运行
./run.sh verbose         # 查看错误输出

菜单栏图标 → 显示面板。

辅助功能未开启 / 点击无法聚焦（macOS）

1. 打开 系统设置 → 隐私与安全性 → 辅助功能
2. 确认 终端（若用 run-app.sh）或 Agent Light（若双击 app）已在列表中且开关已打开
3. ./run-app.sh stop 或菜单栏退出后重新启动
4. 若刚授权仍无效：从列表移除该程序，重新 + 添加并打开开关

状态始终绿灯

1. 菜单栏 安装 Hook（或 ./run.sh install-hooks）
2. 重启 Cursor / Claude Code / Codex / Claude Desktop
3. 运行一次 Agent 任务（Desktop 需在编程模式）
4. 确认已授予辅助功能权限

只装了部分 AI 工具

正常。未检测到的工具会跳过，菜单显示如 安装 Hook (1/2)。

虚拟环境报错

rm -rf .venv
./run.sh

调试日志

./run.sh stop
./run.sh verbose

日志路径：~/.agent-light/logs/agent-light.log

项目结构

agent-light/
├── run.sh / run.ps1       # macOS / Windows 入口
├── agent_light/
│   ├── main.py            # 平台分发入口
│   ├── platform/          # darwin / win32 应用壳
│   ├── ui/                # macOS AppKit UI
│   ├── ui_win/            # Windows Tk UI
│   ├── agent_hooks/       # Hook 安装与中继
│   └── detector/          # 实例扫描与状态分析
└── packaging/             # PyInstaller spec（mac / win）

完整功能说明与问题检测见 FEATURES.md。

License

MIT — 见 LICENSE。

隐私与数据

Agent Light 完全本地运行，不向任何远程服务器上传数据，无遥测、无分析、无自动更新检查（代码中无 HTTP 网络请求）。

存储位置

收集与用途

Hook 写入的第三方配置

安装 Hook 时会在本机 AI 工具配置目录写入中继脚本并合并 Hook 配置（不覆盖你已有的其他 Hook）：

卸载可从菜单栏 / 托盘选择「删除 Hook」，或通过 run.sh / run.ps1 uninstall-hooks 移除。

请勿提交：.venv/、*.egg-info/、.env、本机 ~/.agent-light/ 或 %USERPROFILE%\.agent-light\ 目录。

发布 Release

# 1. 更新 pyproject.toml 与 agent_light/__init__.py 中的版本号
# 2. 构建 macOS 发布包（本机 Apple Silicon）
chmod +x scripts/build-release.sh scripts/build-app.sh
./scripts/build-release.sh

# 3. Windows x64 包：推送 tag 后由 GitHub Actions 自动构建并上传到 Release
#    （也可在 Windows 上手动运行 .\scripts\build-app-win.ps1）

# 4. 打 tag 并发布（先上传 macOS 资源；Windows zip 由 CI 自动补上）
git tag v1.1.0
git push origin v1.1.0
gh release create v1.1.0 \
  dist/agent-light-1.1.0-macos-app.zip \
  dist/agent-light-1.1.0-macos-source.zip \
  dist/agent-light-1.1.0-macos-source.tar.gz \
  --title "v1.1.0" \
  --notes "macOS: ./run-app.sh | Windows x64: ./run-app.ps1（未经真机测试）"

仅构建 macOS 独立 app：./scripts/build-app.sh

Windows x64 独立包（需在 Windows 上执行）：

.\scripts\build-app-win.ps1
# 产出 dist/agent-light-x.x.x-windows-x64.zip

或通过 GitHub Actions Build Windows x64 workflow 自动构建并上传到 Release。

友链

• LINUX DO — 一个真诚、友善、团结、专业的社区