# Preservation Aeon

**Repository Path**: Interest-driven/preservation-aeon

## Basic Information

- **Project Name**: Preservation Aeon
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pulse Monitor

桌面悬浮窗工具，实时监控 [Claude Code](https://claude.ai/code) 的运行状态。

![pulse-status](https://img.shields.io/badge/Pulse-v1.0-4CAF50)

## 功能

- **桌面悬浮窗** — 无边框、始终置顶、可拖拽，半透明深色背景
- **系统托盘** — 彩色图标 + 右键菜单，最小化时也不丢失提醒
- **三种状态可视化**

| 状态 | 颜色 | 含义 |
|------|------|------|
| idle | ● 绿色 | 等待用户输入 |
| generating | ● 黄色 | Claude 工作中 |
| needs_approval | ●● 橙红闪烁 | 需要用户操作（授权 / 回答追问） |

- **一键切回终端** — 单击悬浮窗即可激活 Claude Code 所在终端窗口
- **位置记忆** — 关闭重启后恢复到上次位置
- **双击展开详情** — 显示最后更新时间、进程 PID、终端标识

## 系统架构

```
[Claude Code] ──hooks──→ update_status.py ──→ status.json
                                                  │
[Pulse Monitor] ←──── 150ms 轮询 ←───────────────┘
      │
      ├── 悬浮窗（Qt 无边框窗口）
      └── 系统托盘（QSystemTrayIcon）
```

## 安装

### 1. 安装依赖并构建

```bash
pip install -r requirements.txt
pyinstaller pulse-monitor.spec --noconfirm
```

### 2. 部署 Hook

```bash
python scripts/install_hooks.py
```

这会完成两件事：
- 将 `update_status.py` 复制到 `~/.claude-code-monitor/`
- 在 `~/.claude/settings.local.json` 和项目 `.claude/settings.local.json` 中写入 11 个 hook

### 3. 启动

双击 `dist/pulse-monitor.exe`。

## 使用方式

1. 先正常在终端中启动 `claude`
2. 再双击打开 Pulse Monitor
3. Pulse 自动检测 Claude Code 进程并开始监控

你发送消息时 Pulse 瞬间变黄，Claude 回复完成后切回绿色。当 Claude 需要授权或向你追问时，Pulse 会橙红闪烁提醒你回到终端操作。

## Hook 覆盖

| Hook | 映射状态 |
|------|----------|
| `UserPromptSubmit` | generating |
| `PreToolUse` | generating |
| `SubagentStart` | generating |
| `ElicitationResult` | generating |
| `Stop` | idle |
| `StopFailure` | idle |
| `PermissionDenied` | idle |
| `SessionEnd` | idle |
| `PermissionRequest` | needs_approval |
| `Elicitation` | needs_approval |
| `Notification(ask_user_permission)` | needs_approval |

## 技术栈

| 组件 | 选型 |
|------|------|
| UI 框架 | PySide6 (Qt for Python) |
| 进程检测 | psutil |
| 终端激活 | ctypes + Windows user32.dll |
| 打包 | PyInstaller (单文件 ~44MB) |
| 通信方式 | 文件轮询（`~/.claude-code-monitor/status.json`） |

## 项目结构

```
pulse-monitor/
├── src/
│   ├── main.py               # 入口
│   ├── status_monitor.py     # 状态轮询 + 进程检测
│   ├── floating_widget.py    # 桌面悬浮窗
│   ├── system_tray.py        # 系统托盘
│   └── terminal_activator.py # 终端查找与激活 (Windows)
├── scripts/
│   ├── install_hooks.py      # 首次安装
│   ├── update_hooks.py       # 更新 hook 配置
│   └── update_status.py      # 状态写入脚本（被 hook 调用）
├── requirements.txt
├── pulse-monitor.spec        # PyInstaller 配置
└── dist/
    └── pulse-monitor.exe     # 可执行文件
```

## 许可证

MIT