loopx 0.4.8__py3-none-any.whl

loopx/claude_goal_mode/hooks/goal_policy.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""PreToolUse policy gate for goal-mode — OPTIONAL deterministic hardening.
+
+In the native-`/loop` design, Claude Code's `/loop` is the runtime and loopx's
+MCP `should_run` is the per-tick gate. This hook is NOT installed by default —
+it is opt-in (`install.py --harden` / `connect.py --harden`), project-scoped, and
+adds a per-TOOL-CALL gate on top of the loop:
+
+- should_run gate (fail-closed)  -> may the agent spend this turn right now?
+- Edit/Write -> write_scope        -> deny file edits outside the goal's scope
+- Bash -> destructive denylist     -> deny obviously dangerous commands
+
+It only acts in a project where loopx is armed (a `.claude/loop.md` exists).
+
+Limitation (by design): Bash is gated only by a denylist, so a determined shell
+command can still write outside write_scope or reach the network. For STRONG
+isolation (untrusted code / unattended high-stakes), run Claude Code inside a dev
+container or VM, which contains the whole process at the environment level.
+
+Behavior (only while goal-mode is ARMED for the event's project):
+- no goal here / goal-mode off            -> {} (no-op; normal permission flow)
+- read-only/safe tools                    -> allow
+- should_run == false (quota/gate closed) -> deny
+- should_run probe unavailable (error)    -> deny for non-read-only tools (FAIL-CLOSED)
+- should_run == true:
+    * Edit/Write outside write_scope      -> deny
+    * Edit/Write within write_scope       -> allow
+    * destructive Bash                    -> deny
+    * Bash / other                        -> allow
+
+Fail-closed: if the deterministic ``should_run`` probe cannot be reached, a
+non-read-only tool is denied rather than allowed, so a flaky/broken control
+plane pauses delivery instead of running ungated. Read-only tools stay allowed.
+
+Identity-aware: when the active goal registered an agent (loopx
+``coordination.registered_agents``), the context carries ``agent_id`` and this
+hook forwards it as ``--agent-id`` to ``loopx quota should-run``. Without it
+loopx returns ``automation_prompt_upgrade_required`` and should_run=false — the
+Claude Code analogue of Codex's identity-scoped heartbeat prompt.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Goal context is resolved PER PROJECT from the event's cwd via the registry, and
+# "armed" = the project's .claude/loop.md exists (see goal_state.py). The registry
+# is the single source of truth; there is no separate active-state file.
+from goal_state import active_context
+
+# Read-only tools are always allowed under goal-mode. Edit/Write are scoped to
+# write_scope; Bash is gated by a destructive-command denylist. (No OS sandbox in
+# this design — the hook is the whole gate; see the module docstring.)
+# NOTE: `Task` is deliberately NOT here. It can launch a subagent that performs
+# writes, so allowing it unconditionally would bypass the gate when
+# should_run=false. It must go through the gate: denied when should_run=false,
+# otherwise deferred to Claude Code's normal permission flow (unknown tool).
+READONLY_TOOLS = {"Read", "Glob", "Grep", "NotebookRead", "TodoWrite", "WebFetch", "WebSearch", "ToolSearch"}
+WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+DESTRUCTIVE = (
+    "rm -rf", "rm -fr", "mkfs", "dd if=", ":(){", "shutdown", "reboot",
+    "git push --force", "git reset --hard", "> /dev/sd", "format ",
+)
+CLAUDE_RUNTIME_PROFILE_ARGS = ["--runtime-profile", "claude_code"]
+CLAUDE_LEGACY_SCHEDULER_ARGS = [
+    "--host-surface", "claude_code",
+    "--scheduler-owner", "agent_cli_loop",
+    "--execution-mode", "interactive",
+]
+
+
+def within(path: str, root: str) -> bool:
+    """True if `path` resolves to `root` or a descendant of it."""
+    try:
+        p = Path(path).resolve()
+        r = Path(root).resolve()
+        return r == p or r in p.parents
+    except Exception:
+        return False
+
+
+def _gh_prefix():
+    _exe = shutil.which("loopx")
+    return [_exe] if _exe else [__import__("sys").executable, "-m", "loopx.cli"]
+
+
+def emit(decision=None, reason=""):
+    if decision is None:
+        sys.stdout.write("{}")  # no-op: defer to normal permission flow
+        return
+    sys.stdout.write(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": reason,
+        }
+    }))
+
+
+def _runtime_profile_flag_is_unsupported(out: subprocess.CompletedProcess) -> bool:
+    diagnostic = str(out.stderr or "").lower()
+    return (
+        out.returncode == 2
+        and "--runtime-profile" in diagnostic
+        and (
+            "unrecognized arguments" in diagnostic
+            or "invalid choice" in diagnostic
+        )
+    )
+
+
+def should_run(registry, goal_id, agent_id=None) -> bool | None:
+    """Return True/False from loopx quota should-run, or None if unknown."""
+    if not goal_id:
+        return None
+    cmd = list(_gh_prefix())
+    if registry:
+        cmd += ["--registry", registry]
+    cmd += ["--format", "json", "quota", "should-run", "--goal-id", goal_id]
+    if agent_id:
+        cmd += ["--agent-id", agent_id]
+    try:
+        out = subprocess.run(
+            [*cmd, *CLAUDE_RUNTIME_PROFILE_ARGS],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if _runtime_profile_flag_is_unsupported(out):
+            out = subprocess.run(
+                [*cmd, *CLAUDE_LEGACY_SCHEDULER_ARGS],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+    except Exception:
+        return None  # caller fails CLOSED on None for non-read-only tools
+    try:
+        data = json.loads(out.stdout or "{}")
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return None
+    should_run_value = data.get("should_run")
+    return should_run_value if isinstance(should_run_value, bool) else None
+
+
+def decide(ev: dict) -> dict:
+    """Pure policy: given a PreToolUse event, return the hookSpecificOutput dict
+    (or {} for no-op). Reused by the CLI hook AND the Agent SDK in-process hook.
+
+    The hook is the whole gate (no OS sandbox): should_run (fail-closed) +
+    Edit/Write write_scope + a destructive-Bash denylist."""
+    # Claude Code feeds the session's working directory on the event; resolve the
+    # goal from THAT project's registry, and gate only while goal-mode is armed
+    # (the project's .claude/loop.md exists). Unrelated/unarmed projects -> no-op.
+    cwd = ev.get("cwd") or (ev.get("workspace") or {}).get("current_dir")
+    ctx = active_context(cwd)
+    if not ctx:
+        return {}  # no goal here, or goal-mode off -> defer to normal flow
+
+    goal_id = ctx.get("goal_id")
+    registry = ctx.get("registry")
+    agent_id = ctx.get("agent_id")
+    scope = ctx.get("write_scope") or []
+    tool = ev.get("tool_name", "")
+    ti = ev.get("tool_input", {}) or {}
+
+    def d(decision, reason):
+        return {"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": reason}}
+
+    if tool in READONLY_TOOLS:
+        return d("allow", "read-only/safe tool under goal-mode")
+
+    sr = should_run(registry, goal_id, agent_id)  # True / False / None
+    if sr is False:
+        return d("deny", f"goal '{goal_id}' should_run=false (quota/gate closed)")
+    if sr is None:
+        # deterministic should_run probe unavailable -> fail closed (non-read-only tool)
+        return d("deny", "loopx should_run probe unavailable — failing closed under goal-mode")
+
+    # should_run == True. Scope the Edit/Write file tools to write_scope, and
+    # gate Bash with the destructive denylist (the hook is the whole gate).
+    if tool in WRITE_TOOLS:
+        fp = ti.get("file_path") or ti.get("notebook_path") or ""
+        if scope and not any(within(fp, s) for s in scope):
+            return d("deny", f"'{fp}' outside goal write_scope {scope}")
+        return d("allow", "write within goal scope")
+    if tool == "Bash":
+        low = (ti.get("command") or "").lower()
+        if any(tok in low for tok in DESTRUCTIVE):
+            return d("deny", "destructive command blocked by goal policy")
+        return d("allow", "bash permitted under goal policy")
+    return {}  # unknown tool: defer to normal flow
+
+
+def main():
+    raw = sys.stdin.read() or "{}"
+    try:
+        ev = json.loads(raw)
+    except Exception:
+        ev = {}
+    result = decide(ev)
+    sys.stdout.write(json.dumps(result) if result else "{}")
+
+
+if __name__ == "__main__":
+    main()

loopx/claude_goal_mode/hooks/goal_state.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Goal-mode context resolution — registry-driven, mirroring the Codex model.
+
+LoopX's registry (``.loopx/registry.json``) is the single source of truth for the
+project's goal (goal_id / agent / scope), exactly as on Codex. We resolve it by
+walking up from cwd to the nearest ``.loopx/`` (or legacy ``.goal-harness/``)
+registry — so two sessions in different projects are independent, and two
+sessions in the SAME project share the one goal.
+
+"Goal-mode ON / armed" for a project = a ``.claude/loop.md`` exists (written by
+``/loopx <task>``). That file is the per-iteration protocol that Claude Code's
+native ``/loop`` runs; its presence means loopx is driving this project. The
+OPTIONAL PreToolUse hook + statusline gate on this, so they only act where loopx
+is actually active. ``LOOPX_GOAL_FORCE=1`` forces armed=true for tests.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+REGISTRY_DIRS = (".loopx", ".goal-harness")  # prefer loopx; fall back to legacy
+
+_ARMED_RE = re.compile(r"<!--\s*loopx:armed\s*(\{.*?\})\s*-->")
+
+
+def find_registry(cwd) -> Path | None:
+    """Nearest ancestor of cwd (inclusive) holding a registry.json, else None."""
+    try:
+        cur = Path(cwd).resolve()
+    except Exception:
+        return None
+    for d in [cur, *cur.parents]:
+        for sub in REGISTRY_DIRS:
+            cand = d / sub / "registry.json"
+            if cand.exists():
+                return cand
+    return None
+
+
+def project_root_for(cwd) -> Path | None:
+    reg = find_registry(cwd)
+    return reg.parent.parent if reg else None
+
+
+def _agent_of(goal: dict):
+    coord = goal.get("coordination") or {}
+    for entry in coord.get("registered_agents") or []:
+        if isinstance(entry, dict):
+            val = entry.get("id") or entry.get("agent_id") or entry.get("name")
+            if val:
+                return str(val)
+        elif entry:
+            return str(entry)
+    return None
+
+
+def loop_md_path(project_root) -> Path:
+    return Path(project_root) / ".claude" / "loop.md"
+
+
+def read_armed_goal(project_root) -> dict | None:
+    """The goal_id/agent_id that `/loopx` armed for THIS project, parsed from the
+    `loopx:armed` marker it writes at the top of `.claude/loop.md`. None if the
+    project isn't armed or the marker is absent/unparseable.
+
+    This is what lets goal_context resolve the *armed* goal rather than guessing
+    by registry order, so a multi-goal repo gates/claims/completes the goal the
+    user actually set up."""
+    if not project_root:
+        return None
+    try:
+        text = loop_md_path(project_root).read_text(encoding="utf-8")
+    except Exception:
+        return None
+    m = _ARMED_RE.search(text)
+    if not m:
+        return None
+    try:
+        d = json.loads(m.group(1))
+    except Exception:
+        return None
+    return d if isinstance(d, dict) and d.get("goal_id") else None
+
+
+def goal_context(cwd) -> dict | None:
+    """The current project's goal, read live from the registry. None if no goal.
+
+    Returns goal_id, registry path, agent_id, write_scope (the goal's repo), and
+    project_root — everything the hooks / MCP / statusline need. When the project
+    is armed (`.claude/loop.md` carries a `loopx:armed` marker), the marker's goal
+    is authoritative; otherwise we fall back to the first registry goal."""
+    reg = find_registry(cwd)
+    if not reg:
+        return None
+    try:
+        data = json.loads(reg.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    goals = data.get("goals") or []
+    if not goals:
+        return None
+    root = reg.parent.parent
+    # Prefer the goal /loopx armed for this project; only fall back to registry
+    # order when there is no armed marker or it points at a goal not in the registry.
+    armed = read_armed_goal(root)
+    chosen = None
+    armed_agent = None
+    if armed:
+        chosen = next((g for g in goals if g.get("id") == armed.get("goal_id")), None)
+        if chosen is not None:
+            armed_agent = armed.get("agent_id")
+    if chosen is None:
+        chosen = goals[0]
+    repo = chosen.get("repo")
+    scope = [str(repo).replace("\\", "/")] if repo else [str(root).replace("\\", "/")]
+    return {
+        "goal_id": chosen.get("id"),
+        "registry": str(reg).replace("\\", "/"),
+        "agent_id": armed_agent or _agent_of(chosen),
+        "write_scope": scope,
+        "project_root": str(root).replace("\\", "/"),
+    }
+
+
+def is_armed(project_root) -> bool:
+    """Armed = the project has a `.claude/loop.md` (loopx is driving), or forced."""
+    if os.environ.get("LOOPX_GOAL_FORCE") == "1":
+        return True
+    return bool(project_root) and loop_md_path(project_root).exists()
+
+
+def active_context(cwd) -> dict | None:
+    """goal_context for cwd, but only when goal-mode is armed; else None."""
+    ctx = goal_context(cwd)
+    if not ctx or not is_armed(ctx.get("project_root")):
+        return None
+    return ctx

loopx/claude_goal_mode/mcp/loopx_mcp.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Minimal MCP server exposing loopx state to the agent.
+
+Tools: list_todos, claim_task, complete_task, should_run.
+Each shells out to the loopx CLI (deterministic control plane).
+
+Requires: pip install mcp
+Config (registry/goal/agent) is resolved PER PROJECT from this process's cwd via
+the `.loopx/registry.json` (see goal_state.py): each Claude Code session launches
+its own stdio MCP subprocess inheriting the session's working directory, so the
+goal scoping is per-project — no global state shared across sessions.
+
+These tools are the loopx control-plane protocol that native `/loop` drives each
+iteration (via `.claude/loop.md`): should_run -> claim_task -> bounded work ->
+verify -> complete_task (which also spends one quota slot after writeback).
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except Exception as e:  # pragma: no cover
+    raise SystemExit("MCP SDK not installed. Run: pip install mcp\n" + str(e))
+
+# share the registry-driven resolver with the hooks (sibling hooks/ dir)
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "hooks"))
+from goal_state import goal_context
+
+mcp = FastMCP("loopx")
+CLAUDE_RUNTIME_PROFILE_ARGS = ["--runtime-profile", "claude_code"]
+CLAUDE_LEGACY_SCHEDULER_ARGS = [
+    "--host-surface", "claude_code",
+    "--scheduler-owner", "agent_cli_loop",
+    "--execution-mode", "interactive",
+]
+def _gh_prefix():
+    _exe = shutil.which("loopx")
+    return [_exe] if _exe else [__import__("sys").executable, "-m", "loopx.cli"]
+
+def _state() -> dict:
+    # registry-derived context for THIS project (cwd) — the control-plane tools
+    # work whenever a goal exists, independent of the optional hook/loop.md.
+    return goal_context(Path.cwd()) or {}
+
+
+def _ctx():
+    st = _state()
+    return st.get("goal_id"), st.get("registry")
+
+
+def _agent_id():
+    return _state().get("agent_id")
+
+
+def _runtime_profile_flag_is_unsupported(out: subprocess.CompletedProcess) -> bool:
+    diagnostic = str(out.stderr or "").lower()
+    return (
+        out.returncode == 2
+        and "--runtime-profile" in diagnostic
+        and (
+            "unrecognized arguments" in diagnostic
+            or "invalid choice" in diagnostic
+        )
+    )
+
+
+def _gh(args: list[str], *, legacy_args: list[str] | None = None) -> str:
+    goal_id, registry = _ctx()
+    cmd = list(_gh_prefix())
+    if registry:
+        cmd += ["--registry", registry]
+    out = subprocess.run([*cmd, *args], capture_output=True, text=True, timeout=30)
+    if (
+        legacy_args is not None
+        and _runtime_profile_flag_is_unsupported(out)
+    ):
+        out = subprocess.run(
+            [*cmd, *legacy_args], capture_output=True, text=True, timeout=30
+        )
+    return (out.stdout or "") + (("\n" + out.stderr) if out.returncode else "")
+
+
+def _should_run_args(goal_id: str, agent_id: str | None) -> tuple[list[str], list[str]]:
+    common = ["--format", "json", "quota", "should-run", "--goal-id", goal_id]
+    if agent_id:
+        common += ["--agent-id", agent_id]
+    return (
+        [*common, *CLAUDE_RUNTIME_PROFILE_ARGS],
+        [*common, *CLAUDE_LEGACY_SCHEDULER_ARGS],
+    )
+
+
+def _no_goal_msg() -> str:
+    return json.dumps({"error": "goal-mode is not active in this project; run /loopx <task> first"})
+
+
+@mcp.tool()
+def should_run() -> str:
+    """Whether the active goal should run now (quota/gate)."""
+    gid, _ = _ctx()
+    if not gid:
+        return _no_goal_msg()
+    args, legacy_args = _should_run_args(gid, _agent_id())
+    return _gh(args, legacy_args=legacy_args)
+
+
+@mcp.tool()
+def list_todos() -> str:
+    """List the active goal's open agent todos (with todo_id + claimed_by)."""
+    gid, _ = _ctx()
+    if not gid:
+        return _no_goal_msg()
+    args, legacy_args = _should_run_args(gid, _agent_id())
+    return _gh(args, legacy_args=legacy_args)
+
+
+@mcp.tool()
+def claim_task(todo_id: str, agent_id: str) -> str:
+    """Soft-claim a todo for an agent."""
+    gid, _ = _ctx()
+    return _gh(["todo", "claim", "--goal-id", gid, "--todo-id", todo_id, "--claimed-by", agent_id])
+
+
+@mcp.tool()
+def complete_task(
+    todo_id: str,
+    agent_id: str,
+    evidence: str,
+    next_agent_todo: str = "",
+    task_lease_idempotency_key: str = "",
+) -> str:
+    """Complete a todo (with evidence), then spend one quota slot.
+
+    Mirrors the Codex heartbeat contract: spend exactly once AFTER validated
+    writeback. The slot is accounted only when the completion reports ok, with
+    source=heartbeat so it lines up with Codex spend accounting."""
+    gid, _ = _ctx()
+    args = ["todo", "complete", "--goal-id", gid, "--todo-id", todo_id,
+            "--claimed-by", agent_id, "--evidence", evidence]
+    if task_lease_idempotency_key:
+        args += ["--task-lease-idempotency-key", task_lease_idempotency_key]
+    if next_agent_todo:
+        # Don't hard-code a next claimer. With --next-agent-todo and no
+        # --next-claimed-by, LoopX assigns the new todo using its own completion
+        # semantics — to the completing agent for same-agent non-delivery, or to
+        # an explicitly claimed peer for an independent handoff.
+        # Hard-coding an unregistered id
+        # like `cc-controller` would fail registration.
+        args += ["--next-agent-todo", next_agent_todo]
+    out = _gh(args)
+    # spend-slot only on a validated completion (ok), matching "spend after writeback"
+    if "ok: `True`" in out or "ok=True" in out or '"ok": true' in out.lower():
+        spend = ["quota", "spend-slot", "--goal-id", gid, "--slots", "1",
+                 "--source", "heartbeat", "--execute"]
+        if agent_id:
+            spend += ["--agent-id", agent_id]
+        out += "\n--- spend-slot ---\n" + _gh(spend)
+    return out
+
+
+if __name__ == "__main__":
+    mcp.run()

loopx/claude_goal_mode/scripts/connect.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Connect a project to loopx for Claude Code (PROJECT-scoped).
+
+Thin wrapper: (1) `loopx connect` the repo, (2) mark `agent_backends += claude`
+in the project registry, (3) install the Claude adapter at PROJECT scope (the
+loopx MCP + the `/loopx` command into this project's `.claude/`) by delegating to
+install.py. No global config, no OS sandbox. The run loop is native `/loop`.
+
+  python connect.py --project DIR --goal-id G [--objective "…"] [--harden]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _gh_prefix():
+    exe = shutil.which("loopx")
+    return [exe] if exe else [sys.executable, "-m", "loopx.cli"]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    ap.add_argument("--goal-id", required=True)
+    ap.add_argument("--objective", default=None)
+    ap.add_argument("--registry", default=None)
+    ap.add_argument("--harden", action="store_true",
+                    help="also install the optional PreToolUse should_run gate + statusline (project scope)")
+    ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args()
+    proj = Path(a.project).resolve()
+    dry = a.dry_run
+
+    # 1. connect the repo to loopx (optional, when an objective is given)
+    if a.objective:
+        cmd = list(_gh_prefix()) + (["--registry", a.registry] if a.registry else []) + \
+              ["connect", "--goal-id", a.goal_id, "--objective", a.objective,
+               "--state-file", f".claude/goals/{a.goal_id}/ACTIVE_GOAL_STATE.md"]
+        print("[connect]", " ".join(cmd))
+        if not dry:
+            try:
+                rc = subprocess.run(cmd, cwd=str(proj), timeout=120)
+            except Exception as e:
+                print(f"[connect] FAILED to run loopx connect: {e}")
+                sys.exit(1)
+            if rc.returncode != 0:
+                # Fail closed: a non-zero connect (e.g. a global route collision)
+                # must stop the helper rather than print a misleading "next steps".
+                print(f"[connect] FAILED (exit {rc.returncode}) — not continuing. "
+                      "Resolve the error above and re-run.")
+                sys.exit(rc.returncode)
+
+    # 2. mark agent_backends += claude in the project registry (additive)
+    if a.registry:
+        reg = Path(a.registry)
+    else:
+        reg = proj / ".loopx" / "registry.json"
+        if not reg.exists() and (proj / ".goal-harness" / "registry.json").exists():
+            reg = proj / ".goal-harness" / "registry.json"
+    if reg.exists():
+        try:
+            data = json.loads(reg.read_text(encoding="utf-8"))
+            data.setdefault("agent_backends", [])
+            if "claude" not in data["agent_backends"]:
+                data["agent_backends"].append("claude")
+            print(f"[registry] mark agent_backends += claude  ({reg})")
+            if not dry:
+                reg.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        except Exception as e:
+            print("  (registry annotate skipped:", e, ")")
+    else:
+        print(f"[registry] {reg} not found yet (run with --objective to connect first)")
+
+    # 3. install the Claude adapter at PROJECT scope (MCP + /loopx command [+ --harden])
+    installer = PLUGIN_ROOT / "scripts" / "install.py"
+    inst = [sys.executable, str(installer), "--scope", "project", "--project", str(proj)]
+    if a.harden:
+        inst.append("--harden")
+    if dry:
+        inst.append("--dry-run")
+    print("[install]", " ".join(inst))
+    ri = subprocess.run(inst, cwd=str(proj))
+    if ri.returncode != 0:
+        # Fail closed: don't claim success / print next steps if the adapter
+        # install failed.
+        print(f"[install] FAILED (exit {ri.returncode}).")
+        sys.exit(ri.returncode)
+
+    print("\nNext: open Claude Code in the project, then:")
+    print("    /loopx <task>     # set the goal, write .claude/loop.md, do the first segment")
+    print("    /loop             # drive the loop (native; loopx should_run gates each tick)")
+    print("    /loopx off        # remove the loop protocol")
+
+
+if __name__ == "__main__":
+    main()