claudebar

English | 中文

Real-time Claude Code session monitoring in your macOS menu bar, powered by SwiftBar.

---

Preview

---

What it does

• Shows every active Claude Code session in your menu bar with an emoji status indicator
• Multiple sessions expand the bar inline: 🤔 web ⚡️ api ✅ docs
• Click a session in the dropdown to bring its terminal window to the front
• Sends native macOS notifications only when you need to act:
  • 💬 Claude is waiting for your reply
  • 🔐 Claude needs permission to use a tool
  • ✅ Task completed
  • 🛑 Session ended

---

Status indicators

Emoji	Status	Meaning
🤔	thinking	Claude is reasoning
⚙️	executing	Running a tool
⚡️	multi_executing	Running multiple tools in parallel
✍️	streaming	Streaming a response
💬	waiting_input	Needs your input
✅	completed	Task finished
❌	error	Something went wrong
🛑	ended	Session closed
💤	idle	No active sessions

---

Requirements

• macOS 13 or later
• SwiftBar installed and running
• claude-monitor daemon
• jq recommended — brew install jq

---

Installation

1. Install the claude-monitor daemon

npm install -g @wangjs-jacky/claude-monitor
claude-monitor init

2. Install claudebar

git clone https://github.com/YOUR_USERNAME/claudebar.git
cd claudebar
chmod +x install.sh
./install.sh

The installer will:

1. Copy hooks to ~/.claudebar/hooks/
2. Merge hook entries into ~/.claude/settings.json
3. Install the SwiftBar plugin automatically
4. Start the claude-monitor daemon

After installation, look for 🤖 Claude in your menu bar. If it does not appear, open SwiftBar → Refresh All Plugins, or hold ⌘ and drag the icon out of Control Center.

---

Manual SwiftBar setup

If the installer cannot detect your SwiftBar plugin directory:

1. Open SwiftBar → Preferences → note the Plugin Directory path
2. Copy swiftbar/claude.3s.sh into that folder
3. Click Refresh All Plugins

---

How it works

Claude Code  ──hooks──▶  claude-monitor daemon (localhost:17530)
                                   │
                         REST API + WebSocket
                                   │
              SwiftBar plugin (polls every 3 s)
                                   │
                         macOS menu bar display

claudebar provides shell hooks that fire on Claude Code lifecycle events. The hooks report to the claude-monitor daemon via its REST API. The SwiftBar plugin polls the daemon every 3 seconds and renders the current state.

---

File structure

claudebar/
├── install.sh            # One-command installer
├── uninstall.sh          # Clean uninstaller
├── hooks/
│   ├── session-start.sh  # SessionStart — register session
│   ├── session-end.sh    # SessionEnd — deregister + notify
│   ├── prompt-submit.sh  # UserPromptSubmit — log prompt, set thinking
│   ├── waiting-input.sh  # PreToolUse(AskUserQuestion) — notify user
│   ├── input-answered.sh # PostToolUse(AskUserQuestion) — reset status
│   ├── tool-start.sh     # PreToolUse — record tool call start
│   ├── tool-end.sh       # PostToolUse — record tool call end
│   ├── response-end.sh   # Stop — mark completed + notify
│   └── notification.sh   # Notification — permission / idle alerts
└── swiftbar/
    ├── claude.3s.sh      # SwiftBar plugin (3 s refresh)
    └── focus-session.sh  # Focus terminal window on click

---

Uninstall

./uninstall.sh

Removes ~/.claudebar, the SwiftBar plugin, and all hook entries from ~/.claude/settings.json.

---

License

MIT

---

---

中文

English | 中文

在 macOS 菜单栏实时显示 Claude Code 会话状态，由 SwiftBar 驱动。

---

效果预览

---

功能

• 在菜单栏以 emoji 实时显示每个 Claude Code 会话的当前状态
• 多个会话并排展示，宽度自动扩展：🤔 web ⚡️ api ✅ docs
• 点击下拉菜单中的会话，自动将对应终端窗口调到前台
• 仅在需要你操作时发送原生 macOS 通知：
  • 💬 Claude 等待你的回复
  • 🔐 Claude 需要权限授权
  • ✅ 任务完成
  • 🛑 会话已结束

---

状态说明

Emoji	状态	含义
🤔	thinking	Claude 正在思考
⚙️	executing	正在执行工具
⚡️	multi_executing	并行执行多个工具
✍️	streaming	正在流式输出
💬	waiting_input	等待你的输入
✅	completed	任务完成
❌	error	执行出错
🛑	ended	会话已结束
💤	idle	无活跃会话

---

环境要求

• macOS 13 或更高版本
• 已安装并运行 SwiftBar
• 已安装 claude-monitor 守护进程
• 推荐安装 jq — brew install jq

---

安装

1. 安装 claude-monitor 守护进程

npm install -g @wangjs-jacky/claude-monitor
claude-monitor init

2. 安装 claudebar

git clone https://github.com/YOUR_USERNAME/claudebar.git
cd claudebar
chmod +x install.sh
./install.sh

安装脚本会自动完成：

1. 将 hooks 复制到 ~/.claudebar/hooks/
2. 将 hook 配置合并写入 ~/.claude/settings.json
3. 自动安装 SwiftBar 插件
4. 启动 claude-monitor 守护进程

安装完成后，在菜单栏查找 🤖 Claude。若未出现，请在 SwiftBar 中点击 刷新全部插件，或按住 ⌘ 将图标从控制中心拖回菜单栏。

---

手动配置 SwiftBar

若安装脚本无法自动检测 SwiftBar 插件目录：

1. 打开 SwiftBar → 偏好设置 → 记下插件目录路径
2. 将 swiftbar/claude.3s.sh 复制到该目录
3. 点击 刷新全部插件

---

工作原理

Claude Code  ──hooks──▶  claude-monitor 守护进程 (localhost:17530)
                                   │
                         REST API + WebSocket
                                   │
              SwiftBar 插件（每 3 秒轮询）
                                   │
                         macOS 菜单栏显示

claudebar 提供一组 shell hooks，在 Claude Code 生命周期事件触发时执行，通过 REST API 上报到 claude-monitor 守护进程。SwiftBar 插件每 3 秒读取一次守护进程状态并渲染到菜单栏。

---

文件结构

claudebar/
├── install.sh            # 一键安装脚本
├── uninstall.sh          # 一键卸载脚本
├── hooks/
│   ├── session-start.sh  # SessionStart — 注册会话
│   ├── session-end.sh    # SessionEnd — 注销会话 + 通知
│   ├── prompt-submit.sh  # UserPromptSubmit — 记录提问
│   ├── waiting-input.sh  # PreToolUse(AskUserQuestion) — 等待输入通知
│   ├── input-answered.sh # PostToolUse(AskUserQuestion) — 重置状态
│   ├── tool-start.sh     # PreToolUse — 记录工具调用开始
│   ├── tool-end.sh       # PostToolUse — 记录工具调用结束
│   ├── response-end.sh   # Stop — 标记完成 + 通知
│   └── notification.sh   # Notification — 权限/超时提醒
└── swiftbar/
    ├── claude.3s.sh      # SwiftBar 插件（3 秒刷新）
    └── focus-session.sh  # 点击跳转对应终端窗口

---

卸载

./uninstall.sh

将移除 ~/.claudebar、SwiftBar 插件，以及 ~/.claude/settings.json 中的所有 hook 配置。

---

开源协议

MIT