agent-overseer

agent-overseer runs a local web UI for coding agents like Codex and Claude. It launches the command in a PTY, streams output to your browser, and uses status heuristics plus notifications to tell when an agent is working vs waiting, with a dashboard to monitor multiple sessions.

Highlights

• Run any CLI command in a PTY and watch it in the browser.
• Dashboard to see all running agents and jump into a session.
• Status heuristics to detect when an agent is working or waiting for input.
• Notifications when agents need your input or approval.
• Alias expansion via ~/.config/agent-overseer/aliases.json.
• Local-first defaults (binds to 127.0.0.1).

Why I built this

I often run 5+ coding agents locally across multiple worktrees (and sometimes multiple projects), with more than one agent per worktree. I wanted a way to keep momentum while away from my computer: see what each agent is doing at a glance, send prompts to keep work moving, jump in to unblock or redirect quickly, and do it all from my phone without rehydrating context or burning extra tokens.

How this compares to other options for monitoring local-first agents:

• Codex and Claude web start brand new agents on a new branch. I wanted to monitor and guide the agents I already had running on my machine, with their local context intact. They also burn a lot of tokens because they have to spin up cloud containers and re-read the repo.
• Termius + Tailscale + agents in local tmux windows (often with workmux) was workable, but not great on a phone. Switching panes takes multiple taps, tmux's window selector isn't a good "all agents at a glance" view, and workmux's dashboard doesn't show Codex agents yet.

What agent-overseer does today

• Start a coding agent (for example Claude or Codex) locally and interact with it via a locally served "agent page." You keep the same session and context, but gain a phone-friendly control surface you can tunnel to.
• Show all agents started via agent-overseer in a mobile-optimized, responsive dashboard with status and recent output snippets, so you can spot stalls and jump in fast. Sessions are grouped by project and branch.
• Optional notifications (desktop browser today; mobile push notifications planned) so you can step away and only return when an agent is finished or needs input.

Power user tips

• Use worktrunk for fast, lightweight worktree management.
• Use Tailscale to make agent pages and the dashboard accessible on your phone. agent-overseer can integrate with Tailscale for a one-command setup.
• Run as many agents as you want across branches and worktrees; the dashboard visually groups them by branch for quick scanning on mobile.

Requirements

• Node.js 18+
• npm
• Platform build tools if node-pty falls back to compiling from source (Xcode Command Line Tools, build-essential, etc.)

Install

Homebrew (recommended)

brew tap troyshu/homebrew-agent-overseer
brew install agent-overseer

npm

npm install -g agent-overseer

The installed command is ago.

From source

make install

make install builds dist/agent-overseer.js and writes a wrapper to ~/.local/bin/ago.

Override the install dir if you want:

BIN_DIR="$HOME/bin" make install

Release automation (maintainers)

Releases are automated via GitHub Actions (release-please + publish).

Required secrets:

• HOMEBREW_TAP_REPO (e.g. owner/homebrew-agent-overseer)
• HOMEBREW_TAP_TOKEN (PAT with contents: read/write on the tap repo)

NPM publish uses trusted publishing (OIDC). Configure a trusted publisher in npm for this repo/workflow; no NPM_TOKEN is needed.

Cut a release by merging the release-please PR; the publish workflow builds, publishes to npm, and updates the Homebrew tap formula.

Quickstart

ago -- <command> [args...]

Examples:

ago -- /bin/bash
ago -- claude -q "summarize this repo"

The server prints the URL on startup, for example:

Agent Overseer: http://127.0.0.1:12345 (pid 1234)

Codex / Claude workflows

Examples for the CLIs:

ago -- codex --yolo
ago -- claude -q "scan this repo for TODOs"

Dashboard

Start a dashboard that lists all running sessions:

ago --dashboard

Optional Tailscale share (requires tailscale):

ago --dashboard --tailscale
ago --dashboard --tailscale=agent-dashboard

This integrates with Tailscale so you can get a shareable HTTPS URL quickly.

This uses tailscale serve on the current node and refuses to run if a serve config already exists. On shutdown it resets the serve config only if it still matches what it set; otherwise it leaves it untouched and warns. In Tailscale mode the dashboard always binds to 127.0.0.1 (the --host flag is ignored).

Manual Tailscale setup (no --tailscale integration):

ago --dashboard --host 127.0.0.1 --port 0
# note the printed port, then:
tailscale serve --bg --set-path /agent-dashboard http://127.0.0.1:<PORT>

Visit https://<your-tailnet-dns>/agent-dashboard.

Aliases

You can define command aliases in ~/.config/agent-overseer/aliases.json. A default config is created on first run (empty). Example:

{
  "aliases": {
    "codex": ["codex"]
  }
}

With this config, ago -- codex expands to codex.

Add arguments to the alias if you want defaults:

{
  "aliases": {
    "codex": ["codex", "--yolo"]
  }
}

Additional arguments are appended:

ago -- codex -q "fix the bug"
# expands to: codex --yolo -q "fix the bug"

To view your current config:

ago --config

State and logs

UI state and session logs are stored under ~/.config/agent-overseer/sessions/<project>-<hash>/<branch>/. Logs and stale state files are pruned after 7 days. Run ago --prune to trigger cleanup manually.

Flags

ago [flags] -- <command> [args...]
ago --dashboard [flags]
ago --prune

| Flag | Description | Default | | --- | --- | --- | | --host | Bind host for agent overseer or dashboard | 127.0.0.1 | | --port | Bind port (0 chooses a free port) | 0 | | --title | Override the agent overseer title | auto | | --cols | PTY columns | 120 | | --rows | PTY rows | 40 | | --buffer-kb | Scrollback size (KB) | 256 | | --debug-esc | Log ANSI escape sequences | false | | --dashboard | Start dashboard mode | false | | --tailscale | Serve dashboard via Tailscale | disabled | | --config | Print config path and aliases | false | | --prune | Prune old session logs/state | false |

Security

This UI exposes a live PTY. Anyone who can reach it can run commands as your user.

• Keep the default 127.0.0.1 unless you fully trust the network.
• Treat --host 0.0.0.0 and --dashboard --tailscale as remote shell access.
• Use Tailscale ACLs or a firewall if you share it.

PATH setup (optional)

If ~/.local/bin is not on your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

For bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Contributing

Feature proposals require maintainer approval before any PRs. See CONTRIBUTING.md for guidelines and the required proposal flow.

License

MIT