When Settings → Agents → Show Agent Activity is on, ApexDock surfaces a live tile per agent session in the bar's agent zone. Each tile reflects the session's current phase (thinking / tool running / idle / errored / approval-pending) and exposes a hover popover with transcript preview, pending tools, and approval buttons.
Supported providers
| Provider | Detection mode | Notes |
|---|---|---|
| Claude Code | JSONL watcher and/or Hook API | Reads ~/.claude/projects/**/*.jsonl. Hook mode is recommended once installed (more reliable, supports approval). |
| Codex | JSONL watcher and/or Hook API | Reads ~/.codex/sessions/. |
| Custom providers | Hook API | Any free-form provider string. Add wordmark, color, group, and icon fields to style the tile. |
| Pi | Reserved | Pi has no on-disk transcript stream yet. Toggle disabled. |
Per-provider source mode (Auto / JSONL only / Hooks only) is configured in Settings → Agents → Hook API.
Tile states
| State | Visual |
|---|---|
idle | Normal tile, no live pulse |
thinking | Slow status pulse |
toolRunning | Fast status pulse + active tool name chip |
pendingApproval | Tile shakes once, orange status, "Approve / Decline" buttons in popover |
errored | Red status, sticky until next user message |
completed | 3-second green flash, then idle |
Hover popover
Shows:
- Session name (often the cwd basename)
- Provider chip (Claude / Codex / custom)
- Current phase + tool, if any
- Pending tools list (active calls awaiting
tool.end) - Recent transcript rows (user message, assistant message, tool start/end)
- Open-in-app button (jumps to the source app)
- Open Here button (arrow icon) — focuses the terminal, app, or tmux pane the session is running in
Toggle transcript previews off in Settings → Agents → Show Transcript Previews if you want a quieter popover.
Open Here
Each session tile and related-session row in the popover exposes an Open Here button. ApexDock picks the best target it can find for the session's provider:
| Route | Used when |
|---|---|
| Custom URL | The provider has a custom-opener template configured under Settings → Agents → Claude Code Open Here / Codex Open Here. The template is expanded with session metadata and opened via NSWorkspace. |
| App deep link | The session reports a deepLink. Codex sessions also fall back to codex://threads/<threadId>. |
| App focus | The session reports an appBundleId (without a deep link). |
| tmux pane | The session reports a tmux pane (tmuxPane, or a unique (session, window, tty) triple). ApexDock runs tmux select-pane and activates the host terminal. |
| Terminal focus | The session reports a terminal bundle ID, PID, or TTY. Falls back to Ghostty → iTerm → Apple Terminal in that order. |
Custom templates accept these placeholders, percent-encoded into the URL: {threadId}, {sessionId}, {cwd}, {provider}, {originator}, {clientName}. Example: myharness://threads/{threadId}. Hide the button per-provider with the Show Open Here button toggle in the same settings section.
Consolidated agent icons
When Settings → Agents → Consolidate Grouped Icons is on, grouped sessions (subagents and same-repo sessions) collapse to a single orchestrator tile in the bar. The grouped child sessions still appear as related-session rows in the parent's popover, so nothing becomes unreachable. Default off.
Approval handshake
When an agent asks for permission (Claude Code's PermissionRequest, or any equivalent gate), the tile turns orange and shakes. Click Approve or Decline in the popover and the decision rounds back to the agent over the same connection.
The agent waits until you decide. Approval requires the live hook connection, not the file-drop fallback. Install Claude hooks from Settings → Agents to enable the bundled apexdock claude-hook bridge.
Notifications
Settings → Agents → Notify When Approval Pending posts a system notification when a session needs your input. Useful when the bar is hidden or you're in another Space.
Idle timeout
Settings → Agents → Idle Timeout (1–60 minutes) controls when an inactive session is marked stale and faded from the tile row. Doesn't kill the underlying agent — just removes the visible tile until activity resumes.
Watched paths
Settings → Agents → Watched Paths shows which directories ApexDock is reading for built-in JSONL providers. The defaults cover ~/.claude / ~/.codex; add custom roots if those agents store sessions elsewhere (e.g. a worktree under your git repo).
Each custom root expects the same shape as the canonical (projects/ or sessions/ subfolder containing JSONL files).
Hook API
The full hook protocol — JSON shapes, event types, transport semantics, custom-provider styling, and the bundled apexdock-event / apexdock claude-hook helpers — lives at API → Hook API.
For Claude Code, the one-time install is: enable Hook API in Settings, click Install Claude Hooks, set Claude Code source to Hooks only.