AgentValley

Product Introduction

1. Definition: AgentValley is a free, open-source macOS menu bar application (a "notch app") designed specifically for users of Anthropic's Claude Code. It functions as a real-time activity monitor and management dashboard, aggregating data from all active Claude Code sessions and sub-agents across the user's system.
2. Core Value Proposition: It exists to solve the context-switching and visibility problem inherent in running multiple, concurrent AI coding agents. By providing a unified, glanceable overview directly in the MacBook's notch area, it enables developers to instantly see which agents are working, which models they are using, and crucially, which ones are waiting for user input, thereby streamlining the AI-assisted development workflow.

Main Features

1. Unified Notch-Based Activity Panel: The app resides in the MacBook's screen notch. Hovering over or clicking it opens a panel displaying all active Claude Code sessions. Each session is represented by a card, and each sub-agent (e.g., Explore, Plan) within that session gets its own row. Every agent is personified with a unique "little pixel programmer" avatar for quick visual identification.
   • How it works: The application passively reads Claude Code's local project and session data files (from ~/.claude/projects and ~/.claude/sessions). It cross-references this with system processes and .git directories to determine the active application, terminal, and branch for each session, presenting this data in a structured, real-time UI.
2. Real-Time Agent Status & Notification System: The interface displays the current task, elapsed time, assigned Claude model (Opus, Sonnet, Haiku), and the latest action (e.g., "> Grep PaymentIntent") for every agent. A prominent red counter badge appears on the notch icon when any agent requires user attention (e.g., asks a question or needs command approval).
   • How it works: The app monitors session state changes. When an agent enters a "needs you" state, it triggers the visual badge. Users can then open the panel to see the specific question or command awaiting approval and can often respond directly from the notch using an optional plugin.
3. Integrated Cost Tracking & History Export: AgentValley includes a detailed usage history and cost estimation feature. It tracks token usage per session and project, calculating estimated costs based on current Anthropic API pricing. This data can be filtered by day, week, month, or project and exported as a professional PDF "statement of work" for client billing or team reporting.
   • How it works: The app parses usage data from Claude Code's logs, applying the official Anthropic API token pricing models. All historical data is stored locally in ~/Library/Application Support/AgentValley and persists independently of Claude Code's own log rotation.

Problems Solved

1. Pain Point: Context Switching Overhead and Lost Visibility. Developers using Claude Code often run multiple sessions or worktrees simultaneously, each potentially spawning sub-agents. Manually switching between terminal tabs or windows to check the status of each agent is disruptive and inefficient, leading to delays in responding to agents that are blocked.
2. Target Audience: Professional Software Developers and Engineering Teams who actively use Claude Code for daily development tasks, code review, refactoring, and exploration. It is particularly valuable for tech leads, freelancers, and agencies that need to track time and cost across multiple projects or client work.
3. Use Cases:
   • Monitoring a Multi-Agent Refactoring Job: Watching a main Sonnet agent refactor a checkout flow while its Haiku sub-agent maps payment call sites and another Sonnet agent writes tests, all from a single pane.
   • Client Work Billing: Generating a PDF report of all Claude Code activity and associated costs for a specific project over a month to invoice a client.
   • Debugging "Stuck" Workflows: Quickly identifying which agent in a complex chain has gone "quiet" (inactive for 2+ minutes) without scanning every terminal.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):
   • Pros:
     • Zero-Configuration Monitoring: Requires no setup; installs and immediately begins displaying data from existing Claude Code sessions.
     • Non-Invasive & Secure: It is a read-only observer for core functionality. It does not modify Claude Code's files or interact with agents unless the optional plugin is installed.
     • Deep Terminal Integration (Optional): Can inject a custom status line and agent avatars directly into supported terminals (Terminal, iTerm2, Ghostty, Cursor), enhancing the in-terminal experience.
     • Transparent Cost Control: Provides real-time and historical visibility into AI usage costs, a critical feature for budget-conscious users.
   • Cons:
     • Platform & Hardware Lock-in: Exclusively for macOS 15+ on MacBooks with a notch. Does not support Windows, Linux, or older Macs.
     • Vendor Lock-in: Solely supports Anthropic's Claude Code. Useless for users of GitHub Copilot, Cursor AI, or other AI coding assistants.
     • Plugin Dependency for Full Interactivity: The convenient "Allow once/Deny" buttons in the notch require a separate, user-installed Claude Code plugin.
2. Key Alternatives & Differentiation:
   • Manual Terminal Tab Management: The default alternative is simply switching between terminal tabs.
     • Differentiation: AgentValley provides aggregated, summarized status across all tabs in one location with visual priority highlighting, eliminating the need to check tabs individually.
   • Claude Code's Native UI: Claude Code itself shows agent status within its terminal interface.
     • Differentiation: AgentValley offers a global, application-agnostic view. It shows status across all terminals and projects simultaneously and adds cost tracking, history, and system-level notifications (notch badge) that the native UI lacks.
   • General System Monitoring Tools (e.g., Activity Monitor): These show process-level data.
     • Differentiation: AgentValley operates at the task and semantic level, showing what the AI is actually doing ("Refactor checkout flow"), which model is doing it, and its progress, rather than just CPU/memory usage of a claude process.

Frequently Asked Questions (FAQ)

1. Is AgentValley safe? Does it send my data to external servers? AgentValley is open-source, allowing full code audit. For core monitoring, it only reads local files generated by Claude Code and your system's running processes. It sends data externally only when you explicitly enable "Plan limits" (to check your Anthropic API usage via api.anthropic.com) or for its once-daily update check. All cost history is stored locally on your Mac.
2. Can I use AgentValley with GitHub Copilot or other AI coding tools? No. AgentValley is built specifically to integrate with Anthropic's Claude Code ecosystem. It relies on Claude Code's specific file formats and processes and will not function with GitHub Copilot, Tabnine, or other AI programming assistants.
3. How does the "Answer from the notch" feature work? This feature requires you to manually install a separate Claude Code plugin (notch-answers@agent-valley). Once installed, when Claude Code requests permission for a command, the request appears in the AgentValley panel with "Allow once" and "Deny" buttons. Clicking "Allow once" triggers the plugin, which sends the approval back to the specific Claude Code session.
4. What are the system requirements for AgentValley? AgentValley requires macOS 15 (Sequoia) or later and a MacBook with a physical notch in the display (introduced in 2021). You must also have Claude Code installed and set up. It will not run on macOS 14 (Sonoma) or earlier, or on Macs without a notch (e.g., Mac Studio, older MacBook Pros).
5. Does AgentValley slow down Claude Code or my computer? The application is designed to be lightweight. It operates by polling file changes and process lists, which has minimal performance impact. It does not intercept or process the actual AI model inference, so it does not affect the speed or operation of Claude Code itself.