jamesrochabrun/AgentHub
GitHub: jamesrochabrun/AgentHub
Stars: 394 | Forks: 29
# AgentHub
## Features
### GitHub Monitoring
AgentHub can monitor the current branch PR for each visible session and show its PR state plus CI summary in the session row. Branches with no pull request stay quiet, so the list only adds GitHub context when there is something actionable to show.
Monitoring is designed to avoid slowing down launch: initial GitHub refresh work is delayed after the app appears, session rows observe through a shared service, and the refresh button in the session list header can force an update whenever you want fresh GitHub state.
### GitHub Setup
GitHub features are optional, but any GitHub access in AgentHub depends on the GitHub CLI:
1. Install [`gh`](https://cli.github.com/).
2. Authenticate with `gh auth login`.
3. Open any GitHub repository in AgentHub and use the `GitHub` action from the session UI.
## File Explorer
AgentHub includes a built-in file explorer and editor for supported text files. Open the quick file picker with **Cmd+P** to jump directly to a file, then edit and save changes from inside the side panel without leaving the app.
File explorer, quick open, and built-in editor
https://github.com/user-attachments/assets/6d263d11-6648-42e7-9335-04aa51a33296
## Storybook
When AgentHub detects a Storybook configuration in a project, the regular **Preview** button on each session card is replaced by a dedicated **Storybook** button. Clicking it spawns the Storybook dev server (via `npm run storybook`) and opens the web preview pane pinned to the Storybook URL — independently of any other dev server the agent has running.
### Detection
A project is treated as Storybook-enabled if **any** of these is true:
- A `.storybook/` directory exists at the project root
- `package.json` has a `"storybook"` or `"storybook:dev"` script entry
- `package.json` devDependencies contains any `@storybook/*` package
Detection lives in the standalone `Storybook` Swift module (`app/modules/Storybook/`), which has zero dependencies and can be reused outside `AgentHubCore`.
### How it runs
- The Storybook server is keyed by `"{sessionId}:storybook"` in `DevServerManager`, so it coexists with your primary dev server (Vite, Next, etc.) under the plain `sessionId` key.
- If your `storybook` npm script already pins a port (e.g. `storybook dev -p 6006`), AgentHub honors that port instead of trying to override it — npm appends extra args after the script's, and Storybook only respects the first `-p`, so passing our own would desync the bind port from the tracked port.
- If port 6006 is in use and Storybook prompts to use an alternate port, AgentHub auto-accepts; the actual port is captured from Storybook's `Local: http://localhost:N/` ready banner.
- The web preview pane in Storybook mode resolves URLs from the storybook server slot only; it does not follow the agent's app-server URL changes, so the Storybook view stays pinned even if the agent restarts the primary dev server.
## Requirements
- macOS 14.0+
- [Claude Code CLI](https://claude.ai/claude-code) installed and authenticated
- [Codex CLI](https://openai.com/index/introducing-codex/) installed (optional, for Codex features)
- [GitHub CLI](https://cli.github.com/) installed and authenticated (optional overall, required for GitHub access/features)
## Installation & Updates
Download the latest release from [GitHub Releases](https://github.com/jamesrochabrun/AgentHub/releases). The app is code-signed and notarized by Apple.
Updates are delivered automatically via [Sparkle](https://sparkle-project.org/) with EdDSA signature verification. You'll be prompted when a new version is available.
## Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| **Cmd+K** | Open command palette |
| **Cmd+P** | Quick open files |
| **Cmd+N** | New session |
| **Cmd+B** | Toggle sidebar |
| **Cmd+J** | Toggle Hub auxiliary shell |
| **Cmd+,** | Open settings |
| **Cmd+Shift+O** | Expand/collapse the embedded web preview |
| **Cmd+[** | Navigate to previous session |
| **Cmd+]** | Navigate to next session |
| **Cmd+\\** | Toggle focus mode (single ↔ previous layout) |
| **Cmd++** | Increase terminal font size |
| **Cmd+-** | Decrease terminal font size |
| **Escape** | Dismiss maximized card / side panel / sheet |
### Diff View
| Shortcut | Action |
|---|---|
| **Return** | Send inline comment to Claude |
| **Cmd+Return** | Add comment to review collection |
| **Shift+Return** | Insert newline in editor |
| **Escape** | Close inline editor or diff view |
### File Explorer
| Shortcut | Action |
|---|---|
| **Cmd+P** | Open quick file picker |
| **Cmd+S** | Save current file in file editor |
| **Escape** | Close quick file picker or file editor |
### Web Preview
| Shortcut | Action |
|---|---|
| **Cmd+Shift+O** | Expand/collapse the embedded web preview |
| **Cmd+Shift+I** | Cycle inspect, crop, edit, and off |
| **Cmd+R** | Reload preview |
| **Cmd+Return** | Send queued canvas feedback or update preview |
| **Escape** | Close preview |
### Embedded Terminal
| Shortcut | Action |
|---|---|
| **Cmd+C** | Copy selected text |
| **Cmd+V** | Paste |
| **Cmd+A** | Select all |
| **Cmd+Left / Cmd+Up** | Move to beginning of line |
| **Cmd+Right / Cmd+Down** | Move to end of line |
| **Cmd+Backspace** | Delete to beginning of line |
| **Cmd+Forward Delete** | Delete to end of line |
| **Option+Left** | Move back one word |
| **Option+Right** | Move forward one word |
| **Option+Backspace** | Delete previous word |
| **Option+Forward Delete** | Delete next word |
| **Cmd+Ctrl+Arrow** | Focus adjacent terminal pane |
| **Cmd+Ctrl+Shift+Left / Right** | Select previous / next terminal tab |
| **⌥↩ / ⌘↩ / ⇧↩** | Insert newline (configurable in Settings → Terminal) |
### Command Palette
| Shortcut | Action |
|---|---|
| **Up / Down** | Navigate items |
| **Return** | Execute selected action |
| **Escape** | Close palette |
## Hub Layouts
The monitoring panel supports multiple layout modes:
| Mode | Description |
|---|---|
| **Single** | One session at full size with optional side panel (diff, plan, web preview) |
| **List** | Vertical card list grouped by provider |
| **2-Column** | Two-column grid |
| **3-Column** | Three-column grid |
Any card can be maximized to full panel with a click (Escape to restore).
In list mode, cards can be resized with a drag preview that commits on release.
## Session States
| Status | Description |
|---|---|
| Thinking | Claude/Codex is processing |
| Executing Tool | Running a tool call |
| Awaiting Approval | Tool requires user confirmation |
| Waiting for User | Awaiting input |
| Idle | Session inactive |
## Plan Mode
Plan mode lets Claude read and analyze your codebase without executing any changes.
Toggle it on or off with **Shift+Tab** inside the prompt editor in the multi-session launcher.
When active, a teal indicator appears below the prompt.
| Provider | Behavior |
|---|---|
| **Claude** | Launched with `--permission-mode plan`; reads files and plans but does not write or execute |
| **Codex** | Not available — the Codex CLI has no flag to start in plan mode |
## Configuration
AgentHub's settings window is organized into four tabs:
- **General** — Notifications and app-wide behavior such as opening the file explorer in a modal window
- **Configuration** — Claude and Codex CLI commands, provider-specific defaults, and Smart mode
- **Worktrees** — Worktree module grouping and generated branch naming
- **Appearance** — Flat session layout, terminal preferences, and theme selection
### Display Mode
AgentHub supports two display modes:
- **Menu Bar Mode** (default) — Stats appear in the system menu bar
- **Popover Mode** — Stats appear as a toolbar button in the app window
Toggle between modes in the app settings.
### Worktree Grouping
Worktree sessions are grouped under their parent module by default, so `ModuleA` shows its regular sessions plus AgentHub-owned worktree sessions. The Worktrees settings tab can switch to separate modules, where each AgentHub-owned worktree appears as its own module section.
AgentHub creates new worktrees as sibling directories beside the main repository, using the generated or manual directory name directly under the repository's parent directory. It no longer creates a repo-local `.worktrees` folder or adds `.worktrees/` to Git's exclude file.
AgentHub only treats worktrees it created, explicitly added, or focused through monitored sessions as owned. External Git worktrees discovered from the repository are ignored for session grouping, which keeps large local worktree setups from flooding the session list. The Worktrees settings inventory still lists all Git worktrees for tracked repositories: focused rows participate in AgentHub grouping, while external rows can be deleted without becoming focused.
### Provider Defaults
Provider defaults are applied only when AgentHub starts a new embedded CLI session. Resume flows keep the original session configuration and do not inject new model or approval flags.
These settings are persisted locally in AgentHub's SQLite metadata store.
#### Claude
AgentHub maps Claude defaults to the installed CLI flags:
- `Model` → `--model `
- `Effort` → `--effort `
- `Allowed Tools` → `--allowedTools `
- `Denied Tools` → `--disallowedTools `
The Claude tool lists in Settings accept either comma-separated values or one pattern per line. AgentHub normalizes both forms before launching the session.
#### Codex
AgentHub maps Codex defaults to the current interactive CLI flags:
- `Model` → `--model `
- `Approval` → `-a untrusted|on-request|never`; `Full-Auto` maps to `--sandbox workspace-write`
- `Effort` → `-c model_reasoning_effort="low|medium|high|xhigh"`
These mappings are verified in unit tests against the current CLI surface exposed by `codex --help` and `claude --help`.
### Claude Code approval hook
AgentHub detects pending `Edit` / `Write` / `MultiEdit` / `Bash` / etc. approvals in real time by installing a small **Claude Code hook**. `PermissionRequest` events mark real approval prompts, while `PreToolUse` records the current permission mode so AgentHub can suppress false "Awaiting Approval" states when Claude Code is in `auto` mode. Without the hook, Claude Code's CLI only writes the pending `tool_use` block to disk after the turn commits — which means AgentHub can't surface an "Awaiting Approval" state (or preview a pending diff) until *after* you've answered the prompt. Enabling the hook is what makes the `eye` / Edits button and the `awaitingApproval` sidebar status appear *during* the approval window.
**What we promise to preserve.** Every other key in `settings.local.json` — `permissions`, `env`, `mcpServers`, and any hook entries you or other tools have added — stays byte-for-byte. Our entry is identified by the absolute path of the installed script, so uninstall removes only that entry and leaves everything else alone.
**Lifecycle.** Hooks install per worktree when a repo is added to AgentHub, stay installed while the repo is tracked, and are removed when you remove the repo, toggle the feature off in **Settings → General → Enable approval hooks**, or quit the app. External Claude Code sessions in the same worktree (e.g. started from Terminal.app) run the hook but it exits silently — a small ~50ms claim-file check makes sure AgentHub only observes sessions it's actively tracking.
### Session Data
~/.claude/projects/{encoded-path}/{sessionId}.jsonl
### Codex Data
- **Session files:** `~/.codex/sessions/{date-path}/` (JSONL format)
- **History file:** `~/.codex/history.jsonl`
### Custom Themes
name: My Theme
version: 1
author: Your Name
colors:
brand:
primary: "#7C3AED"
secondary: "#6D28D9"
tertiary: "#5B21B6"
backgrounds:
dark: "#1A1A2E"
light: "#FFFFFF"
## Privacy
## License
MIT
## Features
### GitHub Monitoring
AgentHub can monitor the current branch PR for each visible session and show its PR state plus CI summary in the session row. Branches with no pull request stay quiet, so the list only adds GitHub context when there is something actionable to show.
Monitoring is designed to avoid slowing down launch: initial GitHub refresh work is delayed after the app appears, session rows observe through a shared service, and the refresh button in the session list header can force an update whenever you want fresh GitHub state.
### GitHub Setup
GitHub features are optional, but any GitHub access in AgentHub depends on the GitHub CLI:
1. Install [`gh`](https://cli.github.com/).
2. Authenticate with `gh auth login`.
3. Open any GitHub repository in AgentHub and use the `GitHub` action from the session UI.
## File Explorer
AgentHub includes a built-in file explorer and editor for supported text files. Open the quick file picker with **Cmd+P** to jump directly to a file, then edit and save changes from inside the side panel without leaving the app.
File explorer, quick open, and built-in editor
https://github.com/user-attachments/assets/6d263d11-6648-42e7-9335-04aa51a33296
## Storybook
When AgentHub detects a Storybook configuration in a project, the regular **Preview** button on each session card is replaced by a dedicated **Storybook** button. Clicking it spawns the Storybook dev server (via `npm run storybook`) and opens the web preview pane pinned to the Storybook URL — independently of any other dev server the agent has running.
### Detection
A project is treated as Storybook-enabled if **any** of these is true:
- A `.storybook/` directory exists at the project root
- `package.json` has a `"storybook"` or `"storybook:dev"` script entry
- `package.json` devDependencies contains any `@storybook/*` package
Detection lives in the standalone `Storybook` Swift module (`app/modules/Storybook/`), which has zero dependencies and can be reused outside `AgentHubCore`.
### How it runs
- The Storybook server is keyed by `"{sessionId}:storybook"` in `DevServerManager`, so it coexists with your primary dev server (Vite, Next, etc.) under the plain `sessionId` key.
- If your `storybook` npm script already pins a port (e.g. `storybook dev -p 6006`), AgentHub honors that port instead of trying to override it — npm appends extra args after the script's, and Storybook only respects the first `-p`, so passing our own would desync the bind port from the tracked port.
- If port 6006 is in use and Storybook prompts to use an alternate port, AgentHub auto-accepts; the actual port is captured from Storybook's `Local: http://localhost:N/` ready banner.
- The web preview pane in Storybook mode resolves URLs from the storybook server slot only; it does not follow the agent's app-server URL changes, so the Storybook view stays pinned even if the agent restarts the primary dev server.
## Requirements
- macOS 14.0+
- [Claude Code CLI](https://claude.ai/claude-code) installed and authenticated
- [Codex CLI](https://openai.com/index/introducing-codex/) installed (optional, for Codex features)
- [GitHub CLI](https://cli.github.com/) installed and authenticated (optional overall, required for GitHub access/features)
## Installation & Updates
Download the latest release from [GitHub Releases](https://github.com/jamesrochabrun/AgentHub/releases). The app is code-signed and notarized by Apple.
Updates are delivered automatically via [Sparkle](https://sparkle-project.org/) with EdDSA signature verification. You'll be prompted when a new version is available.
## Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| **Cmd+K** | Open command palette |
| **Cmd+P** | Quick open files |
| **Cmd+N** | New session |
| **Cmd+B** | Toggle sidebar |
| **Cmd+J** | Toggle Hub auxiliary shell |
| **Cmd+,** | Open settings |
| **Cmd+Shift+O** | Expand/collapse the embedded web preview |
| **Cmd+[** | Navigate to previous session |
| **Cmd+]** | Navigate to next session |
| **Cmd+\\** | Toggle focus mode (single ↔ previous layout) |
| **Cmd++** | Increase terminal font size |
| **Cmd+-** | Decrease terminal font size |
| **Escape** | Dismiss maximized card / side panel / sheet |
### Diff View
| Shortcut | Action |
|---|---|
| **Return** | Send inline comment to Claude |
| **Cmd+Return** | Add comment to review collection |
| **Shift+Return** | Insert newline in editor |
| **Escape** | Close inline editor or diff view |
### File Explorer
| Shortcut | Action |
|---|---|
| **Cmd+P** | Open quick file picker |
| **Cmd+S** | Save current file in file editor |
| **Escape** | Close quick file picker or file editor |
### Web Preview
| Shortcut | Action |
|---|---|
| **Cmd+Shift+O** | Expand/collapse the embedded web preview |
| **Cmd+Shift+I** | Cycle inspect, crop, edit, and off |
| **Cmd+R** | Reload preview |
| **Cmd+Return** | Send queued canvas feedback or update preview |
| **Escape** | Close preview |
### Embedded Terminal
| Shortcut | Action |
|---|---|
| **Cmd+C** | Copy selected text |
| **Cmd+V** | Paste |
| **Cmd+A** | Select all |
| **Cmd+Left / Cmd+Up** | Move to beginning of line |
| **Cmd+Right / Cmd+Down** | Move to end of line |
| **Cmd+Backspace** | Delete to beginning of line |
| **Cmd+Forward Delete** | Delete to end of line |
| **Option+Left** | Move back one word |
| **Option+Right** | Move forward one word |
| **Option+Backspace** | Delete previous word |
| **Option+Forward Delete** | Delete next word |
| **Cmd+Ctrl+Arrow** | Focus adjacent terminal pane |
| **Cmd+Ctrl+Shift+Left / Right** | Select previous / next terminal tab |
| **⌥↩ / ⌘↩ / ⇧↩** | Insert newline (configurable in Settings → Terminal) |
### Command Palette
| Shortcut | Action |
|---|---|
| **Up / Down** | Navigate items |
| **Return** | Execute selected action |
| **Escape** | Close palette |
## Hub Layouts
The monitoring panel supports multiple layout modes:
| Mode | Description |
|---|---|
| **Single** | One session at full size with optional side panel (diff, plan, web preview) |
| **List** | Vertical card list grouped by provider |
| **2-Column** | Two-column grid |
| **3-Column** | Three-column grid |
Any card can be maximized to full panel with a click (Escape to restore).
In list mode, cards can be resized with a drag preview that commits on release.
## Session States
| Status | Description |
|---|---|
| Thinking | Claude/Codex is processing |
| Executing Tool | Running a tool call |
| Awaiting Approval | Tool requires user confirmation |
| Waiting for User | Awaiting input |
| Idle | Session inactive |
## Plan Mode
Plan mode lets Claude read and analyze your codebase without executing any changes.
Toggle it on or off with **Shift+Tab** inside the prompt editor in the multi-session launcher.
When active, a teal indicator appears below the prompt.
| Provider | Behavior |
|---|---|
| **Claude** | Launched with `--permission-mode plan`; reads files and plans but does not write or execute |
| **Codex** | Not available — the Codex CLI has no flag to start in plan mode |
## Configuration
AgentHub's settings window is organized into four tabs:
- **General** — Notifications and app-wide behavior such as opening the file explorer in a modal window
- **Configuration** — Claude and Codex CLI commands, provider-specific defaults, and Smart mode
- **Worktrees** — Worktree module grouping and generated branch naming
- **Appearance** — Flat session layout, terminal preferences, and theme selection
### Display Mode
AgentHub supports two display modes:
- **Menu Bar Mode** (default) — Stats appear in the system menu bar
- **Popover Mode** — Stats appear as a toolbar button in the app window
Toggle between modes in the app settings.
### Worktree Grouping
Worktree sessions are grouped under their parent module by default, so `ModuleA` shows its regular sessions plus AgentHub-owned worktree sessions. The Worktrees settings tab can switch to separate modules, where each AgentHub-owned worktree appears as its own module section.
AgentHub creates new worktrees as sibling directories beside the main repository, using the generated or manual directory name directly under the repository's parent directory. It no longer creates a repo-local `.worktrees` folder or adds `.worktrees/` to Git's exclude file.
AgentHub only treats worktrees it created, explicitly added, or focused through monitored sessions as owned. External Git worktrees discovered from the repository are ignored for session grouping, which keeps large local worktree setups from flooding the session list. The Worktrees settings inventory still lists all Git worktrees for tracked repositories: focused rows participate in AgentHub grouping, while external rows can be deleted without becoming focused.
### Provider Defaults
Provider defaults are applied only when AgentHub starts a new embedded CLI session. Resume flows keep the original session configuration and do not inject new model or approval flags.
These settings are persisted locally in AgentHub's SQLite metadata store.
#### Claude
AgentHub maps Claude defaults to the installed CLI flags:
- `Model` → `--model