nov1n/squawk
GitHub: nov1n/squawk
squawk 是一款 macOS 上为 Claude Code 提供上下文感知智能通知的工具，支持在通知中内联回复和一键批准权限。
Stars: 5 | Forks: 0
https://github.com/user-attachments/assets/e99fe0b1-1423-4f97-bf2a-b0fd287f4eb5
# squawk
`squawk` 为 Claude Code 带来了智能的 macOS 通知功能。它只会在 Claude 不在视线范围内时提醒你，并提供快速操作以便回复、批准或跳转到该面板。
## 功能
- **上下文感知提醒：** 聚焦时保持静默，可见时显示面板内横幅，离开屏幕时发送通知。
- **内联回复：** 直接在通知中回复以让 Claude 继续。
- **一键批准：** 直接在提醒中允许权限提示。
- **消息预览：** 一眼即可查看 Claude 的最新回复。
- **智能生命周期：** 提醒会持续存在直至被处理，但当你聚焦该面板时会自动清除。
- **整洁分组：** 会话通知会原地更新，而不会堆满你的屏幕。
- **零配置：** 开箱即用，并支持可选的环境变量覆盖（参见[配置](#configuration)）。
## 事件
`squawk` 使用 Claude Code hooks 在以下事件发生时发送通知：
| 事件 | 触发条件 | 通知 |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `Stop` | Claude 完成其轮次 | **已完成**；回复以让其继续 |
| `StopFailure` | 轮次因 API 错误（速率限制、服务器错误等）而终止 | **轮次失败** |
| `Notification` | Claude 正在等待你或 MCP 服务器请求输入 | **需要你的输入** |
| `PermissionRequest` | Claude 需要权限才能运行工具 | **需要你的权限**；在提醒中批准 |
## 要求
- **Claude Code**、**`tmux`**、**`jq`** 和 **`alerter`**（核心依赖）
- **Claude for Desktop** _（可选）_ `squawk` 会借用其应用图标，使通知看起来更原生。如果没有它，你会得到一个默认的后备图标（或者你可以手动设置 `SQUAWK_ICON`）。
```
brew install jq tmux claude
brew install vjeantet/tap/alerter
brew install --cask claude-code
```
## 安装
```
git clone https://github.com/nov1n/squawk ~/.local/share/squawk
~/.local/share/squawk/bin/squawk install
```
将克隆的仓库保留在原处，因为 `squawk install` 会创建指向它的符号链接，并在运行时读取它（因此 `git pull` 即可实现原处升级）。`squawk install` 会执行以下操作：
1. 检查所需依赖是否已正确安装。
2. 将 `squawk` 符号链接到 `~/.local/bin`（可通过 `PREFIX=` 覆盖）。
3. 将其 hooks（`Stop`、`StopFailure`、`Notification`、`PermissionRequest`）合并到 `~/.claude/settings.json` 中。
4. 提示将面板内横幅所需的 tmux 代码片段添加到 `~/.tmux.conf`（或者打印出来供你自行添加）。
## 配置
全部通过环境变量（或者如果存在则读取可选的 `~/.config/squawk/config`）进行配置：
| 变量 | 默认值 | 用途 |
| ------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SQUAWK_ICON` | _（自动）_ | 通知所使用的 **图标** 的 Bundle id（`alerter --sender`）。如果 Claude for Desktop 安装在标准路径下，则默认使用 **Claude 图标**。设置一个 bundle id 以使用其他应用的图标，或设为 `none` 以禁用。 |
| `SQUAWK_BANNER` | _（黄色 ⬤ 样式）_ | 面板内横幅的完整 tmux `pane-border-format`；`{label}` 会被替换为对应的事件。重新设置颜色、符号、填充/宽度和对齐方式 —— 例如 `#[align=left,bg=magenta,fg=white,bold] ▶ {label} `。 |
| `SQUAWK_TIMEOUT` | `0` | 通知自动消失前的秒数。`0` 表示**持续保留**（当你返回面板时 squawk 会将其清除）。设置一个数字则以自动消失代替。 |
| `SQUAWK_SOUND` | _（静音）_ | 在通知时播放声音。设置为 `default` 或 macOS 系统声音名称（`Ping`、`Glass`、`Submarine` 等）。 |
| `SQUAWK_APPROVE` | `1` | 在权限通知上显示批准按钮。设为 `0` 表示仅通知（在终端中决定）。 |
| `SQUAWK_REPLY` | `1` | 在“已完成”通知上显示回复字段（你的回复会继续对话）。设为 `0` 表示仅通知。 |
| `SQUAWK_ENABLE` | `1` | 设为 `0` 将完全禁用 squawk。 |
| `SQUAWK_DEBUG` | _（未设置）_ | 设为 `1` 可将决策记录到 `SQUAWK_DEBUG_LOG`。 |
| `SQUAWK_DEBUG_LOG` | `$TMPDIR/squawk-debug.log` | 调试日志路径。 |
## 卸载
```
squawk uninstall
```
移除 Claude Code hooks（保留同级内容）、`~/.local/bin/squawk` 符号链接以及 tmux 代码片段。
## 开发
```
make test # bats suite
make lint # shellcheck + shfmt
make fmt # auto-format
```
## 常见问题
## AI 声明
squawk 几乎完全由 Claude Code 构建。其设计、实现和测试均是在人类指导和审查下，通过 AI 结对编程产生的。
## 许可证
[MIT](LICENSE)
为什么我没有收到通知？
macOS 必须允许 squawk 借用图标的应用（默认为 Claude Desktop）发送通知。打开 **系统设置 → 通知 → Claude**，开启 **允许通知**，并将样式设置为 **提醒**，以便回复/批准按钮出现并持续显示。如果通知仍然没有显示，macOS 可能正在丢弃模拟的发送方 —— 请设置 `SQUAWK_ICON=none` 以使用默认图标。 squawk 支持多个 tmux 客户端吗？
不完全支持。当两个客户端连接到同一个会话时，tmux 是按_会话_而不是按客户端报告其面板/窗口状态的，因此 squawk 无法分辨你实际正在查看哪个终端，并且可能会在该通知时保持静默。单个已连接的客户端 —— 无论是否有任何分割、窗口和分离的会话 —— 都能得到完全支持。标签：Claude Code, Cutter, tmux, 开发辅助, 通知工具