Metadata-Version: 2.5
Name: jarvix-hub
Version: 0.1.0
Summary: Jarvix hub: agent state tracking server and client
Project-URL: Homepage, https://github.com/loctvl842/jarvix
Project-URL: Repository, https://github.com/loctvl842/jarvix
Project-URL: Issues, https://github.com/loctvl842/jarvix/issues
Author-email: loctvl842 <loclepnvx@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,cli,multiplexer,tmux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: jarvix-mux>=0.1.0
Description-Content-Type: text/markdown

# 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

| State | Meaning |
| --- | --- |
| `starting` | Pane is up, agent has not reported yet |
| `idle` | Waiting for input |
| `working` | Handling a prompt |
| `blocked` | Waiting on you, for example a permission prompt. Flagged as needing attention |
| `dead` | Session ended or the pane is gone |

## 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:

```sh
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

```sh
uv run pytest packages/hub/tests
```
