{"id":50535441,"url":"https://github.com/saba-burduli/codexagentmonitor","last_synced_at":"2026-06-03T16:01:39.034Z","repository":{"id":358482960,"uuid":"1241518510","full_name":"Saba-Burduli/CodexAgentMonitor","owner":"Saba-Burduli","description":"Native macOS menu-bar observability app for Codex agent workflows","archived":false,"fork":false,"pushed_at":"2026-06-02T20:39:25.000Z","size":52,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T21:19:47.642Z","etag":null,"topics":["codex","codex-cli","macos","openai"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Saba-Burduli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T13:46:07.000Z","updated_at":"2026-06-02T20:39:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Saba-Burduli/CodexAgentMonitor","commit_stats":null,"previous_names":["saba-burduli/codexagentmonitor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Saba-Burduli/CodexAgentMonitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saba-Burduli%2FCodexAgentMonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saba-Burduli%2FCodexAgentMonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saba-Burduli%2FCodexAgentMonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saba-Burduli%2FCodexAgentMonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Saba-Burduli","download_url":"https://codeload.github.com/Saba-Burduli/CodexAgentMonitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saba-Burduli%2FCodexAgentMonitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex","codex-cli","macos","openai"],"created_at":"2026-06-03T16:01:35.431Z","updated_at":"2026-06-03T16:01:39.027Z","avatar_url":"https://github.com/Saba-Burduli.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodexAgentMonitor\n\nCodexAgentMonitor is a native macOS menu-bar observability app for Codex-style agent workflows. It shows active agents, live state, token/quota telemetry, permission scopes, rate limits, and quick diagnostics from a local event stream.\n\nThis project does not modify Codex and does not control external systems. It observes JSONL events from an integration layer and renders them in the menu bar.\n\n## Features\n\n- Native macOS menu-bar app using SwiftUI `MenuBarExtra`.\n- Health icon states: green healthy, yellow high usage, red critical/blocked.\n- Active agent list with ID, name, status, task, start time, duration, and activity.\n- Recent Codex session activity history for mirrored messages, context, goals, reasoning markers, and compaction records.\n- Usage metrics for last 5 hours, last 7 days, total usage, remaining quota, and trend.\n- Permission scope and rate-limit display per agent.\n- Diagnostics panel for permission and quota warnings.\n- Demo telemetry when no event log exists.\n- Settings opens as a tab beside Overview and focuses the existing Settings tab if already open.\n- Codex session JSONL mirror for importing local `~/.codex/sessions` telemetry into the app event log.\n\n## Requirements\n\n- macOS 14 or newer.\n- Swift 6.3 toolchain or compatible Xcode command line tools.\n\n## Build And Run\n\n```sh\nswift build\nswift run CodexAgentMonitor\n```\n\nWhen launched from Codex, the app runs from the agent PTY. The menu-bar item appears in the macOS menu bar.\n\nBuild a local ad-hoc signed app bundle:\n\n```sh\n./script/build_app.sh release\nopen dist/CodexAgentMonitor.app\n```\n\n## Tests\n\n```sh\n./script/run_tests.sh\n./script/run_ui_smoke.sh\n```\n\nThe current Command Line Tools environment cannot import XCTest/Testing, so core checks run through `CodexAgentMonitorTestRunner`. Full validation also runs `CodexAgentMonitorE2ERunner`, which simulates an orchestrator agent and tester agent end to end. Use `swift run CodexAgentMonitorE2ERunner -- --live` to slow the feed down for menu-bar inspection.\n\n## Local Event Writer\n\nAppend a sample integration event to the observed JSONL feed:\n\n```sh\nswift run CodexAgentMonitorEventWriter\n```\n\nCustom sample event:\n\n```sh\nswift run CodexAgentMonitorEventWriter -- --id writer-cli-test --name \"Writer CLI Test\" --status blocked --task \"Validate CLI args\" --activity \"Custom event emitted\"\n```\n\n## Local HTTP Ingest Daemon\n\nRun a local observe-only HTTP helper that appends posted `MonitorEvent` JSON to the event log:\n\n```sh\nswift run CodexAgentMonitorIngestDaemon -- --port 8765\n```\n\nFor one-shot validation:\n\n```sh\nswift run CodexAgentMonitorIngestDaemon -- --once --port 8765\n```\n\n## Codex Session Mirror\n\nImport a real Codex session JSONL file into the app-readable event log:\n\n```sh\nswift run CodexAgentMonitorSessionMirror -- --session ~/.codex/sessions/YYYY/MM/DD/rollout-file.jsonl\n```\n\nIf `--session` is omitted, the mirror imports the most recently modified `.jsonl` file under `~/.codex/sessions`.\n\nFor isolated validation without touching the live app feed:\n\n```sh\nswift run CodexAgentMonitorSessionMirror -- --session ~/.codex/sessions/YYYY/MM/DD/rollout-file.jsonl --event-log /tmp/codex-agent-monitor-events.jsonl\n```\n\nFollow a session file and mirror new records into the live app feed:\n\n```sh\nswift run CodexAgentMonitorSessionMirror -- --session ~/.codex/sessions/YYYY/MM/DD/rollout-file.jsonl --follow\n```\n\nFor deterministic validation, bounded follow mode is available:\n\n```sh\nswift run CodexAgentMonitorSessionMirror -- --session /tmp/session.jsonl --event-log /tmp/events.jsonl --follow --poll-interval 0.2 --max-polls 4\n```\n\n## Event Log Contract\n\nDefault path:\n\n```text\n~/.codex-agent-monitor/events.jsonl\n```\n\nEach line is one JSON event. Dates use ISO-8601.\n\nSupported event types:\n\n- `agent_started`\n- `agent_updated`\n- `agent_status_update`\n- `agent_finished`\n- `agent_completed`\n- `agent_error`\n- `token_usage_updated`\n- `permission_warning_triggered`\n- `session_activity_recorded`\n\nExample:\n\n```json\n{\"type\":\"agent_started\",\"agent\":{\"id\":\"local-main\",\"name\":\"Primary Codex\",\"status\":\"running\",\"currentTask\":\"Implement feature\",\"startedAt\":\"2026-05-17T12:00:00Z\",\"updatedAt\":\"2026-05-17T12:00:10Z\",\"activity\":\"Reading files\"}}\n```\n\nSee [Architecture](docs/architecture.md) for the full model boundary. See [End-to-End Testing](docs/e2e-testing.md) for the orchestrated tester-agent simulation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaba-burduli%2Fcodexagentmonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaba-burduli%2Fcodexagentmonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaba-burduli%2Fcodexagentmonitor/lists"}