Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -274,7 +274,7 @@ Tracks child processes that have open ports. When a parent session dies but the
| Key | Action |
|-----|--------|
| `↑`/`↓` or `k`/`j` | Select session in list |
| `Enter` | Jump to session terminal (cmux / tmux / iTerm2) |
| `Enter` | Jump to session terminal (Herdr / cmux / tmux / iTerm2) |
| `x` | Kill selected session (SIGKILL) |
| `X` | Kill all orphan ports |
| `q` | Quit |
Expand Down Expand Up @@ -364,22 +364,27 @@ Each adapter returns a three-way `JumpAttempt`:
- `Failed(msg)` — this backend owns the process but the focus command errored;
stop and surface `"<backend>: <msg>"` in the status line.

Order (most specific first), mutually exclusive by controlling tty:
Order (most specific first):

1. **cmux** (`jump/cmux.rs`) — reads `CMUX_WORKSPACE_ID` (a UUID cmux exports
1. **Herdr** (`jump/herdr.rs`) — when abtop runs inside Herdr, validates the
selected agent PID against Herdr's pane process inventory and calls
`herdr agent focus`. The inherited pane ID is the fast path; `agent list`
recovers the current ID after a cross-workspace move. Only the same Herdr
session is searched.
2. **cmux** (`jump/cmux.rs`) — reads `CMUX_WORKSPACE_ID` (a UUID cmux exports
into every surface, inherited by the agent) from the process environment via
`ps eww`, then `cmux select-workspace --workspace <uuid>`.
2. **tmux** (`jump/tmux.rs`) — only when abtop itself runs inside tmux (`$TMUX`).
3. **tmux** (`jump/tmux.rs`) — only when abtop itself runs inside tmux (`$TMUX`).
Maps PID → pane via `tmux list-panes -a -F '#{pane_pid} #{session_name}:#{window_index}.#{pane_index}'`
+ process-tree descent, then `switch-client` / `select-window` / `select-pane`.
PID in no pane → `NotApplicable` (lets another backend try).
3. **iTerm2** (`jump/iterm2.rs`) — resolves the PID's controlling tty (`ps -o tty=`),
4. **iTerm2** (`jump/iterm2.rs`) — resolves the PID's controlling tty (`ps -o tty=`),
then AppleScript selects the session whose `tty` matches and brings its
window/app to the front. First call triggers a one-time macOS Automation
permission prompt; until granted, `osascript` exits non-zero → `Failed`.

Parsing/registry logic is unit-tested in `jump/mod.rs`; the thin `ps`/`osascript`/
`tmux` I/O wrappers are verified manually.
Parsing/registry logic is unit-tested in `jump/mod.rs` and each backend; the
thin CLI and platform I/O wrappers are also verified manually.

## Privacy

Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,10 @@ Mouse capture is off by default so terminal drag selection and copy keep working

### Terminal Jump

Press `Enter` to focus the terminal running the selected agent. abtop supports cmux, tmux, and iTerm2 on macOS.
Press `Enter` to focus the terminal running the selected agent. abtop supports
Herdr 0.7.0 or newer, cmux, tmux, and iTerm2 on macOS. When abtop runs inside
Herdr, it can jump to agents in any pane, tab, or workspace in the same Herdr
session; no additional setup is required.

```bash
tmux new -s work
Expand All @@ -73,6 +76,9 @@ tmux new -s work
# → Enter on a session in abtop jumps to its pane
```

The same flow works inside Herdr: run abtop in one pane, run agents elsewhere
in the same session, then press `Enter` on the selected abtop row.

## Supported Agents

| Feature | Claude Code | Codex CLI | OpenCode |
Expand Down
2 changes: 1 addition & 1 deletion src/app.rs
Original file line number Diff line number Diff line change
Expand Up @@ -791,7 +791,7 @@ impl App {
}

/// Jump to the terminal running the selected session's agent process.
/// Delegates to the terminal-jumper registry (cmux / tmux / iTerm2);
/// Delegates to the terminal-jumper registry (Herdr / cmux / tmux / iTerm2);
/// see [`crate::jump`]. No-op when nothing is selected or no backend
/// recognizes the process.
pub fn jump_to_session(&mut self) -> JumpOutcome {
Expand Down
Loading