agent-berth

Monitor coding agents and resume their sessions.

agent-berth runs a small background server that tracks the status of your AI coding agent sessions — Claude Code, Codex, Grok, OpenCode, and Pi — through hooks installed into each agent. When the server or the host restarts, it can resume the sessions you were working on, each in its own tmux window, grouped by working directory.

Features

• Live status tracking — see which sessions are working, waiting, idle, or done, across all supported agents.
• Session resume — restart sessions that were interrupted by a reboot or server restart, each in its own tmux window via the agent's native resume command (claude --resume, codex resume, …).
• Attach — fuzzy-find a running agent pane with fzf and jump straight to it in tmux.
• Persistent state — sessions survive server and host restarts (redb database on disk).
• Cross-platform — Linux, macOS, and Windows; IPC over Unix sockets or Windows named pipes.

Install

Prebuilt binaries for Windows, Linux, and macOS are attached to each GitHub Release. With cargo-binstall:

cargo binstall agent-berth

Or build from source (Rust 2024 edition toolchain):

cargo install agent-berth
# or from a checkout:
cargo install --path .

Quick start

# Install the background service and hooks for every detected agent
agent-berth setup

# Watch your agents
agent-berth list

# After a reboot, bring back sessions idle for less than 20 minutes
agent-berth resume

setup installs hooks only for agents that are installed (found on PATH or with an existing config directory), and registers the server as a user service: a systemd user unit on Linux, a Scheduled Task on Windows. Use agent-berth setup --no-service to install hooks only.

Resuming CLI sessions requires tmux (or psmux on Windows). Interactive selection uses fzf.

Commands

TUI

agent-berth tui (or bare agent-berth) opens an interactive dashboard. The left column lists sessions with the agent logo, status, and title; the right column shows session details, plus a live tmux pane preview when the selected session runs in tmux.

The details pane combines the Git branch and status in one row, for example main [!+↕]. It uses Starship-style symbols: red ! for conflicts, $ for stashes, ✘ for deletions, yellow » for renames, yellow ! for modifications, green + for staged changes, and ? for untracked files. Tracking status uses ↑ (ahead), ↓ (behind), ↕ (diverged), or green ≡ (up to date), relative to the local upstream tracking ref. Branches without an upstream omit the tracking symbol. Clean repositories without an upstream show only the branch name.

Group headers use 1h, 1d, 7d, and >7d for creation/activity sorting: up to one hour, over one hour through one day, over one day through seven days, and older than seven days. Other sorts group by agent name, status, or full working directory. Directory labels show the last two components with / separators, such as codebase/agent-berth; missing directories show -. Headers are skipped when moving between sessions.

Resume behavior

resume selects sessions that are still busy (working/waiting) with no live agent process, plus sessions that went idle without a graceful exit within the idle window (default 20m, override with --idle). Selected sessions are grouped by working directory; each directory gets a tmux session and each agent session gets a window running the provider's resume command. Pass a pattern to pick one session interactively with fzf, --here to only consider sessions in the current directory, and --dry-run to print the plan without starting anything. list --resumable shows exactly what resume would start.

How it works

The hooks installed by setup call agent-berth notify on agent events (session start, prompt submit, tool use, permission requests, stop, session end). The server folds these events into per-session status and persists them in a redb database, so state survives restarts. Sessions are keyed by provider and session ID, with the working directory and command line needed to resume.

State lives in $XDG_STATE_HOME/agent-berth (~/.local/state/agent-berth, or %LOCALAPPDATA%\agent-berth on Windows). The IPC endpoint is $XDG_RUNTIME_DIR/agent-berth.sock on Unix and the \\.\pipe\agent-berth named pipe on Windows.

Environment variables

Provider config locations honor CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME, and PI_CODING_AGENT_DIR.

Development

Tasks are defined in mise.toml and runnable with mise:

mise run            # cargo build
mise run test       # full test suite
mise pre-commit     # cargo fmt --check + typos

See tests/README.md for the integration test harness, including the real-tmux, mock-LLM, and live-client suites.

License

MPL-2.0