{"_id":"@avee1234/worklease","_rev":"4-626db22d83f835f67d6653015db7da25","name":"@avee1234/worklease","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@avee1234/worklease","version":"0.1.1","keywords":["ai","agent","multi-agent","coordination","parallel","coding-agents","git-worktree","file-lease","fleet","claude-code","codex","cursor","conflict-prevention","zero-dependency"],"license":"MIT","_id":"@avee1234/worklease@0.1.1","maintainers":[{"name":"avee1234","email":"das.abhijit34@gmail.com"}],"bin":{"worklease":"bin/worklease.js"},"dist":{"shasum":"39eebf77bd7a0168a36981a6f2c80872907353f2","tarball":"https://registry.npmjs.org/@avee1234/worklease/-/worklease-0.1.1.tgz","fileCount":12,"integrity":"sha512-E7oBO/xeVDsOA4hBEG2KVxIpPUFihpNU+VzkLTwr75nGsvkXtTtzptJBa8Y3cqJsr/aZ1SK+GL23Z+s05YReiQ==","signatures":[{"sig":"MEUCIC1w6Zqdf5iXBC/4CGUsDpx+cvtYhhUkXS5OaZvqWfgGAiEAg4mllhNTvgiZcA0JI3bnDZ+ttVjJkG+eGj6NcwFHhKE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72305},"main":"src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"5818f7be59cf9bda40eb80feedb0aaf9022caca6","scripts":{"test":"node --test"},"_npmUser":{"name":"avee1234","email":"das.abhijit34@gmail.com"},"_npmVersion":"10.9.8","description":"The open coordination format for fleets of AI coding agents. Agents declare intent to edit file globs before they start, so parallel agents don't duplicate work or collide on hotspot files. Zero dependencies, harness-neutral, git-backed.","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/worklease_0.1.1_1783915812806_0.8869454469440927","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@avee1234/worklease","version":"0.1.2","description":"The open coordination format for fleets of AI coding agents. Agents declare intent to edit file globs before they start, so parallel agents don't duplicate work or collide on hotspot files. Zero dependencies, harness-neutral, git-backed.","type":"module","main":"src/index.js","bin":{"worklease":"bin/worklease.js"},"engines":{"node":">=18"},"scripts":{"test":"node --test"},"keywords":["ai","agent","multi-agent","coordination","parallel","coding-agents","git-worktree","file-lease","fleet","claude-code","codex","cursor","conflict-prevention","zero-dependency"],"license":"MIT","gitHead":"e90bd868cbd331169aadc1474f4d77439986b48e","_id":"@avee1234/worklease@0.1.2","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-aONcHDGWZ0wOs4nTodj57PXOEJF4ijUTWS7gG5yo/V9jHKFbxa00XLM+W7PYBiYE50VTs7zoMBLP7lJd3pG0uA==","shasum":"ae6d2d3ed01b08f3500138ddf1fe79e6c2062b0d","tarball":"https://registry.npmjs.org/@avee1234/worklease/-/worklease-0.1.2.tgz","fileCount":12,"unpackedSize":76451,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCPmxwjkNEVghPv5tlXUuWLWzPXPZXPxCmOdptt94REZAIhAJ7VoSPiDeFWEyPzcRcVDYlp7RNH8tUf+huP4LzvA9K+"}]},"_npmUser":{"name":"avee1234","email":"das.abhijit34@gmail.com"},"directories":{},"maintainers":[{"name":"avee1234","email":"das.abhijit34@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/worklease_0.1.2_1784123950946_0.8752982503858904"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-13T04:06:40.105Z","modified":"2026-07-15T13:59:11.194Z","0.1.0":"2026-07-13T04:06:40.509Z","0.1.1":"2026-07-13T04:10:12.942Z","0.1.2":"2026-07-15T13:59:11.094Z"},"license":"MIT","keywords":["ai","agent","multi-agent","coordination","parallel","coding-agents","git-worktree","file-lease","fleet","claude-code","codex","cursor","conflict-prevention","zero-dependency"],"description":"The open coordination format for fleets of AI coding agents. Agents declare intent to edit file globs before they start, so parallel agents don't duplicate work or collide on hotspot files. Zero dependencies, harness-neutral, git-backed.","maintainers":[{"name":"avee1234","email":"das.abhijit34@gmail.com"}],"readme":"# worklease\n\n**The open coordination format for fleets of AI coding agents.** Before an agent starts editing, it files a *claim* — \"I intend to touch `src/auth/**` for the next 20 minutes\" — to a shared, conflict-free registry. Other agents see it and steer clear. So parallel agents stop duplicating work and colliding on hotspot files. Zero dependencies.\n\n> Working name — see [`vision.md`](vision.md). Grounded in the mid-2026 state of parallel agent coding.\n\nGit worktrees are now the default for running many coding agents at once (Claude Code, Codex, Cursor, Google Antigravity) — but they only isolate the *filesystem*. Nothing warns you when two agents are about to edit the same code, so parallel runs still produce merge conflicts, duplicated features, and logic that compiles but disagrees at runtime. worklease is the missing coordination layer: a format for *intent*, not another orchestrator.\n\n```bash\nworklease claim \"src/auth/**\" --intent \"add OAuth\" --ttl 20m   # I'm taking this\nworklease check \"src/auth/login.ts\"                            # is anyone else on it?\nworklease list                                                  # who holds what, expiring when\nworklease release <id>                                          # done\nworklease conformance registry.jsonl merges.json               # did the fleet actually coordinate?\nworklease hook install                                         # auto-check staged files before every commit\n```\n\n**Why it's different:** advisory, not a hard lock — it *warns and coordinates* so agents can pick different work. The registry is append-only JSONL with content-hash IDs, so it never merge-conflicts with itself even when many agents write at once. Harness-neutral: Claude Code, Codex, Cursor, Google Antigravity, or a factory worker.\n\nSame open-format-and-conformance playbook as [opentrajectory](https://github.com/abhid1234/opentrajectory) and [constraintguard](https://github.com/abhid1234/constraintguard) — the coordination standard for the one thing a fleet can't currently share: *what it's about to touch.*\n\n### `worklease claim <globs...>`\n\nFiles a claim — declares that you intend to edit the given globs, for a reason,\nfor a while — and **appends** it to the registry as one JSON line. This is the\nwrite verb: `check` only ever reports clear until someone has claimed something.\n\n```bash\nworklease claim \"src/auth/**\" --intent \"add OAuth\" --ttl 20m --agent me\nworklease claim \"src/api/**\" --intent \"rate limits\" --json    # print the claim object\n```\n\n- `--intent <str>` — **required**; why you're claiming (a claim without intent\n  isn't useful — it's what lets another agent decide to wait or pick other work).\n- `--ttl <dur>` — lease length: `<n>s`/`<n>m`/`<n>h` (e.g. `90s`, `20m`, `2h`) or a\n  bare integer number of seconds. Default `30m`.\n- `--agent <id>` (or `WORKLEASE_AGENT`) — who is filing; **required**.\n- `--registry <path>` (or `WORKLEASE_REGISTRY`) — registry file location\n  (default `.worklease/registry.jsonl`; the parent directory is created if\n  missing).\n- `--json` — print the created claim object instead of the human summary.\n\nThe written record is a fully-valid claim: `id` is the registry's deterministic\ncontent hash of the record, and `expires` is `created + ttl`. The claim is\nvalidated before it's written, so an unsupported glob is rejected rather than\nappended. Exit `0` on write, `1` on any input or validation error.\n\nThe library also exports the pure `makeClaim(globs, meta)` constructor (no I/O,\nno clock — `created` is passed in) for building claims programmatically.\n\n### `worklease check <globs...>`\n\nAsks whether your planned edit overlaps any **active** claim held by **another**\nagent — the safe pre-edit question. Overlap is decided purely from the glob\nstrings (conservative *satisfiability*: any concrete path could match both), with\nno filesystem access, so it is correct even for files that don't exist yet.\n\n```bash\nworklease check \"src/auth/**\"                 # human summary; exit 1 on conflict\nworklease check \"src/**/*.ts\" --json          # { clear, conflicts: [...] } for harnesses\nworklease check \"src/auth/**\" --agent me      # my own claims count as clear\n```\n\n- `--agent <id>` (or `WORKLEASE_AGENT`) — treat your own claims as clear.\n- `--registry <path>` (or `WORKLEASE_REGISTRY`) — registry file location\n  (default `.worklease/registry.jsonl`).\n- `--json` — emit `{ clear, conflicts }` verbatim.\n- Exit `0` when clear, `1` when any conflict — an advisory signal a pre-edit hook\n  can gate on, not a hard lock.\n\n### `worklease list`\n\nShows the active claims — who holds what, and when each lease expires — resolved\nfrom the append log at read time (latest claim per id, releases applied, and\nTTL-expired claims treated as inactive). One row each, sorted by soonest expiry.\n\n```bash\nworklease list                     # active claims: agent, globs, intent, expiry, id8\nworklease list --all               # also released + expired, labeled\nworklease list --agent me          # only my claims\nworklease list --json              # the resolved claim array, for harnesses\n```\n\n- `--all` — include `released` and `expired` claims, each labeled with its\n  effective status (default shows only `active`).\n- `--agent <id>` — filter to a single holder.\n- `--json` — emit the resolved claim array verbatim (each claim carries its\n  effective `status`).\n- `--registry <path>` (or `WORKLEASE_REGISTRY`) — registry file location.\n- An empty or missing registry prints `no active claims` (`[]` under `--json`)\n  and exits `0`.\n\n### `worklease release <id>`\n\nDrops a claim you're done with by **appending** a release record — it never edits\nor deletes the original claim line, so a concurrent writer can't be lost.\n\n```bash\nworklease release fb964bcd                 # by short id (unambiguous prefix)\nworklease release <full-id> --agent me     # record who released it\nworklease release <id> --json              # print the appended release record\n```\n\n- Resolves the target by full `id` or an **unambiguous** id prefix (the short ids\n  `list` prints work); an ambiguous prefix or an unknown id is an error (exit `1`).\n- `--agent <id>` (or `WORKLEASE_AGENT`) — who is releasing; a release by someone\n  other than the holder is allowed but noted (advisory cleanup across the fleet).\n- Releasing an already-`released` or already-`expired` claim is a **no-op** with a\n  note (still exit `0` — the desired end state already holds).\n- `--registry <path>` (or `WORKLEASE_REGISTRY`) — registry file location.\n\n### `worklease conformance <registry> <merges>`\n\nScores, **after the fact**, whether the fleet actually coordinated. Given the\nregistry and a **merges** file — the concrete files each agent touched — it grades\nevery `(agent, file)` change: did the acting agent hold a claim covering the file,\nand did it edit a file under another agent's live claim?\n\n```bash\nworklease conformance .worklease/registry.jsonl merges.json   # human summary; exit 1 on any violation\nworklease conformance registry.jsonl merges.json --json       # { score, total, respected, violations, warnings }\n```\n\nThe **merges** file is a JSON array (or JSONL, one per line) of merge records\n`{ agent, files: [\"path\", …], at? }`, where `at` is the optional ISO-8601-UTC\ntime the change landed. Each record is flattened to one change per touched file.\n\n- **respected** — the agent held a matching claim for the file *and* it collided\n  with no other agent's live claim. These are the numerator of the score.\n- **violation** — the file fell under a **different** agent's claim active at the\n  change time (temporal `created ≤ at < expires` when `at` is given, else the\n  claim's `status`). One entry per conflicting claim, each with the full\n  `conflicting_claim` record. This is the collision worklease exists to prevent.\n- **warning** — the change was **uncovered** and collided with no one (an edit to\n  an unclaimed file). It lowers the score but is **not** a failure.\n- `score` = `respected / total`, a float in `[0, 1]` (`1` when there are no\n  changes). A fleet that never claims anything scores `0` — the score rewards\n  coverage, not just the absence of collisions.\n- Exit `0` when there are **no violations**, `1` when any violation is found. A\n  low score from warnings alone does **not** fail — the score is advisory, the\n  non-zero exit a hint a CI/merge gate *may* act on.\n- Missing registry or merges files are tolerated as empty inputs; a malformed\n  merges JSON is a clear error (exit `1`).\n\n### `worklease hook install`\n\nInstalls a **git pre-commit hook** that runs `worklease check` on the files a\ncommit is about to change — the dogfood adapter that makes worklease actually\ncatch collisions in a live parallel-agent setup, before the edit lands.\n\n```bash\nworklease hook install            # advisory: prints conflicts, never blocks a commit\nworklease hook install --strict   # strict: a conflict aborts the commit (exit 1)\n```\n\nThe hook is **advisory by default** (roadmap principle #1 — coordinate, don't\nenforce): on a conflict it prints who holds the overlapping globs and lets the\ncommit through. `--strict` makes a conflict fatal so git aborts the commit.\nInstall is **idempotent** and **preserves an existing hook** — it manages only a\nmarked block (`# >>> worklease >>>` … `# <<< worklease <<<`), so re-running it\nnever duplicates the block or clobbers hand-written hook logic. A committed\n[`examples/pre-commit.sample`](examples/pre-commit.sample) shows what it writes.\n\nUnder the hood the hook calls `worklease hook run`, which lists the staged files\n(`git diff --cached --name-only`) and checks them against active claims. Set\n`WORKLEASE_AGENT` in the commit environment so your own claims count as clear.\n\n```bash\nworklease hook run            # what the hook runs: check staged files (exit 0 even on conflict)\nworklease hook run --strict   # exit 1 on conflict, for a blocking hook\nworklease hook run --json     # { clear, conflicts: [...] } for tooling\n```\n\n### The registry\n\nThe store is an **append-only JSONL file** (default `.worklease/registry.jsonl`),\nmeant to be **committed** so it's shareable across worktrees and harnesses. New\nrecords are appended as whole lines; existing lines are never rewritten. Every\nrecord's `id` is a content hash of its own content, so a duplicated append is\nidempotent on read and two agents appending at once union-merge cleanly instead\nof conflicting. A line that fails its integrity check (or won't parse) is skipped\nwith a note — one bad line never discards the rest of the registry.\n\nDogfood target: the author's own parallel-agent software factory + Conductor sessions.\n\nStatus: **drafting** — see [`roadmap.md`](roadmap.md). MIT · zero dependencies · harness-neutral.\n","readmeFilename":"README.md"}