jamesrochabrun/AgentHub: Native macOS Hub for Claude Code & Codex

Developers running multiple AI coding agents face a familiar friction: Claude Code in one terminal tab, Codex in another, Git worktrees scattered across the filesystem, and no unified way to monitor what each agent is actually doing. Context switching between terminal windows, reviewing diffs in separate tools, and manually tracking session state burns cognitive overhead that compounds across a workday.

jamesrochabrun/AgentHub addresses this directly. It's a native macOS application that aggregates Claude Code and Codex sessions into a single monitoring hub, embeds terminals and diff review, manages Git worktrees from the UI, and runs entirely on your machine. Built in Swift for macOS 14.0+, it reads local CLI session files to render live state without polling or external data transmission.

This article breaks down what AgentHub does, how it fits into agentic development workflows, and how to get it running.

What is jamesrochabrun/AgentHub?

AgentHub is an open-source macOS application maintained by James Rochabrun, distributed under the MIT License. With 457 GitHub stars and 33 forks as of its last commit on July 14, 2026, it occupies a specific niche: local-first session management for CLI-based AI coding agents.

The tool sits between you and the Claude Code and Codex CLIs. Rather than replacing either tool, AgentHub wraps them—reading session JSONL files from ~/.claude/projects/ and ~/.codex/sessions/, rendering live session cards, embedding PTY terminals via SwiftTerm, and providing side-panel tools for diff review, web preview, and GitHub integration. It does not proxy API calls or intermediate between you and Anthropic/OpenAI; all agent execution happens in the underlying CLI processes that AgentHub spawns and monitors.

The project's relevance tracks the rise of agentic coding workflows. As developers increasingly delegate file edits, test runs, and refactoring to autonomous CLI agents, the need for oversight tooling grows. AgentHub treats this as a local developer experience problem rather than a cloud orchestration challenge—no SaaS signup, no data exfiltration, no subscription tier.

Key Features

Multi-provider session monitoring. AgentHub displays Claude Code and Codex sessions in a unified hub panel with single, list, 2-column, and 3-column grid layouts. Real-time updates are driven by file-system watchers on the CLI session files, eliminating polling overhead.

Embedded PTY terminal. Each session card contains a full terminal via SwiftTerm. You can resume existing sessions or start new ones without leaving the app. An auxiliary Hub shell (toggle with Cmd+J) follows the selected session's worktree and maintains shell state per session.

Inline diff review and pending changes preview. AgentHub renders split-pane diffs for Edit/Write/MultiEdit tool approvals and includes an inline editor to send change requests directly back to Claude. The eye icon for pending edits appears in real time through a Claude Code approval hook.

Git worktree management. Create and delete sibling worktrees from the UI, launch sessions on new branches, and control whether worktree sessions group under their parent module or appear as separate modules. Sparse checkout support for subdirectory launches reduces materialization overhead in monorepos.

Web and iOS Simulator preview. AgentHub detects localhost servers started by agents, falls back to static index.html, and supports batch UI update requests via inspect/crop tools. For Xcode projects, it can build, install, and mirror a booted iOS Simulator with hot-reload support via InjectionLite.

GitHub integration via gh CLI. Browse PRs and issues, inspect diffs and CI checks, and send context back into active sessions. PR state and CI status appear on session rows when a branch has an open PR.

MCP Apps rendering. When agents produce MCP app UIs (e.g., Excalidraw diagrams), AgentHub renders them in a dedicated panel with consent-gated, lazy access to the MCP server actually used by the agent.

Additional tooling: Global search across session files, usage stats with token/cost tracking, command palette (Cmd+K), Mermaid diagram rendering, Storybook auto-detection and launching, plan view for Claude-generated plan files with annotation, and 9 bundled YAML themes with WCAG-compliant contrast.

Use Cases

Parallel agent task management. A developer kicks off a Codex session for API refactoring and a Claude Code session for frontend component migration simultaneously. AgentHub's multi-session launcher (with optional AI-planned "Smart mode" orchestration) starts both, and the hub panel tracks each session's state—Thinking, Executing Tool, Awaiting Approval, Idle—without tab-switching.

Isolated feature branches with worktrees. Using the "Remix" feature, branch any session into a git worktree with the original transcript passed as context. The new worktree session can switch providers (Claude to Codex or vice versa), keeping experimental changes isolated from the main working tree.

Code review without context loss. When Claude proposes a multi-file edit, review the split-pane diff in AgentHub, add inline comments, and send batch feedback directly to the agent's interactive prompt. No copy-pasting diffs into a separate review tool.

iOS development with live iteration. Build and run on a booted iOS Simulator directly from a session card, annotate UI elements with structured feedback sent back to the agent, and hot-reload Swift file changes without restarting the simulator app process.

Storybook-driven component work. For Storybook-enabled projects, AgentHub replaces the generic Preview button with a dedicated Storybook launcher that starts the dev server on a compound key, running alongside your primary app server without port collision.

Installation & Setup

AgentHub requires macOS 14.0+ and the following CLI tools installed and authenticated:

• Claude Code CLI — required
• Codex CLI — optional, for Codex features
• GitHub CLI — optional overall, required for GitHub integration

Download the latest release from GitHub Releases. The app is code-signed and notarized by Apple. Updates deploy automatically via Sparkle with EdDSA signature verification.

GitHub CLI Setup (Optional)

# Install gh if not present
# Authenticate
gh auth login

# Verify authentication
gh auth status

AgentHub uses your existing gh authentication; it does not manage GitHub tokens independently.

Claude Code Approval Hook (Optional but Recommended)

AgentHub can install a per-worktree approval hook to detect pending tool approvals in real time. The hook writes a single entry to {project}/.claude/settings.local.json (gitignored by default) pointing to a script at ~/Library/Application Support/AgentHub/hooks/agenthub-approval.sh. Enable or disable this in Settings → General → Enable approval hooks.

Without the hook, AgentHub cannot surface "Awaiting Approval" state or preview pending diffs until after you've already responded to the CLI prompt.

Theme Customization (Optional)

# Create themes directory
mkdir -p ~/Library/Application\ Support/AgentHub/themes/

# Place custom YAML theme files here; they hot-reload on save

Real Code Examples

The AgentHub README does not contain extensive inline code samples; the following reflects the configuration patterns and file paths documented in the project.

Session Data Paths

AgentHub reads Claude Code session data from:

# Claude Code sessions
~/.claude/projects/{encoded-path}/{sessionId}.jsonl

And Codex data from:

# Codex session files
~/.codex/sessions/{date-path}/

# Codex history
~/.codex/history.jsonl

These paths are read-only; AgentHub does not modify CLI session formats. The {encoded-path} component is derived from the repository path, allowing per-project session isolation.

MCP Server Configuration Shapes

AgentHub parses MCP server configurations without mutating them. For Claude:

// ~/.claude.json — top-level or per-project mcpServers
{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "@excalidraw/mcp-server"],
      "env": {
        "NODE_ENV": "production"
      },
      "cwd": "/optional/working/directory"
    }
  }
}

For Codex:

# ~/.codex/config.toml
[mcp_servers.excalidraw]
command = "npx"
args = ["-y", "@excalidraw/mcp-server"]
cwd = "/optional/working/directory"

[mcp_servers.excalidraw.env]
NODE_ENV = "production"

Remote MCP servers are supported for unauthenticated HTTP/streamable HTTP or legacy SSE endpoints. Authenticated remote MCP servers are explicitly unsupported in the current release.

Custom Theme YAML Structure

name: My Theme
version: 1
author: Your Name
colors:
  brand:
    primary: "#7C3AED"
    secondary: "#6D28D9"
    tertiary: "#5B21B6"
  backgrounds:
    dark: "#1A1A2E"
    light: "#FFFFFF"

Place this file in ~/Library/Application Support/AgentHub/themes/; AgentHub hot-reloads on save.

Build Command (Documented)

# Known-good build path from the README
xcodebuild -workspace app/AgentHub.xcodeproj/project.xcworkspace -scheme AgentHub build

This is the verified build invocation for contributors working from source.

Advanced Usage & Best Practices

Worktree strategy for monorepos. When launching agents from subdirectories like ios/features/foo, AgentHub creates sparse-checkouted worktrees with inferred owner paths. For full repository access, explicitly request fullCheckout; otherwise, you may miss cross-package dependencies that the agent needs to analyze.

Simulator preview limitations. Only one armed preview session at a time due to a fixed loopback port. If you switch between Xcode projects, expect to rebuild the hot-reload host package under ~/Library/Application Support/AgentHub/HotReloadHost/—this can take 1–2 minutes on first use.

Provider defaults behavior. Settings for model, effort, and tool permissions apply only to new embedded sessions. Resumed sessions retain their original configuration. This prevents mid-session flag injection from breaking ongoing agent context.

GitHub monitoring overhead. Initial PR/CI state refresh is delayed until after the app appears to avoid slowing launch. If session rows seem stale, use the refresh button in the session list header rather than restarting AgentHub.

Privacy verification. Since AgentHub runs entirely locally, you can verify this by monitoring network traffic (e.g., Little Snitch, nettop)—the app makes no outbound connections except for Sparkle update checks and any agent-initiated connections from the embedded terminals themselves.

Comparison with Alternatives

AgentHub's specific value is orchestration visibility—seeing and interacting with multiple CLI agent sessions simultaneously in a native interface. If you primarily use one agent in one terminal, the overhead of a hub app may not justify itself. If you run parallel agents across worktrees and want inline diff review without leaving your workflow, AgentHub fills a gap that raw CLI and IDE extensions do not address.

FAQ

Q: Does AgentHub work on Windows or Linux? A: No—macOS 14.0+ only. The Swift/SwiftUI codebase and Simulator integration are platform-specific.

Q: Do I need paid API access for Claude or Codex? A: AgentHub does not handle API billing; you use your existing Claude Code and Codex CLI installations with their respective authentication.

Q: Can AgentHub run without the approval hook? A: Yes, but real-time pending diff preview and "Awaiting Approval" state detection will not work until after you respond to CLI prompts.

Q: Is my code sent to any server? A: No. AgentHub reads local session files and runs entirely on your machine. The MIT License source is auditable.

Q: How does AgentHub handle Codex's lack of plan mode? A: The Codex provider pill is disabled when plan mode is active in AgentHub, since Codex CLI lacks a startup flag for plan mode. Track upstream support at openai/codex #12738.

Q: Can I use custom fonts in the terminal? A: Yes—choose from 9 bundled monospace fonts including JetBrains Mono, Fira Code, and GeistMono in Settings → Appearance.

Q: What happens to terminal processes when I close a session card? A: AgentHub terminates both the card terminal and auxiliary Hub shell process tree to prevent orphaned CLI sessions.

Conclusion

jamesrochabrun/AgentHub targets a specific developer profile: macOS users running Claude Code and/or Codex who need visibility across multiple sessions, worktrees, and review workflows without surrendering data to a cloud service. It does not replace the underlying CLIs or abstract away their configuration—it augments them with native UI affordances that terminal multiplexers and raw JSONL files do not provide.

The tool is best suited for developers already committed to agentic coding workflows who feel the friction of context-switching between terminal tabs, diff tools, and Git operations. Its privacy-first, local-only architecture is a genuine differentiator in a landscape of cloud-hosted alternatives. With active development as of mid-2026 and an MIT License, it is worth evaluating if your workflow matches its design center.

Explore the source, download releases, and file issues at https://github.com/jamesrochabrun/AgentHub.