jarvix 0.1.0__tar.gz

jarvix-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check tag matches package versions
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          status=0
+          for f in pyproject.toml packages/*/pyproject.toml; do
+            version=$(python3 -c "import sys, tomllib; print(tomllib.load(open(sys.argv[1], 'rb'))['project']['version'])" "$f")
+            if [ "$version" != "$tag" ]; then
+              echo "::error file=$f::version $version does not match tag $GITHUB_REF_NAME"
+              status=1
+            fi
+          done
+          exit $status
+      - run: uv sync --all-packages
+      - run: uv run pytest
+      - run: uv build --all-packages
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v5
+      - run: uv publish --trusted-publishing always dist/*

jarvix-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

jarvix-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

jarvix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loctvl842
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jarvix-0.1.0/Makefile

@@ -0,0 +1,42 @@
+APP_NAME := `sed -n 's/^ *name.*=.*"\([^"]*\)".*/\1/p' pyproject.toml`
+APP_VERSION := `sed -n 's/^ *version.*=.*"\([^"]*\)".*/\1/p' pyproject.toml`
+
+# Makefile help
+
+.PHONY: header
+header:
+	@printf "\033[34mEnvironment\033[0m\n"
+	@printf "\033[34m---------------------------------------------------------------\033[0m\n"
+	@printf "\033[33mAPP_NAME: \033[0m"
+	@printf "\033[35m$(APP_NAME)\033[0m\n"
+	@printf "\033[33mAPP_VERSION: \033[0m"
+	@printf "\033[35m$(APP_VERSION)\033[0m\n"
+	@printf "\n"
+
+.PHONY: usage
+usage:
+	@printf "\033[034mUsage\033[0m\n"
+	@printf "\033[34m---------------------------------------------------------------\033[0m\n"
+	@printf "\033[37mmake [options] \033[0m\n\n"
+
+.PHONY: options
+options:
+	@printf "\033[34mOptions\033[0m\n"
+	@printf "\033[34m---------------------------------------------------------------\033[0m\n"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2}' | sort
+
+
+.PHONY: core
+core:  ## Run a command in packages/core/Makefile (Usage: make core <command>)
+	@$(MAKE) --no-print-directory -C packages/core $(filter-out $@, $(MAKECMDGOALS))
+
+.PHONY: mux
+mux:  ## Run a command in packages/mux/Makefile (Usage: make mux <command>)
+	@$(MAKE) --no-print-directory -C packages/mux $(filter-out $@, $(MAKECMDGOALS))
+
+.PHONY: test
+test:  ## Run tests (fast, offline)
+	uv run pytest
+
+%:
+	@:

jarvix-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: jarvix
+Version: 0.1.0
+Summary: Talk to your agent(s)
+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-core>=0.1.0
+Provides-Extra: all
+Requires-Dist: jarvix-cli>=0.1.0; extra == 'all'
+Requires-Dist: jarvix-hub>=0.1.0; extra == 'all'
+Requires-Dist: jarvix-mux>=0.1.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: jarvix-cli>=0.1.0; extra == 'cli'
+Provides-Extra: hub
+Requires-Dist: jarvix-hub>=0.1.0; extra == 'hub'
+Provides-Extra: mux
+Requires-Dist: jarvix-mux>=0.1.0; extra == 'mux'
+Description-Content-Type: text/markdown
+
+# Jarvix
+
+**Talk to your agent(s).**
+
+One coding agent is a great assistant. A dozen of them is a team, and a team needs a way to work together.
+
+Jarvix turns a crowd of terminal agents into one coordinated crew. Launch them together, see what each one is doing, and stop juggling tabs to work out who is busy, who is stuck, and who needs you.
+
+## Why Jarvix
+
+- **See everything at a glance.** Every agent reports what it is doing, so you always know who is working, who is idle, and who is waiting on you.
+- **Never miss a blocked agent.** When an agent needs your approval, it asks for your attention and you jump straight to it.
+- **Shape your team.** Chain agents, fan work out in parallel, and route it conditionally, all in a few readable lines.
+- **Stay in your terminal.** No new app to learn. Your agents live in plain tmux panes you can attach to and watch whenever you like.
+- **Safe by design.** Each team runs on its own private tmux server, so your own sessions are never touched.
+
+## Install
+
+```sh
+pip install "jarvix[cli]"
+```
+
+This installs the `jarvix` command. Requires Python 3.12+ and tmux.
+
+Other extras: `jarvix[hub]`, `jarvix[mux]`, and `jarvix[all]`.
+
+## Learn more
+
+- [Mux](packages/mux/README.md) - spawning and arranging agent panes
+- [Hub](packages/hub/README.md) - tracking what every agent is doing
+
+## Status
+
+Jarvix is in early development and moving fast.

jarvix-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Jarvix
+
+**Talk to your agent(s).**
+
+One coding agent is a great assistant. A dozen of them is a team, and a team needs a way to work together.
+
+Jarvix turns a crowd of terminal agents into one coordinated crew. Launch them together, see what each one is doing, and stop juggling tabs to work out who is busy, who is stuck, and who needs you.
+
+## Why Jarvix
+
+- **See everything at a glance.** Every agent reports what it is doing, so you always know who is working, who is idle, and who is waiting on you.
+- **Never miss a blocked agent.** When an agent needs your approval, it asks for your attention and you jump straight to it.
+- **Shape your team.** Chain agents, fan work out in parallel, and route it conditionally, all in a few readable lines.
+- **Stay in your terminal.** No new app to learn. Your agents live in plain tmux panes you can attach to and watch whenever you like.
+- **Safe by design.** Each team runs on its own private tmux server, so your own sessions are never touched.
+
+## Install
+
+```sh
+pip install "jarvix[cli]"
+```
+
+This installs the `jarvix` command. Requires Python 3.12+ and tmux.
+
+Other extras: `jarvix[hub]`, `jarvix[mux]`, and `jarvix[all]`.
+
+## Learn more
+
+- [Mux](packages/mux/README.md) - spawning and arranging agent panes
+- [Hub](packages/hub/README.md) - tracking what every agent is doing
+
+## Status
+
+Jarvix is in early development and moving fast.

jarvix-0.1.0/packages/cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loctvl842
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jarvix-0.1.0/packages/cli/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jarvix"]
+
+[project]
+name = "jarvix-cli"
+version = "0.1.0"
+description = "Jarvix command line interface"
+authors = [{ name = "loctvl842", email = "loclepnvx@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["ai", "agents", "tmux", "multiplexer", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "jarvix-core>=0.1.0",
+  "jarvix-hub>=0.1.0",
+  "jarvix-mux>=0.1.0",
+  "click>=8.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/loctvl842/jarvix"
+Repository = "https://github.com/loctvl842/jarvix"
+Issues = "https://github.com/loctvl842/jarvix/issues"
+
+[project.scripts]
+jarvix = "jarvix.cli:main"
+
+[tool.uv.sources]
+jarvix-core = { workspace = true }
+jarvix-hub = { workspace = true }
+jarvix-mux = { workspace = true }

jarvix-0.1.0/packages/cli/src/jarvix/cli/__init__.py

@@ -0,0 +1,86 @@
+import json
+import os
+import sys
+import time
+from datetime import datetime
+
+import click
+from jarvix.hub.client import send
+from jarvix.hub.paths import socket_path
+
+from .mesh import mesh, mesh_option
+
+
+@click.group()
+def main() -> None:
+    """Jarvix CLI."""
+
+
+main.add_command(mesh)
+
+
+@main.command(hidden=True, context_settings={"ignore_unknown_options": True})
+@click.argument("event")
+def hook(event: str) -> None:
+    """Forward a harness hook event (stdin JSON) to the hub. Never fails the harness."""
+    try:
+        node = os.environ.get("JARVIX_NODE")
+        sock = os.environ.get("JARVIX_SOCKET")
+        if not node or not sock:
+            return
+        try:
+            payload = json.loads(sys.stdin.read() or "{}")
+        except ValueError:
+            payload = {}
+        reply = send(
+            sock, {"op": "event", "node": node, "event": {"name": event, "ts": time.time(), "payload": payload}}
+        )
+        if reply and reply.get("output"):
+            click.echo(reply["output"])
+    except Exception:  # noqa: BLE001 - a broken hook must never break the harness
+        pass
+
+
+def _age(since: float) -> str:
+    secs = max(0, int(time.time() - since))
+    if secs < 60:
+        return f"{secs}s"
+    if secs < 3600:
+        return f"{secs // 60}m"
+    return f"{secs // 3600}h{secs % 3600 // 60:02d}m"
+
+
+@main.command()
+@mesh_option
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def status(mesh: str, as_json: bool) -> None:
+    """Show the state of every node."""
+    reply = send(socket_path(mesh), {"op": "nodes"})
+    if reply is None or not reply.get("ok"):
+        raise click.ClickException(f"hub for mesh {mesh!r} is not running")
+    nodes = reply["nodes"]
+    if as_json:
+        click.echo(json.dumps(nodes, indent=2))
+        return
+    width = max([len(n["name"]) for n in nodes] + [4])
+    click.echo(f"{'NODE':<{width}}  {'STATE':<8}  {'SINCE':<6}  {'ATTN':<4}  SUMMARY")
+    for n in nodes:
+        attn = "!" if n["attention"] else "-"
+        click.echo(f"{n['name']:<{width}}  {n['state']:<8}  {_age(n['state_since']):<6}  {attn:<4}  {n['summary']}")
+
+
+@main.command()
+@mesh_option
+@click.argument("node")
+@click.option("-n", default=10, show_default=True, help="Number of recent events.")
+def logs(mesh: str, node: str, n: int) -> None:
+    """Show recent events for a node."""
+    reply = send(socket_path(mesh), {"op": "status", "node": node, "n": n})
+    if reply is None:
+        raise click.ClickException(f"hub for mesh {mesh!r} is not running")
+    if not reply.get("ok"):
+        raise click.ClickException(reply["error"])
+    for e in reply["events"]:
+        stamp = datetime.fromtimestamp(e["ts"]).strftime("%H:%M:%S")
+        detail = e["payload"].get("tool_name") or e["payload"].get("prompt") or e["payload"].get("message") or ""
+        click.echo(f"{stamp}  {e['kind']:<18} {detail[:80]}")

jarvix-0.1.0/packages/cli/src/jarvix/cli/__main__.py

@@ -0,0 +1,4 @@
+from jarvix.cli import main
+
+if __name__ == "__main__":
+    main()

jarvix-0.1.0/packages/cli/src/jarvix/cli/launch.py

@@ -0,0 +1,67 @@
+import json
+import shlex
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from jarvix.hub.hooks import hook_settings
+from jarvix.hub.paths import runtime_dir
+from jarvix.hub.server import NodeSpec
+from jarvix.mux import LayoutStrategy, Multiplexer, PaneRef, SessionRef
+
+NODES_WINDOW = "nodes"
+
+
+def default_jarvix_bin() -> str:
+    """Command the hooks run. Uses this interpreter so it works without `jarvix` on PATH."""
+    return shlex.join([sys.executable, "-m", "jarvix.cli"])
+
+
+def session_name(mesh: str) -> str:
+    return f"jarvix-{mesh}"
+
+
+def tmux_socket(mesh: str) -> str:
+    """Private tmux server per mesh, so the user's own tmux is untouched."""
+    return f"jarvix-{mesh}"
+
+
+def write_settings(mesh: str, jarvix_bin: str) -> Path:
+    path = runtime_dir(mesh) / "claude-settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(hook_settings(jarvix_bin), indent=2))
+    return path
+
+
+def node_argv(spec: NodeSpec, settings: Path, *, model: str, claude_bin: str = "claude") -> list[str]:
+    if spec.harness != "claude":
+        raise ValueError(f"unsupported harness {spec.harness!r} for node {spec.name!r}")
+    # --model is required: a model pinned in the user's global settings can break turns (M0 gotcha).
+    return [claude_bin, "--model", model, "--settings", str(settings)]
+
+
+def launch_nodes(
+    mux: Multiplexer,
+    mesh: str,
+    specs: Sequence[NodeSpec],
+    sock_path: Path,
+    settings: Path,
+    *,
+    model: str,
+    claude_bin: str = "claude",
+) -> dict[str, PaneRef]:
+    """Spawn one pane per node in a fresh session and arrange them in a grid. The hub must already listen."""
+    session: SessionRef = mux.spawn_session(session_name(mesh))
+    panes: dict[str, PaneRef] = {}
+    for spec in specs:
+        env = {"JARVIX_NODE": spec.name, "JARVIX_SOCKET": str(sock_path), "JARVIX_MESH": mesh}
+        panes[spec.name] = mux.spawn_pane(
+            session,
+            node_argv(spec, settings, model=model, claude_bin=claude_bin),
+            env=env,
+            cwd=Path(spec.cwd),
+            tag=spec.name,
+            window=NODES_WINDOW,
+        )
+    mux.layout(session, LayoutStrategy.GRID, window=NODES_WINDOW)
+    return panes

jarvix-0.1.0/packages/cli/src/jarvix/cli/mesh.py

@@ -0,0 +1,205 @@
+import asyncio
+import contextlib
+import logging
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import time
+
+import click
+from jarvix.hub import (
+    Hub,
+    HubAlreadyRunning,
+    NodeSpec,
+    Store,
+    db_path,
+    encode_pane,
+    log_path,
+    pid_path,
+    send,
+    socket_path,
+)
+from jarvix.mux import SessionRef, TmuxMultiplexer
+from jarvix.mux.tmux import MuxError
+
+from .launch import (
+    default_jarvix_bin,
+    launch_nodes,
+    session_name,
+    tmux_socket,
+    write_settings,
+)
+
+mesh_option = click.option("--mesh", envvar="JARVIX_MESH", default="default", show_default=True, help="Mesh name.")
+
+STARTUP_TIMEOUT = 20.0
+STOP_TIMEOUT = 5.0
+
+
+@click.group()
+def mesh() -> None:
+    """Run a mesh of harness nodes in tmux panes."""
+
+
+def _hub_pid(mesh: str) -> int | None:
+    """Pid of the background hub, or None if there is no live one."""
+    try:
+        pid = int(pid_path(mesh).read_text())
+        os.kill(pid, 0)
+    except (OSError, ValueError):
+        return None
+    return pid
+
+
+def _tail(path: Path, n: int = 15) -> str:
+    try:
+        return "\n".join(path.read_text().splitlines()[-n:])
+    except OSError:
+        return ""
+
+
+def _print_hints(mesh: str, count: int) -> None:
+    click.echo(f"mesh {mesh!r} up with {count} node(s)")
+    click.echo(f"  jarvix mesh attach --mesh {mesh}    # see the nodes")
+    click.echo(f"  jarvix status --mesh {mesh}         # state of every node")
+    click.echo(f"  jarvix mesh logs --mesh {mesh} -f   # hub log")
+    click.echo(f"  jarvix mesh down --mesh {mesh}      # stop the hub and kill the panes")
+
+
+def _serve(mesh: str, specs: list[NodeSpec], model: str, claude_bin: str, clean_config: bool) -> None:
+    """Run the hub in this process and spawn the nodes once it listens. Returns when stopped."""
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s", datefmt="%H:%M:%S")
+    sock = socket_path(mesh)
+    sock.parent.mkdir(parents=True, exist_ok=True)
+    store = Store(db_path(mesh))
+    mux = TmuxMultiplexer(socket=tmux_socket(mesh), config_file="/dev/null" if clean_config else None)
+    server = Hub(sock, store, specs, mux=mux)
+    settings = write_settings(mesh, default_jarvix_bin())
+
+    def spawn() -> None:
+        # Hooks are fire-and-forget, so the hub must be listening before the first SessionStart.
+        try:
+            panes = launch_nodes(mux, mesh, specs, sock, settings, model=model, claude_bin=claude_bin)
+        except MuxError as e:
+            raise click.ClickException(f"{e}\nIs the mesh already up? Try: jarvix mesh down --mesh {mesh}") from e
+        for name, pane in panes.items():
+            store.set_pane(name, encode_pane(pane))
+        logging.info("spawned %d node(s): %s", len(panes), ", ".join(panes))
+
+    async def run() -> None:
+        loop = asyncio.get_running_loop()
+        task = asyncio.current_task()
+        assert task is not None
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, task.cancel)
+        with contextlib.suppress(asyncio.CancelledError):
+            await server.serve_forever(on_ready=spawn)
+
+    try:
+        pid_path(mesh).write_text(str(os.getpid()))
+        asyncio.run(run())
+    except HubAlreadyRunning as e:
+        raise click.ClickException(str(e)) from e
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            pid_path(mesh).unlink()
+        store.close()
+        logging.info("hub stopped")
+
+
+def _wait_until_up(mesh: str, names: list[str], child: subprocess.Popen) -> None:
+    """Block until the hub answers and every node has a pane, or fail with the hub log."""
+    deadline = time.monotonic() + STARTUP_TIMEOUT
+    while time.monotonic() < deadline:
+        if child.poll() is not None:
+            raise click.ClickException(f"hub exited during startup:\n{_tail(log_path(mesh))}")
+        reply = send(socket_path(mesh), {"op": "nodes"}, timeout=0.5)
+        if reply and reply["ok"]:
+            panes = {n["name"]: n["pane_ref"] for n in reply["nodes"]}
+            if all(panes.get(name) for name in names):
+                return
+        time.sleep(0.1)
+    raise click.ClickException(f"hub did not come up in {STARTUP_TIMEOUT:.0f}s:\n{_tail(log_path(mesh))}")
+
+
+@mesh.command("up")
+@mesh_option
+@click.option("--node", "nodes", multiple=True, required=True, help="Node name. Repeatable.")
+@click.option("--cwd", default=".", show_default=True, help="Working directory of every node.")
+@click.option("--model", default="sonnet", show_default=True, help="Model passed to claude.")
+@click.option("--claude-bin", default="claude", show_default=True, help="The claude executable.")
+@click.option("--clean-config", is_flag=True, help="Ignore ~/.tmux.conf for the mesh's tmux server.")
+@click.option("--foreground", is_flag=True, help="Run the hub in this terminal instead of the background.")
+def mesh_up(
+    mesh: str, nodes: tuple[str, ...], cwd: str, model: str, claude_bin: str, clean_config: bool, foreground: bool
+) -> None:
+    """Spawn one Claude Code pane per node and run the hub (in the background by default)."""
+    # TODO: temporary entry point. The real one is `jarvix up <graph>`: compile() the graph into a launch plan
+    # (per-node harness, cwd, prompt, model, plus edges and Jarvis) and feed it to launch_nodes, instead of --node flags.
+    if send(socket_path(mesh), {"op": "ping"}, timeout=0.5):
+        raise click.ClickException(f"mesh {mesh!r} is already up. Stop it first: jarvix mesh down --mesh {mesh}")
+    specs = [NodeSpec(name=n, cwd=os.path.abspath(cwd)) for n in nodes]
+    if foreground:
+        if sys.stdout.isatty():  # the background child inherits a log file, where this banner would be noise
+            click.echo(f"hub for mesh {mesh!r} running in this terminal. Ctrl-C stops it; nodes keep running.")
+        _serve(mesh, specs, model, claude_bin, clean_config)
+        return
+
+    log = log_path(mesh)
+    log.parent.mkdir(parents=True, exist_ok=True)
+    argv = [sys.executable, "-m", "jarvix.cli", "mesh", "up", "--foreground", "--mesh", mesh, "--cwd", cwd]
+    argv += ["--model", model, "--claude-bin", claude_bin]
+    argv += ["--clean-config"] if clean_config else []
+    for n in nodes:
+        argv += ["--node", n]
+    with log.open("ab") as out:
+        # New session: the hub must outlive this terminal.
+        child = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=out, stderr=out, start_new_session=True)
+    _wait_until_up(mesh, list(nodes), child)
+    _print_hints(mesh, len(nodes))
+
+
+@mesh.command("down")
+@mesh_option
+def mesh_down(mesh: str) -> None:
+    """Stop the hub and kill the mesh's tmux session and all its panes."""
+    stopped = False
+    pid = _hub_pid(mesh)
+    if pid is not None:
+        os.kill(pid, signal.SIGTERM)
+        deadline = time.monotonic() + STOP_TIMEOUT
+        while _hub_pid(mesh) is not None and time.monotonic() < deadline:
+            time.sleep(0.1)
+        stopped = True
+    try:
+        TmuxMultiplexer(socket=tmux_socket(mesh)).kill_session(SessionRef(session_name(mesh)))
+        stopped = True
+    except MuxError:
+        pass
+    if not stopped:
+        raise click.ClickException(f"no running mesh {mesh!r}")
+    click.echo(f"mesh {mesh!r} down")
+
+
+@mesh.command("attach")
+@mesh_option
+def mesh_attach(mesh: str) -> None:
+    """Attach this terminal to the mesh's tmux session (detach with ctrl-b d)."""
+    sock, session = tmux_socket(mesh), session_name(mesh)
+    os.execvp("tmux", ["tmux", "-L", sock, "attach", "-t", f"={session}"])
+
+
+@mesh.command("logs")
+@mesh_option
+@click.option("-n", default=50, show_default=True, help="Number of lines.")
+@click.option("-f", "follow", is_flag=True, help="Follow new lines.")
+def mesh_logs(mesh: str, n: int, follow: bool) -> None:
+    """Show the hub's log (state transitions, startup errors)."""
+    path = log_path(mesh)
+    if not path.exists():
+        raise click.ClickException(f"no hub log for mesh {mesh!r}")
+    if follow:
+        os.execvp("tail", ["tail", "-n", str(n), "-f", str(path)])
+    click.echo(_tail(path, n))