parallel-agents-cli 0.1.0__py3-none-any.whl

pa.py

@@ -0,0 +1,761 @@
+#!/usr/bin/env python3
+"""pa - keep parallel coding agents out of each other's way.
+
+Before an agent edits files, it claims them. Other agents see the claim and
+work elsewhere instead of overwriting each other. Claims expire on their own,
+so a crashed agent never blocks anyone for long.
+
+State lives in <git common dir>/parallel-agents (shared by every worktree of
+the repo and never committed), or in .parallel-agents/ outside git.
+
+Zero dependencies. Python 3.9+. macOS, Linux and Windows.
+"""
+
+import argparse
+import contextlib
+import fnmatch
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+
+try:
+    import fcntl  # POSIX
+except ImportError:  # pragma: no cover - Windows
+    fcntl = None
+    import msvcrt
+
+VERSION = "0.1.0"
+STATE_NAME = "parallel-agents"
+DEFAULT_TTL = 30 * 60
+EXIT_OK, EXIT_ERROR, EXIT_USAGE, EXIT_CONFLICT = 0, 1, 2, 3
+GLOB_CHARS = "*?["
+NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+WINDOWS_RESERVED = {"con", "prn", "aux", "nul"} | {"com%d" % i for i in range(1, 10)} | {"lpt%d" % i for i in range(1, 10)}
+CASE_INSENSITIVE_FS = sys.platform in ("darwin", "win32")
+
+
+class UsageError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Locating the repository and its shared state
+# ---------------------------------------------------------------------------
+
+class Workspace:
+    """Where we are: the worktree root (paths are relative to it) and the
+    state directory shared by all agents."""
+
+    def __init__(self, root, state):
+        self.root = os.path.realpath(root)
+        self.state = state
+
+    @classmethod
+    def discover(cls, cwd=None):
+        cwd = os.path.realpath(cwd or os.getcwd())
+        override = os.environ.get("PA_DIR")
+        git, error = _git_dirs(cwd)
+        if git:
+            root, common = git
+            return cls(root, override or os.path.join(common, STATE_NAME))
+        # Never fall back to a private board inside a repo that git can't read:
+        # that agent would see no one else's claims.
+        probe = cwd
+        while True:
+            if os.path.exists(os.path.join(probe, ".git")):
+                raise UsageError("this is a git repository but git failed (%s); fix git first" % (error or "unknown error"))
+            parent = os.path.dirname(probe)
+            if parent == probe:
+                break
+            probe = parent
+        # Outside git: use the nearest .parallel-agents up the tree, or create one here.
+        probe = cwd
+        while True:
+            candidate = os.path.join(probe, "." + STATE_NAME)
+            if os.path.isdir(candidate):
+                return cls(probe, override or candidate)
+            parent = os.path.dirname(probe)
+            if parent == probe:
+                return cls(cwd, override or os.path.join(cwd, "." + STATE_NAME))
+            probe = parent
+
+    @property
+    def claims_dir(self):
+        return os.path.join(self.state, "claims")
+
+    @property
+    def log_path(self):
+        return os.path.join(self.state, "log.jsonl")
+
+    def ensure(self):
+        os.makedirs(self.claims_dir, exist_ok=True)
+
+
+def _git_dirs(cwd):
+    """((worktree root, common dir), None) or (None, error text)."""
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel", "--git-common-dir"],
+            cwd=cwd, capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError) as e:
+        return None, str(e)
+    if out.returncode != 0:
+        return None, out.stderr.strip().splitlines()[-1] if out.stderr.strip() else "exit %d" % out.returncode
+    lines = out.stdout.strip().splitlines()
+    if len(lines) < 2:
+        return None, "unexpected git output"
+    root, common = lines[0], lines[1]
+    if not os.path.isabs(common):
+        common = os.path.join(cwd, common)
+    return (os.path.realpath(root), os.path.realpath(common)), None
+
+
+def same_path(a, b):
+    if a is None or b is None:
+        return a == b
+    a, b = os.path.normpath(a), os.path.normpath(b)
+    return a.casefold() == b.casefold() if CASE_INSENSITIVE_FS else a == b
+
+
+# ---------------------------------------------------------------------------
+# Locking and storage
+# ---------------------------------------------------------------------------
+
+@contextlib.contextmanager
+def locked(ws):
+    """Exclusive lock around every read and write of the board, so two agents
+    can never claim the same file at the same moment."""
+    ws.ensure()
+    fd = os.open(os.path.join(ws.state, ".lock"), os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        if fcntl:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        else:  # pragma: no cover - Windows
+            deadline = time.time() + 30
+            while True:
+                try:
+                    os.lseek(fd, 0, 0)
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    if time.time() > deadline:
+                        raise OSError("could not lock %s after 30s" % ws.state)
+                    time.sleep(0.02)
+        yield
+    finally:
+        if fcntl:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        else:  # pragma: no cover - Windows
+            try:
+                os.lseek(fd, 0, 0)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            except OSError:
+                pass
+        os.close(fd)
+
+
+def _atomic_write(path, data):
+    directory = os.path.dirname(path)
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def _agent_file(ws, agent):
+    return os.path.join(ws.claims_dir, agent + ".json")
+
+
+def _valid_claim(c):
+    return (isinstance(c, dict) and isinstance(c.get("paths"), list) and c["paths"]
+            and all(isinstance(p, str) for p in c["paths"])
+            and isinstance(c.get("heartbeat"), (int, float)) and isinstance(c.get("ttl"), (int, float))
+            and isinstance(c.get("created"), (int, float)))
+
+
+def load_all(ws):
+    """{agent: [claim, ...]} for every agent with a claims file. Call under the lock."""
+    result = {}
+    if not os.path.isdir(ws.claims_dir):
+        return result
+    for name in sorted(os.listdir(ws.claims_dir)):
+        if not name.endswith(".json") or name.startswith("."):
+            continue
+        try:
+            with open(os.path.join(ws.claims_dir, name), encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, ValueError):
+            continue  # a corrupt file never takes the whole board down
+        if not isinstance(data, dict) or not isinstance(data.get("claims"), list):
+            continue
+        agent = str(data.get("agent") or name[:-5]).lower()
+        result[agent] = [c for c in data["claims"] if _valid_claim(c)]
+    return result
+
+
+def save_agent(ws, agent, claims):
+    path = _agent_file(ws, agent)
+    if claims:
+        _atomic_write(path, {"agent": agent, "claims": claims})
+    else:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(path)
+
+
+def is_active(claim, now):
+    return now - claim["heartbeat"] <= claim["ttl"]
+
+
+def drop_expired(ws, board, now):
+    """Remove expired claims from disk. Returns the cleaned board and how many went."""
+    removed = 0
+    for agent in list(board):
+        alive = [c for c in board[agent] if is_active(c, now)]
+        if len(alive) != len(board[agent]):
+            removed += len(board[agent]) - len(alive)
+            save_agent(ws, agent, alive)
+            board[agent] = alive
+        if not board[agent]:
+            del board[agent]
+    return board, removed
+
+
+# ---------------------------------------------------------------------------
+# Paths, resources and overlap
+# ---------------------------------------------------------------------------
+
+def _is_glob(p):
+    return any(ch in p for ch in GLOB_CHARS)
+
+
+def normalize(ws, raw, cwd=None):
+    """Turn a user path into a repo-relative POSIX path.
+
+    - '@name' is a named resource (migrations, deps, a port) and is kept as is.
+    - An existing directory gets a trailing '/' (for display; any path covers
+      everything below it, existing or not).
+    - Globs are kept as patterns relative to the repo root, with the folder
+      part before the first wildcard resolved like any other path.
+    """
+    raw = raw.strip()
+    if not raw:
+        raise UsageError("empty path")
+    if raw.startswith("@"):
+        name = raw[1:].strip().lower()
+        if not name:
+            raise UsageError("empty resource name after '@'")
+        return "@" + name
+    cwd = os.path.realpath(cwd or os.getcwd())
+    unified = raw.replace("\\", "/") if os.sep == "\\" else raw
+    if _is_glob(unified):
+        parts = unified.split("/")
+        first = next(i for i, part in enumerate(parts) if _is_glob(part))
+        static = "/".join(parts[:first]) or "."
+        tail = "/".join(parts[first:]).rstrip("/")
+        base = os.path.realpath(os.path.join(cwd, static))
+        absolute = os.path.normpath(os.path.join(base, tail))
+    else:
+        absolute = os.path.realpath(os.path.join(cwd, raw))
+    try:
+        rel = os.path.relpath(absolute, ws.root)
+    except ValueError:  # another drive on Windows
+        raise UsageError("%s is outside the repository (%s)" % (raw, ws.root))
+    if rel == os.curdir:
+        raise UsageError("refusing to claim the whole repository; claim the files or folders you will edit")
+    if rel == os.pardir or rel.startswith(os.pardir + os.sep):
+        raise UsageError("%s is outside the repository (%s)" % (raw, ws.root))
+    rel = rel.replace(os.sep, "/").rstrip("/")
+    if not _is_glob(rel) and os.path.isdir(os.path.join(ws.root, rel)):
+        rel += "/"
+    return rel
+
+
+def _static_prefix(pattern):
+    """'src/api/*.py' -> 'src/api'; '*.py' -> '' (could match anything)."""
+    cut = min((pattern.index(ch) for ch in GLOB_CHARS if ch in pattern), default=len(pattern))
+    head = pattern[:cut]
+    return head[: head.rfind("/")] if "/" in head else ""
+
+
+def _variants(glob):
+    """'**/' may also match zero folders: 'src/**/*.py' also means 'src/*.py'."""
+    seen, todo = set(), [glob]
+    while todo:
+        g = todo.pop()
+        if g in seen:
+            continue
+        seen.add(g)
+        i = g.find("**/")
+        while i != -1:
+            todo.append(g[:i] + g[i + 3:])
+            i = g.find("**/", i + 1)
+    return seen
+
+
+def _matches(path, glob):
+    return any(fnmatch.fnmatchcase(path, g) for g in _variants(glob))
+
+
+def _witness(segment):
+    """A concrete file name the last glob segment would match."""
+    s = re.sub(r"\[![^\]]*\]", "~", segment)
+    s = re.sub(r"\[([^\]])[^\]]*\]", r"\1", s)
+    s = s.replace("*", "x").replace("?", "x")
+    return s or "x"
+
+
+def _under(path, folder):
+    return path == folder or path.startswith(folder + "/")
+
+
+def _glob_touches(glob, concrete):
+    """Could a glob claim and a concrete claim (which covers itself and
+    everything below it) touch the same file? Errs on the side of yes."""
+    prefix = _static_prefix(glob)
+    if prefix and _under(prefix, concrete):  # the concrete folder contains the glob's whole area
+        return True
+    parts = concrete.split("/")
+    for i in range(len(parts), 0, -1):  # the concrete path, or a folder above it, is matched
+        if _matches("/".join(parts[:i]), glob):
+            return True
+    leaf = _witness(glob.rsplit("/", 1)[-1])
+    for depth in range(5):  # something below the concrete folder is matched
+        if _matches(concrete + "/" + "x/" * depth + leaf, glob):
+            return True
+    return False
+
+
+def overlaps(a, b):
+    """Could these two claims touch the same file? Errs on the side of yes:
+    every comparison is case-insensitive (macOS and Windows file systems are),
+    and every path also covers anything that might later appear below it."""
+    a, b = a.casefold().rstrip("/"), b.casefold().rstrip("/")
+    if a.startswith("@") or b.startswith("@"):
+        return a == b
+    ga, gb = _is_glob(a), _is_glob(b)
+    if not ga and not gb:
+        return _under(a, b) or _under(b, a)
+    if ga and gb:
+        pa, pb = _static_prefix(a), _static_prefix(b)
+        return pa == "" or pb == "" or _under(pa, pb) or _under(pb, pa)
+    return _glob_touches(a, b) if ga else _glob_touches(b, a)
+
+
+def same_claim_path(a, b):
+    return a.casefold().rstrip("/") == b.casefold().rstrip("/")
+
+
+def covers(held, wanted):
+    """Does a path I already hold also cover this one? A folder covers what is
+    under it, so claiming a file inside a folder of mine records nothing new.
+    Keeps the board readable when an agent claims a folder and then edits
+    thirty files in it."""
+    h, w = held.casefold().rstrip("/"), wanted.casefold().rstrip("/")
+    if h == w:
+        return True
+    if h.startswith("@") or w.startswith("@") or _is_glob(w):
+        return False
+    return _matches(w, h) if _is_glob(h) else _under(w, h)
+
+
+def find_overlaps(ws, board, agent, paths, now):
+    """Split other agents' overlapping claims into blocking (same worktree)
+    and heads-up warnings (another worktree of the same repo)."""
+    conflicts, warnings = [], []
+    for other, claims in board.items():
+        if other == agent:
+            continue
+        for claim in claims:
+            if not is_active(claim, now):
+                continue
+            hits = sorted({p for p in paths for q in claim["paths"] if overlaps(p, q)})
+            if not hits:
+                continue
+            entry = {"agent": other, "claim": claim, "requested": hits}
+            (conflicts if same_path(claim.get("worktree"), ws.root) else warnings).append(entry)
+    return conflicts, warnings
+
+
+# ---------------------------------------------------------------------------
+# Formatting
+# ---------------------------------------------------------------------------
+
+def parse_ttl(text):
+    match = re.fullmatch(r"\s*(\d+)\s*([smh]?)\s*", text or "")
+    if not match:
+        raise UsageError("bad --ttl %r (use e.g. 90s, 30m, 2h)" % text)
+    value, unit = int(match.group(1)), match.group(2) or "m"
+    seconds = value * {"s": 1, "m": 60, "h": 3600}[unit]
+    if not 10 <= seconds <= 24 * 3600:
+        raise UsageError("--ttl must be between 10s and 24h")
+    return seconds
+
+
+def ago(seconds):
+    seconds = max(0, int(seconds))
+    if seconds < 60:
+        return "%ds" % seconds
+    if seconds < 3600:
+        return "%dm" % (seconds // 60)
+    return "%dh%02dm" % (seconds // 3600, (seconds % 3600) // 60)
+
+
+def describe(entry, now, ws):
+    c = entry["claim"]
+    where = "" if same_path(c.get("worktree"), ws.root) else "  [worktree %s]" % c.get("worktree")
+    why = (' "%s"' % c["why"]) if c.get("why") else ""
+    return "%s holds %s%s (since %s ago, expires in %s)%s" % (
+        entry["agent"], ", ".join(c["paths"]), why,
+        ago(now - c["created"]), ago(c["heartbeat"] + c["ttl"] - now), where)
+
+
+def brief(entry):
+    c = entry["claim"]
+    return {"agent": entry["agent"], "paths": c["paths"], "why": c.get("why", ""),
+            "requested": entry["requested"], "worktree": c.get("worktree")}
+
+
+def emit_json(obj):
+    print(json.dumps(obj, indent=2, sort_keys=True))
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def need_agent(args):
+    agent = (args.as_ or os.environ.get("PA_AS") or "").strip().lower()
+    if not agent:
+        raise UsageError("say who you are: --as <name> (e.g. --as claude-7f2c), or set PA_AS")
+    if not NAME_RE.match(agent):
+        raise UsageError("agent name %r: use letters, digits, '.', '_' or '-' (max 64)" % agent)
+    if agent.split(".")[0] in WINDOWS_RESERVED:
+        raise UsageError("agent name %r is reserved on Windows; pick another" % agent)
+    return agent
+
+
+def optional_agent(args):
+    return need_agent(args) if (args.as_ or os.environ.get("PA_AS")) else None
+
+
+def cmd_init(ws, args):
+    ws.ensure()
+    if args.json:
+        emit_json({"ok": True, "state": ws.state, "root": ws.root})
+    else:
+        print("parallel-agents state: %s" % ws.state)
+        print("repository root:       %s" % ws.root)
+    return EXIT_OK
+
+
+def cmd_claim(ws, args):
+    agent = need_agent(args)
+    ttl = parse_ttl(args.ttl) if args.ttl else DEFAULT_TTL
+    paths = sorted({normalize(ws, p) for p in args.paths})
+    now = time.time()
+    with locked(ws):
+        board, _ = drop_expired(ws, load_all(ws), now)
+        mine = board.get(agent, [])
+        for c in mine:  # any claim attempt, even a blocked one, refreshes all of mine
+            c["heartbeat"] = now
+        conflicts, warnings = find_overlaps(ws, board, agent, paths, now)
+        if conflicts:
+            save_agent(ws, agent, mine)
+            if args.json:
+                emit_json({"ok": False, "agent": agent, "conflicts": [brief(c) for c in conflicts]})
+            else:
+                print("BLOCKED: nothing was claimed.")
+                for c in conflicts:
+                    print("  " + describe(c, now, ws))
+                print("Do not edit these paths. Work on something else and retry later, or ask the user.")
+            return EXIT_CONFLICT
+
+        held = [p for c in mine for p in c["paths"]]
+        new_paths = [p for p in paths if not any(covers(h, p) for h in held)]
+        for c in mine:
+            c["ttl"] = max(c["ttl"], ttl)
+        if new_paths:
+            mine.append({
+                "id": uuid.uuid4().hex[:8],
+                "paths": new_paths,
+                "why": args.why or "",
+                "worktree": ws.root,
+                "created": now,
+                "heartbeat": now,
+                "ttl": ttl,
+            })
+        save_agent(ws, agent, mine)
+
+    if args.json:
+        emit_json({"ok": True, "agent": agent, "claimed": paths, "expires_in": ttl,
+                   "warnings": [brief(w) for w in warnings]})
+    else:
+        print("OK: %s now holds %s (expires in %s unless renewed)." % (agent, ", ".join(paths), ago(ttl)))
+        for w in warnings:
+            print("WARN: same paths in another worktree, expect a merge conflict: " + describe(w, now, ws))
+    return EXIT_OK
+
+
+def cmd_release(ws, args):
+    agent = need_agent(args)
+    targets = [normalize(ws, p) for p in args.paths] if args.paths else None
+    released, keep = [], []
+    with locked(ws):
+        mine = load_all(ws).get(agent, [])
+        for c in mine:
+            if targets is None:
+                released.extend(c["paths"])
+                continue
+            gone = [p for p in c["paths"] if any(same_claim_path(p, t) for t in targets)]
+            released.extend(gone)
+            remaining = [p for p in c["paths"] if p not in gone]
+            if remaining:
+                c["paths"] = remaining
+                keep.append(c)
+        save_agent(ws, agent, keep)
+        held = [p for c in keep for p in c["paths"]]
+    missing = [t for t in (targets or []) if not any(same_claim_path(t, r) for r in released)]
+    if args.json:
+        emit_json({"ok": True, "agent": agent, "released": sorted(released), "not_held": missing})
+        return EXIT_OK
+    if released:
+        print("OK: %s released %s." % (agent, ", ".join(sorted(released))))
+    elif targets is None:
+        print("Nothing to release for %s." % agent)
+    for t in missing:
+        print("NOT HELD: %s. You hold: %s" % (t, ", ".join(held) or "nothing"))
+    return EXIT_OK
+
+
+def cmd_check(ws, args):
+    agent = optional_agent(args)
+    paths = sorted({normalize(ws, p) for p in args.paths})
+    now = time.time()
+    with locked(ws):
+        board = load_all(ws)
+    conflicts, warnings = find_overlaps(ws, board, agent, paths, now)
+    if args.json:
+        emit_json({"ok": not conflicts, "free": not conflicts,
+                   "conflicts": [brief(c) for c in conflicts], "warnings": [brief(w) for w in warnings]})
+    elif conflicts:
+        for c in conflicts:
+            print("TAKEN: " + describe(c, now, ws))
+    else:
+        print("FREE: %s" % ", ".join(paths))
+        for w in warnings:
+            print("WARN: " + describe(w, now, ws))
+    return EXIT_CONFLICT if conflicts else EXIT_OK
+
+
+def cmd_status(ws, args):
+    now = time.time()
+    with locked(ws):
+        board = load_all(ws)
+    board = {a: [c for c in cs if is_active(c, now)] for a, cs in board.items()}
+    board = {a: cs for a, cs in board.items() if cs}
+    if args.json:
+        emit_json({"ok": True, "state": ws.state, "agents": {
+            a: [dict(c, expires_in=int(c["heartbeat"] + c["ttl"] - now)) for c in cs]
+            for a, cs in board.items()}})
+        return EXIT_OK
+    if not board:
+        print("No active claims. Everything is free.")
+        return EXIT_OK
+    for agent, claims in sorted(board.items()):
+        print(agent)
+        for c in claims:
+            where = "" if same_path(c.get("worktree"), ws.root) else "  [worktree %s]" % c.get("worktree")
+            why = ('  "%s"' % c["why"]) if c.get("why") else ""
+            print("  %s%s  (since %s ago, expires in %s)%s" % (
+                ", ".join(c["paths"]), why, ago(now - c["created"]),
+                ago(c["heartbeat"] + c["ttl"] - now), where))
+    return EXIT_OK
+
+
+def cmd_renew(ws, args):
+    agent = need_agent(args)
+    ttl = parse_ttl(args.ttl) if args.ttl else None
+    now = time.time()
+    with locked(ws):
+        board, _ = drop_expired(ws, load_all(ws), now)
+        mine = board.get(agent, [])
+        for c in mine:
+            c["heartbeat"] = now
+            if ttl:
+                c["ttl"] = ttl
+        save_agent(ws, agent, mine)
+    if args.json:
+        emit_json({"ok": bool(mine), "agent": agent, "renewed": len(mine)})
+    elif mine:
+        print("OK: renewed %d claim(s) for %s." % (len(mine), agent))
+    else:
+        print("NOTHING HELD: %s has no live claims. They may have expired; claim again before editing." % agent)
+    return EXIT_OK if mine else EXIT_CONFLICT
+
+
+def cmd_note(ws, args):
+    agent = need_agent(args)
+    text = " ".join(args.text).strip()
+    if not text:
+        raise UsageError("note text is empty")
+    entry = {"ts": time.time(), "agent": agent, "text": text,
+             "paths": sorted({normalize(ws, p) for p in (args.paths or [])})}
+    with locked(ws):
+        with open(ws.log_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    if args.json:
+        emit_json({"ok": True, "note": entry})
+    else:
+        print("OK: note saved.")
+    return EXIT_OK
+
+
+def cmd_log(ws, args):
+    entries = []
+    with locked(ws):
+        if os.path.exists(ws.log_path):
+            with open(ws.log_path, encoding="utf-8") as f:
+                for line in f:
+                    with contextlib.suppress(ValueError):
+                        e = json.loads(line)
+                        if isinstance(e, dict) and isinstance(e.get("ts"), (int, float)) and e.get("text"):
+                            entries.append(e)
+    entries = entries[-max(1, args.n):]
+    if args.json:
+        emit_json(entries)
+        return EXIT_OK
+    if not entries:
+        print("No notes yet.")
+    now = time.time()
+    for e in entries:
+        paths = (" [%s]" % ", ".join(e["paths"])) if e.get("paths") else ""
+        print("%s ago  %s: %s%s" % (ago(now - e["ts"]), e.get("agent", "?"), e["text"], paths))
+    return EXIT_OK
+
+
+def cmd_gc(ws, args):
+    with locked(ws):
+        _, removed = drop_expired(ws, load_all(ws), time.time())
+        for name in os.listdir(ws.claims_dir):  # leftovers of a process killed mid-write
+            path = os.path.join(ws.claims_dir, name)
+            if name.startswith(".tmp-") and time.time() - os.path.getmtime(path) > 60:
+                with contextlib.suppress(OSError):
+                    os.unlink(path)
+    if args.json:
+        emit_json({"ok": True, "removed": removed})
+    else:
+        print("Removed %d expired claim(s)." % removed)
+    return EXIT_OK
+
+
+def cmd_evict(ws, args):
+    """Human override: drop another agent's claims (e.g. it crashed and you
+    don't want to wait for the TTL)."""
+    target = args.agent.strip().lower()
+    with locked(ws):
+        count = sum(len(c["paths"]) for c in load_all(ws).get(target, []))
+        save_agent(ws, target, [])
+    if args.json:
+        emit_json({"ok": True, "evicted": target, "paths": count})
+    else:
+        print("Evicted %s (%d path(s))." % (target, count))
+    return EXIT_OK
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="pa",
+        description="Keep parallel coding agents out of each other's way: claim files before editing them.",
+        epilog="Exit codes: 0 ok, 1 error, 2 usage error (nothing was claimed), 3 blocked or nothing held.",
+    )
+    p.add_argument("--version", action="version", version="parallel-agents " + VERSION)
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    def add(name, help_text, func):
+        sp = sub.add_parser(name, help=help_text, description=help_text)
+        sp.set_defaults(func=func)
+        sp.add_argument("--json", action="store_true", help="machine-readable output")
+        return sp
+
+    def who(sp, required=True):
+        sp.add_argument("--as", dest="as_", metavar="NAME",
+                        help="your agent name, e.g. claude-7f2c (or set PA_AS)" if required
+                        else "your agent name; your own claims never count as taken")
+
+    add("init", "Create the shared state directory and show where it is.", cmd_init)
+
+    sp = add("claim", "Claim files, folders, globs or @resources before editing them.", cmd_claim)
+    sp.add_argument("paths", nargs="+", metavar="PATH")
+    who(sp)
+    sp.add_argument("--why", help="what you are about to do (shown to other agents)")
+    sp.add_argument("--ttl", help="how long the claim lives without renewal (default 30m)")
+
+    sp = add("release", "Release some or all of your claims.", cmd_release)
+    sp.add_argument("paths", nargs="*", metavar="PATH")
+    who(sp)
+
+    sp = add("check", "Exit 0 if free (or yours with --as), 3 if another agent holds it.", cmd_check)
+    sp.add_argument("paths", nargs="+", metavar="PATH")
+    who(sp, required=False)
+
+    add("status", "Show who holds what right now.", cmd_status)
+
+    sp = add("renew", "Keep your claims alive during long tasks (exit 3 if you hold nothing).", cmd_renew)
+    who(sp)
+    sp.add_argument("--ttl", help="new lifetime, e.g. 1h")
+
+    sp = add("note", "Leave a handoff note for the next agent.", cmd_note)
+    sp.add_argument("text", nargs="+")
+    who(sp)
+    sp.add_argument("--paths", nargs="*", metavar="PATH", help="files the note is about")
+
+    sp = add("log", "Read recent handoff notes.", cmd_log)
+    sp.add_argument("-n", type=int, default=10, help="how many (default 10)")
+
+    add("gc", "Delete expired claims and leftover temp files.", cmd_gc)
+
+    sp = add("evict", "Human override: drop all claims of another agent.", cmd_evict)
+    sp.add_argument("agent")
+
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return EXIT_USAGE
+    try:
+        return args.func(Workspace.discover(), args)
+    except UsageError as e:
+        if getattr(args, "json", False):
+            emit_json({"ok": False, "error": str(e)})
+        print("error: %s" % e, file=sys.stderr)
+        return EXIT_USAGE
+    except OSError as e:
+        if getattr(args, "json", False):
+            emit_json({"ok": False, "error": str(e)})
+        print("error: %s" % e, file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pa_hook.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""pa-hook - enforce parallel-agents claims from inside the agent.
+
+Claude Code runs this as a PreToolUse hook. Before an agent writes to a file
+the hook claims that path; if another agent already holds it, the edit is
+denied and the agent is told who holds it and why. The protocol then holds
+even for an agent that never loaded the skill.
+
+Reads the hook payload on stdin, writes a PreToolUse decision on stdout.
+
+Anything unexpected lets the edit through. A coordination helper must never be
+the reason a session stops working, so a broken payload, a missing pa.py or a
+slow claim all fall back to allowing the edit.
+
+Environment:
+  PA_AS           this agent's name (default: claude-<session id>)
+  PA_HOOK_DISABLE set to anything to turn the hook off
+  PA_HOOK_MODE    "claim" (default) also takes the path; "check" only blocks
+  PA_HOOK_TTL     how long an auto-claim lives without a further edit (15m)
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+EDITING_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+PATH_KEYS = ("file_path", "notebook_path")
+PA = os.path.join(os.path.dirname(os.path.abspath(__file__)), "pa.py")
+DEFAULT_TTL = "15m"
+EXIT_CONFLICT = 3
+TIMEOUT = 10
+
+
+def allow():
+    """Say nothing: Claude Code then decides the call on its own rules."""
+    sys.exit(0)
+
+
+def deny(reason):
+    json.dump({"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": reason,
+    }}, sys.stdout)
+    sys.exit(0)
+
+
+def wanted_paths(tool_input):
+    out = []
+    for key in PATH_KEYS:
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            out.append(value)
+    return out
+
+
+def agent_name(payload):
+    """This agent's name: PA_AS, else one derived from the session id.
+
+    Two Claude Code sessions on one repo get different session ids, which is
+    exactly the identity the board needs. pa.py requires [a-z0-9][a-z0-9._-]*.
+    """
+    name = (os.environ.get("PA_AS") or "").strip()
+    if name:
+        return name
+    session = "".join(c for c in str(payload.get("session_id") or "") if c.isalnum())
+    return ("claude-" + session[:8].lower()) if session else "claude"
+
+
+def explain(stdout, paths):
+    holders = []
+    try:
+        for conflict in (json.loads(stdout).get("conflicts") or []):
+            who = conflict.get("agent") or "another agent"
+            held = ", ".join(conflict.get("paths") or []) or conflict.get("requested") or ""
+            why = conflict.get("why") or ""
+            holders.append("%s holds %s%s" % (who, held, ' "%s"' % why if why else ""))
+    except (ValueError, AttributeError):
+        pass
+    lines = ["parallel-agents: %s is claimed by another agent." % ", ".join(paths)]
+    lines.extend("  " + h for h in holders)
+    lines.append("Do not edit these paths. Work on something else and come back to them, "
+                 "or ask the user. `pa status` shows the whole board.")
+    return "\n".join(lines)
+
+
+def main():
+    if os.environ.get("PA_HOOK_DISABLE"):
+        allow()
+    try:
+        payload = json.load(sys.stdin)
+    except (ValueError, OSError):
+        allow()
+    if not isinstance(payload, dict) or payload.get("tool_name") not in EDITING_TOOLS:
+        allow()
+
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        allow()
+    paths = wanted_paths(tool_input)
+    if not paths or not os.path.exists(PA):
+        allow()
+
+    check_only = (os.environ.get("PA_HOOK_MODE") or "").strip().lower() == "check"
+    argv = [sys.executable, PA, "check" if check_only else "claim"]
+    argv += paths + ["--as", agent_name(payload), "--json"]
+    if not check_only:
+        argv += ["--why", "%s via Claude Code" % payload["tool_name"],
+                 "--ttl", (os.environ.get("PA_HOOK_TTL") or DEFAULT_TTL).strip()]
+
+    try:
+        done = subprocess.run(argv, cwd=payload.get("cwd") or None,
+                              stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                              universal_newlines=True, timeout=TIMEOUT)
+    except (OSError, subprocess.SubprocessError):
+        allow()
+
+    # Only a conflict blocks. A usage or disk error means the board is not
+    # answering, and a board that cannot answer must not hold the agent up.
+    if done.returncode != EXIT_CONFLICT:
+        allow()
+    deny(explain(done.stdout, paths))
+
+
+if __name__ == "__main__":
+    main()

parallel_agents_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: parallel-agents-cli
+Version: 0.1.0
+Summary: Run Claude Code, Codex, Cursor and Gemini CLI on the same repo without them overwriting each other.
+Author-email: Alisher Muhammadaliyev <viltrumlik@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Viltrumlik/parallel-agents
+Project-URL: Source, https://github.com/Viltrumlik/parallel-agents
+Project-URL: Issues, https://github.com/Viltrumlik/parallel-agents/issues
+Project-URL: Changelog, https://github.com/Viltrumlik/parallel-agents/blob/main/CHANGELOG.md
+Keywords: claude-code,codex,cursor,gemini-cli,multi-agent,coordination,file-locking,agent-skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viltrumlik/parallel-agents/main/.claude-plugin/icon.png" width="112" alt="parallel-agents icon">
+</p>
+
+<h1 align="center">parallel-agents</h1>
+
+<p align="center">
+  <b>Run Claude Code, Codex, Cursor and Gemini CLI on the same repo without them overwriting each other.</b>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Viltrumlik/parallel-agents/actions/workflows/ci.yml"><img src="https://github.com/Viltrumlik/parallel-agents/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Agent%20Skills-SKILL.md-7c3aed" alt="Agent Skills">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viltrumlik/parallel-agents/main/demo/demo.gif" alt="Two agents share a repo: the second agent is blocked from a folder the first one claimed, works on tests instead, and takes the file once the first agent releases it" width="900">
+</p>
+
+Running several coding agents at once is the new normal. In one checkout, though, they collide: two agents edit the same file, one runs migrations while the other changes models, both start a dev server on port 3000. **parallel-agents** gives them a tiny shared protocol: **claim before you edit, see who holds what, leave a note, release.**
+
+It's an [Agent Skill](https://agentskills.io), a `SKILL.md` plus one zero-dependency Python script, so it works in every agent that reads skills. In Claude Code a hook enforces it, so an agent that never read the skill still can't overwrite another one's work.
+
+## How it works
+
+```bash
+pa status                                                            # who is doing what
+pa claim src/billing/ --as claude-7f2c --why "add refund endpoint"   # before the first edit
+pa claim @migrations --as claude-7f2c --why "add refunds table"      # shared operations too
+pa note "refunds done, tests still missing" --as claude-7f2c         # handoff for the next agent
+pa release --as claude-7f2c                                          # done
+```
+
+If another agent already holds something, `pa claim` refuses (exit code `3`), says who holds it and why, and the agent works on something else instead.
+
+- **Enforced in Claude Code.** A `PreToolUse` hook claims each path before the edit and refuses the edit outright if another agent holds it. Everywhere else the skill carries the protocol.
+- **Atomic.** Checking and claiming happen under one file lock. If 16 agents claim the same file at the same moment, exactly one wins (there's a test for that).
+- **Never stuck.** Claims expire after 30 minutes without activity, so a crashed agent can't block the repo. Agents refresh them by re-claiming before each batch of edits.
+- **Conservative.** Any doubt counts as overlap: paths compare case-insensitively, symlinks are resolved, a folder that doesn't exist yet still covers what will be created in it, and `src/**/*.py` collides with `src/app.py`.
+- **Invisible to git.** State lives in the repo's git directory (`.git/parallel-agents/`). Nothing to commit, nothing to `.gitignore`. Outside git it falls back to a `.parallel-agents/` folder.
+- **Worktree-aware.** All worktrees of a repo share the state. Editing the same file in another worktree isn't blocked, but you get a warning about the merge conflict ahead.
+- **Files, folders, globs and resources.** `src/api/views.py`, `src/api/`, `src/**/*.py`, plus named resources like `@migrations`, `@deps`, `@port:3000` and `@db`.
+
+## Install
+
+**Requirements:** Python 3.9+ on macOS, Linux or Windows. Nothing to `pip install`. Git is optional: inside a repo the state goes into the git directory, outside one into `.parallel-agents/`.
+
+**Any agent** (Claude Code, Codex, Cursor, Gemini CLI, Copilot…) with the [skills CLI](https://skills.sh):
+
+```bash
+npx skills add Viltrumlik/parallel-agents
+```
+
+**Claude Code** plugin marketplace:
+
+```
+/plugin marketplace add Viltrumlik/parallel-agents
+/plugin install parallel-agents@parallel-agents
+```
+
+Installed as a plugin, the protocol is **enforced**: a `PreToolUse` hook runs before every `Edit`, `Write`, `MultiEdit` and `NotebookEdit`, claims the path for this session, and denies the edit — naming who holds it and why — if another agent got there first. Each Claude Code session is its own agent, named after its session id, so two sessions on one repo coordinate with no setup.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `PA_AS` | `claude-<session id>` | this agent's name on the board |
+| `PA_HOOK_TTL` | `15m` | how long an auto-claim lives without a further edit |
+| `PA_HOOK_MODE` | `claim` | `check` blocks without taking the path |
+| `PA_HOOK_DISABLE` | unset | set to anything to turn the hook off |
+
+If anything goes wrong — a payload it doesn't understand, a missing `pa.py`, a board that won't answer — the edit goes through. A coordination helper is never the reason a session stops working.
+
+**Manually:** copy [`skills/parallel-agents`](skills/parallel-agents) into your agent's skills folder: `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/`, or `.agents/skills/` inside a project.
+
+**Just the `pa` command**, to drive the board yourself from a terminal:
+
+```bash
+pipx install parallel-agents-cli
+```
+
+### Make it always-on
+
+Skills load when an agent thinks they're relevant. To make sure every agent follows the protocol from its first edit, paste [`snippets/AGENTS.md`](snippets/AGENTS.md) into your repo's `AGENTS.md` (Codex, Cursor, Gemini) or `CLAUDE.md`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pa status [--json]` | Who holds what right now |
+| `pa claim PATH... --as NAME --why TEXT [--ttl 30m]` | Claim before editing. All or nothing; exit `3` if blocked |
+| `pa check PATH... [--as NAME]` | Exit `0` if free (or yours), `3` if taken |
+| `pa release [PATH...] --as NAME` | Release some paths, or all of yours |
+| `pa renew --as NAME [--ttl 1h]` | Keep claims alive; exit `3` if nothing is held anymore |
+| `pa note TEXT --as NAME [--paths ...]` | Leave a handoff note |
+| `pa log [-n 10] [--json]` | Read recent notes |
+| `pa gc` | Delete expired claims |
+| `pa evict AGENT` | Human override: drop an agent's claims |
+
+Every command accepts `--json`, so agents can parse the output. You can set `PA_AS` instead of passing `--as`.
+
+Exit codes: `0` ok · `1` error (disk, lock) · `2` wrong command, nothing was claimed · `3` blocked by another agent, or nothing held.
+
+## FAQ
+
+**Why not just use git worktrees?** Use both. Worktrees isolate files, but the agents still share your database, ports and lockfile, and you meet their overlapping edits later as merge conflicts. parallel-agents coordinates the shared resources and warns about overlaps across worktrees while there's still time to split the work.
+
+**Is it enforced?** In Claude Code, yes. Install it as a plugin and a `PreToolUse` hook runs before every edit: it claims the path for this session, and refuses the edit if another agent holds it. An agent that never loaded the skill still cannot overwrite another one's work. Everywhere else it's an advisory protocol that agents follow through the skill — Cursor and Codex hooks are next.
+
+**Does it work across machines?** No, it coordinates agents that share one filesystem. That covers the common setup of several agents on your laptop or one dev box.
+
+**Will it slow my agents down?** Each command is a single short Python process, and the skill tells agents to claim once per batch of edits, not once per edit. In Claude Code the skill adds about 130 tokens to a session and about 1,200 when it is used (`claude plugin details`).
+
+## Roadmap
+
+- [x] Hooks that block edits to files another agent holds — Claude Code done, Cursor and Codex next
+- [ ] `pa watch`: a live terminal view of who holds what
+- [ ] Editor status-bar integrations
+- [ ] Claims that follow git branches
+
+Ideas and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v   # the full test suite, including the 16-agent race
+bash demo/two-agents.sh                    # two agents sharing a throwaway repo, step by step
+```
+
+CI runs the tests on Ubuntu, macOS and Windows with Python 3.9, 3.10 and 3.13.
+
+```
+skills/parallel-agents/
+├── SKILL.md              # the protocol agents read
+└── scripts/
+    ├── pa.py             # the `pa` CLI: one file, zero dependencies
+    └── pa_hook.py        # Claude Code PreToolUse hook
+pyproject.toml            # the PyPI package: pipx install parallel-agents-cli
+hooks/hooks.json          # registers the hook when installed as a plugin
+.claude-plugin/           # plugin and marketplace manifests
+snippets/AGENTS.md        # always-on instructions for AGENTS.md / CLAUDE.md
+tests/                    # end-to-end tests against real git repos
+demo/                     # demo script and GIF generator
+```
+
+## License
+
+[MIT](LICENSE) © Alisher ([@Viltrumlik](https://github.com/Viltrumlik))

parallel_agents_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pa.py,sha256=bgWU-8vmaVK2-4PzhWUs96_NCmHOgngdjMDzqCwfa-A,28109
+pa_hook.py,sha256=wRfH5XW_-zjjjCEZ7I0e6lyZFSPv6xZCQ4gEAk0dsjE,4469
+parallel_agents_cli-0.1.0.dist-info/licenses/LICENSE,sha256=WHxEksSGrdAAA6UbFYxEom_yI8krJiy_80b5zhR593M,1077
+parallel_agents_cli-0.1.0.dist-info/METADATA,sha256=KGym0J036ZUc5r5PYxY8RxzkGWoDmTTUOzJOsASq9OY,10265
+parallel_agents_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+parallel_agents_cli-0.1.0.dist-info/entry_points.txt,sha256=MvhLx53YpF252CkscQcYkKWNxRwbszrliX74Ed6FDXE,31
+parallel_agents_cli-0.1.0.dist-info/top_level.txt,sha256=6ad4h9HwhEXBr52XNSkTs711sWIYnhqrk6f1D9lD_-w,11
+parallel_agents_cli-0.1.0.dist-info/RECORD,,

parallel_agents_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

parallel_agents_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pa = pa:main

parallel_agents_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alisher (Viltrumlik)
+
+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.

parallel_agents_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pa
+pa_hook