Single Machine

This page explains how the node and discovery work on one machine, so you can choose how to run Argus.

Nodes

A node is the background process that discovers agent sessions, controls their tmux panes, and serves a local API (a unix socket) to the TUI. The TUI talks to the node, so you don't use the node directly.

A local node runs in one of two ways:

• Started by the TUI: if no node is running, argus offers to spawn one. The node continues after you quit the TUI, the next argus attaches to it, and argus stop stops it. With --gateway, argus spawns a node that connects to that gateway, and does not ask.

  argus          # open the TUI (can spawn a node if none is running)
  argus stop     # stop the node that the TUI started

• Persistent: argus start runs a node in the foreground. It keeps running whether or not a TUI is open, so the status is current when you open the TUI. Run it in its own tmux window, or as a systemd or launchd service.

  argus start    # run a persistent node

Discovery

Argus finds running agent sessions automatically, inside or outside tmux. No per-session setup is needed. Start a supported agent as usual and Argus discovers it:

cd ~/code/my-project
claude          # or agy, codex, opencode

For a Claude Code or Antigravity session, run the agent inside tmux to see its live screen and type into it. Outside tmux, the session still appears with its status and transcript. A Claude Code session outside tmux also takes prompts and permission answers if the Argus plugin is installed.

Codex and OpenCode sessions do not need tmux. To open a terminal for a Codex session, Argus starts a codex resume <id> viewer.

Don't use tmux? Let Argus wrap it

argus spawn starts an agent inside tmux and attaches you to it with tmux hidden, so it feels like running the agent directly:

cd ~/code/my-project
argus spawn claude          # or: argus spawn antigravity

You can also set a shell alias:

alias claude='argus spawn claude'