Jarvix Hub

A small background daemon that knows what every node in a mesh is doing. Agents report their own lifecycle to it, and it turns those reports into one state per node.

Node states

How it works

1. When a mesh starts, each agent is launched with hooks that forward its lifecycle events to the hub.
2. The hub listens on a local socket and updates the node's state on each event.
3. In the background it also checks the panes. If a pane vanishes, the node becomes dead. If a permission dialog disappears without any event (for example you denied it), the node goes back to idle.
4. State and recent events are kept on disk, so a restarted hub picks up where it left off.

Hooks never break the agent: if the hub is down, the event is dropped silently.

Using it

The hub is run for you by the CLI. Bring a mesh up, look at it, and take it down:

jarvix mesh up --node planner --node coder --cwd ~/my-project
jarvix mesh attach        # watch the nodes in tmux (detach with ctrl-b d)
jarvix status             # state of every node
jarvix logs coder -n 20   # recent events for one node
jarvix mesh logs -f       # follow the hub's own log
jarvix mesh down          # stop the hub and kill the panes

Use --mesh <name> on any command to run several meshes side by side. jarvix status --json gives machine-readable output.

Where things live

Per mesh, under ~/.local/state/jarvix/<mesh>/: the socket, database, pid file, and hub log. Set JARVIX_HOME to move the root.

Tests

uv run pytest packages/hub/tests