CodexAgentMonitor：macOS 菜单栏的 Codex Agent 观测工具

CodexAgentMonitor 是一款原生 macOS 菜单栏应用，专门用于观测 Codex 风格 Agent 工作流的运行状态，提供实时健康指标、用量遥测和权限诊断能力。

随着 AI 编程助手如 Codex 的广泛应用，开发者越来越依赖 Agent 来自动化代码编写、重构和调试任务。然而，当多个 Agent 同时运行或长时间执行复杂任务时，了解它们的实时状态、资源消耗和权限边界变得至关重要。CodexAgentMonitor 正是为解决这一观测需求而诞生的原生 macOS 工具。

该项目的设计理念非常明确：它不对 Codex 进行任何修改，也不控制外部系统，纯粹作为一个观测层存在。通过读取本地 JSONL 事件流，它将 Agent 的运行状态以直观的方式呈现在 macOS 菜单栏中，让开发者能够随时掌握 AI 助手的工作情况。

CodexAgentMonitor 采用 SwiftUI 的 MenuBarExtra 构建，作为常驻菜单栏应用运行。其核心功能围绕 Agent 观测展开，提供了多维度的状态展示：

健康状态指示是应用最直观的功能。菜单栏图标会根据系统状态显示不同颜色：绿色表示健康运行，黄色表示高负载或资源紧张，红色则表示出现关键问题或被阻塞。这种设计让用户无需打开详细界面，一眼就能判断系统状态。

活跃 Agent 列表展示了当前所有运行中的 Agent 信息，包括 ID、名称、状态、当前任务、启动时间和运行时长。每个 Agent 的活动描述也会实时更新，让用户清楚了解每个 Agent 正在做什么。

用量遥测面板提供了过去 5 小时、过去 7 天以及总使用量的统计，同时显示剩余配额和用量趋势。这对于需要监控 API 配额消耗或资源使用的团队尤为重要。

权限与限流显示为每个 Agent 展示其权限范围和当前的速率限制状态，帮助开发者及时发现潜在的权限问题。

诊断面板则集中展示权限警告和配额警告，方便快速定位问题。

CodexAgentMonitor 的核心是一个本地事件文件监听器。默认情况下，它监视位于 ~/.codex-agent-monitor/events.jsonl 的 JSONL 文件，每行代表一个独立的事件。

应用支持的事件类型包括：

• agent_started：Agent 启动事件，包含 Agent 的基本信息和初始状态
• agent_updated：Agent 状态更新，用于实时同步任务进度和活动描述
• agent_finished：Agent 完成事件，标记任务结束
• token_usage_updated：Token 用量更新，用于遥测统计
• permission_warning_triggered：权限警告触发，用于诊断面板展示

所有事件均采用 ISO-8601 格式的日期时间戳，确保跨时区的一致性。当事件文件不存在时，应用还会展示演示遥测数据，方便用户了解界面功能。

CodexAgentMonitor 要求 macOS 14 或更新版本，使用 Swift 6.3 工具链或兼容的 Xcode 命令行工具进行构建。构建和运行非常简单：

swift build
swift run CodexAgentMonitor

当从 Codex 启动时，应用会在 Agent 的 PTY 中运行，菜单栏图标会自动出现在 macOS 菜单栏中。这种设计让它能够无缝融入开发者的工作流程。

项目提供了测试脚本 script/run_tests.sh 用于运行验证套件。需要注意的是，由于命令行工具环境无法直接导入 XCTest/Testing，测试通过 CodexAgentMonitorTestRunner 执行。

完整的架构边界定义可以在项目的 docs/architecture.md 中找到，该文档详细描述了事件模型、状态转换和数据流设计。

CodexAgentMonitor 适合以下场景：

多 Agent 并行开发：当同时运行多个 Codex Agent 处理不同任务时，通过菜单栏快速切换关注焦点，了解每个 Agent 的进度。

长时间任务监控：对于需要运行数分钟甚至更长时间的复杂重构任务，实时观察 Agent 的活动描述，确认它仍在正常工作而非陷入死循环。

配额管理：通过用量遥测面板跟踪 API 调用消耗，避免意外超出配额限制。

问题排查：当 Agent 行为异常时，通过诊断面板快速定位权限或限流问题，减少调试时间。

CodexAgentMonitor 的价值在于它填补了 Codex Agent 工作流中的一个关键空白——可观测性。作为一个轻量级的菜单栏工具，它既不侵入 Codex 的核心功能，又为开发者提供了必要的运行时洞察。对于重度使用 Codex 的 macOS 开发者来说，这款工具能够显著提升工作流的透明度和可控性。