jarvix-cli 0.1.0__tar.gz

jarvix_cli-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_cli-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_cli-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: jarvix-cli
+Version: 0.1.0
+Summary: Jarvix command line interface
+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: click>=8.1
+Requires-Dist: jarvix-core>=0.1.0
+Requires-Dist: jarvix-hub>=0.1.0
+Requires-Dist: jarvix-mux>=0.1.0

jarvix_cli-0.1.0/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_cli-0.1.0/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_cli-0.1.0/src/jarvix/cli/__main__.py

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

jarvix_cli-0.1.0/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_cli-0.1.0/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))