Hallmonitor

Product Introduction

1. Definition: Hallmonitor is a free, open-source, cross-platform (macOS, Linux) system monitoring and observability tool specifically designed for AI-powered coding agents. It functions as a real-time dashboard and status aggregator for Anthropic's Claude Code and Codex sessions.
2. Core Value Proposition: Hallmonitor exists to solve the developer productivity problem of context switching and agent sprawl. It provides centralized, at-a-glance visibility into the status, activity, and resource consumption of all active AI coding assistants across local and remote machines, enabling developers to manage workflows efficiently and avoid wasted time.

Main Features

1. Unified Real-Time Dashboard ("The Board"): This terminal-based TUI (Text User Interface) provides a live, color-coded overview of all Claude Code and Codex sessions. It groups sessions by status: "Needs You" (pulsing amber for prompts/errors), "Working" (spinning animation), and "Idle". Each card displays detailed metadata including project directory, AI model, context size, current tool in use, last prompt snippet, and a subagent count. A waveform visualization at the top aggregates fleet-wide activity over recent minutes. Navigation is keyboard-driven (arrow keys, Enter to jump to session).
2. Native macOS Integration (Menu Bar & Dynamic Island/Notch): For macOS 14+ users, Hallmonitor offers a lightweight menu bar application. It provides a standard macOS menu listing active agents and status. On MacBook Pros, it integrates with the Dynamic Island ("the notch"), displaying minimal "ears" for active agents. It can proactively drop down notifications when an agent needs attention or completes a task. A key opt-in feature, "Answer from the notch," allows users to directly respond to Claude Code's permission prompts or questions via interactive notifications, routing the response through Claude's own hook system (hallmonitor hook --install).
3. Cross-Machine Monitoring via SSH: Hallmonitor can monitor sessions on remote servers (e.g., GPU boxes, dev servers) without requiring a persistent daemon or open firewall ports. It establishes a single SSH connection per host (defined via --host flag or a config file) and streams session data using hallmonitor --stream. The dashboard visually indicates host connectivity status (green/red chips). This uses standard key-based SSH authentication.
4. Comprehensive Usage Analytics & Limit Tracking: The tool maintains a local, privacy-focused usage ledger (~/.local/share/hallmonitor/usage/) by parsing existing agent logs. It tracks metrics like agent-hours per day, token usage trends, cache hit rates, top projects, and frequently used models/tools. Crucially, it automatically surfaces plan limit status for both Claude Code (by periodically and safely querying its internal /usage endpoint) and Codex (from its logs), displaying remaining quotas directly in the menu bar and dashboard.

Problems Solved

1. Pain Point: Agent State Ambiguity and Context Loss. Developers lose track of which AI coding sessions are active, which are stuck awaiting input, and which have finished, leading to wasted time searching through terminals and apps.
2. Target Audience: Professional Developers and Engineering Teams using Claude Code and/or Codex extensively, especially those who multitask across multiple projects or utilize remote development environments. It's particularly valuable for tech leads managing team resources and individuals pushing against AI service usage limits.
3. Use Cases: Monitoring a fleet of long-running code generation/refactoring jobs on a remote server; Quickly triaging which of several active Claude Code sessions requires a human decision; Keeping a real-time pulse on team-wide AI agent usage and remaining budget; Reducing interruptions by answering simple Claude queries directly from system notifications.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros:
     • Zero-Cost & Transparent: Free, open-source (MIT licensed), with no telemetry, accounts, or data exfiltration.
     • Non-Invasive & Secure: Operates in read-only mode by default, parsing only public session metadata and logs. Requires explicit opt-in for any write action (answering prompts).
     • Lightweight & Native: Low CPU footprint (~1% in menu bar). The macOS app uses native APIs for seamless integration.
     • Unified Cross-Platform View: Aggregates data from both local machines and remote servers over standard SSH into a single pane of glass.
   • Cons/Limitations:
     • Vendor-Locked: Exclusively supports Anthropic's Claude Code and Codex. Does not monitor other AI coding assistants like GitHub Copilot, Cursor, or Windsurf.
     • macOS-Centric Features: The Dynamic Island integration and native menu bar app are exclusive to macOS 14+, limiting feature parity for Linux/Windows CLI users.
     • Setup for Advanced Features: Enabling "Answer from the notch" requires modifying Claude Code's configuration (settings.json), which may be intimidating for non-technical users.
     • Dependent on Agent Logs: Accuracy and completeness of data rely on the stability and format of Claude/Codex's own logging output.

2. Key Alternatives & Differentiation:

   • Manual Terminal/App Switching: The default alternative. Hallmonitor differentiates by providing aggregated, prioritized status visualization and remote monitoring, eliminating the need to manually check each session.
   • Built-in Agent Status (Claude Desktop App): Claude Code's app shows active sessions but only for itself, locally. Hallmonitor differentiates by combining data from both Claude Code and Codex, across multiple machines, with richer analytics and system-level integration (notch, menu bar).
   • Generic Process Monitors (htop, lsof): Tools like htop can show claude or codex processes but cannot interpret their semantic state (e.g., "waiting for user approval," "running tool X"). Hallmonitor is purpose-built to understand and display the specific workflow states of AI coding agents.

Frequently Asked Questions (FAQ)

1. Is Hallmonitor safe? Does it send my code or API keys anywhere? Hallmonitor is designed with privacy as a core principle. It operates locally in a read-only manner by default, parsing only session metadata and transcript tails from standard log locations. It never accesses authentication tokens or keys. The optional "answer" feature sends only the specific clicked response back to Claude Code via its official hook interface. No telemetry data is collected.
2. How does Hallmonitor track Claude Code usage limits without my login? It leverages Claude Code's own local API. The app or CLI tool periodically opens Claude Code's /usage endpoint in a safe, isolated mode (no hooks, MCP, or tools active) within a temporary directory. This endpoint returns the limit data already available in your locally logged-in Claude app. The session transcript for this probe is deleted afterward. It does not use or require your Anthropic API tokens.
3. Can I use Hallmonitor to monitor AI agents on a headless Linux server? Yes. Install the hallmonitor CLI binary on the server via the provided Homebrew tap or direct download. You can then stream its data to your local dashboard by adding it as a --host (e.g., --host user@server). The server only needs the CLI tool and standard SSH access; no GUI or special ports are required.
4. What happens if Hallmonitor or the hook system breaks after an update? The tool includes safety measures. The hallmonitor hook --install command creates a backup of your original ~/.claude/settings.json file. If you encounter issues, you can run hallmonitor hook --uninstall to revert the changes, or manually restore from the backup. The core monitoring functionality is separate and will continue to work in read-only mode.
5. How does Hallmonitor impact the performance of my coding agents? The impact is negligible. The monitoring is passive, based on reading log files and occasional safe API calls. The menu bar app uses minimal system resources (~1% CPU). The SSH connections for remote monitoring are lightweight and persistent, designed to avoid connection overhead.