Command reference

Every executable in this repository. Each one is a standalone Node script with zero dependencies; there is no build step and nothing to install to run them from a checkout.

Requires Node.js 18 or newer.

tools/handoff.mjs — capture engine

Reads a transcript and writes a handoff directory. The source is never written; every output file is a render of it. The folder layout, the manifest fields and the provenance chain are in FORMAT.md.

build flags

build is incremental. It appends the turns with seq above the manifest’s watermark, sets the watermark to the highest seq seen, and increments revisions. timeline.jsonl is append-only; the renders are rewritten. A rebuild with no new turns and an unchanged source hash writes nothing and prints handoff: up-to-date.

Exit codes

tools/agents-handoff.mjs — runtime layer

Acts on the state of the store rather than being invoked per file. Every mutating command takes a lock in <root>/.locks/, so two runs cannot capture or merge the same session at once. Behaviour per command is described in LEVEL4.md.

tools/agent-handoff.mjs is a forwarder, not a second implementation: it spawns tools/agents-handoff.mjs, passes every argument through, and exits with the same code. Its stdout and stderr are the runtime’s own. Use the new path in anything you write today; the old one exists only so a command that already names it does not break.

auto flags: --source (required), --session, --harness, --project, --min-fresh-ms. dispatch flags: --task (required), --role (default implementation-agent), --parent (default handoff:<id>), --broker <root>, --live.

verify-gate reports a rejection twice: ok: false and verdict: "REJECTED" in the JSON, and exit 6. A gate that failed is not a success, so a caller that only reads the exit code still fails closed. promote runs the same gate and refuses (exit 6) when it is rejected — pass --force to override deliberately, which is recorded in the manifest as promoted_gate: "FORCED" rather than "VERIFIED".

Exit codes

tools/runtime-engine.mjs — bounded execution

Evaluates every operation against permission-policy.json before it runs, and records the decision whether it was allowed, refused or failed. Levels, risk classes and grants are in PERMISSIONS.md.

Verdicts are ALLOWED, DENIED and NEEDS_AUTH. A denied or personal-data target is refused at any risk class and is never executed.

tools/capability-registry.mjs — capability probes

Runs a real probe per declared capability and reports what it observed. An unknown probe kind, a probe error and an unreadable target are reported as unknown or unhealthy with the evidence — never interpreted into a passing verdict.

Probe kinds: file-exists, dir-writable, command (with command and args; the token <node> means the running node binary).

State is written to <state>/capability-state.json, where <state> is AGENT_HANDOFF_STATE_DIR or .agents-handoff/.

install/install.mjs — installer

Published as agents-handoff. Location resolution is documented in INSTALL.md.

A bare verb and its flag form are the same command: npx agents-handoff update and npx agents-handoff --update behave identically.

Harness targets. With no harness flag the installer keeps its historical single target (--location / --path); any of these switches to named targets, and several may be combined in one run — each target gets its own copy and its own install record.

update and verify with no harness flag

A machine can hold the same skill in several places at once — ~/.claude/skills for Claude Code, ~/.agents/skills for a neutral store, an account-skill store a desktop client reads. With no harness flag, update and verify act on every installation they can find rather than on the single target the resolver happens to pick, because updating only the resolved one is how a second harness keeps an old engine without anyone noticing.

The search covers the resolved global root, ./local/skills, ./skills, ~/.claude/skills, ~/.codex/skills, ~/.agents/skills, each harness’s per-repository form, and every account-skill root discovered under the platform’s application-data directories. update reports one line per installation, with the version before and after; verify fails the run when any copy fails. Neither touches a store, handoff.config.json or any file the install manifest does not name.

Exit codes

The install record

Every install writes .agents-handoff-install.json into the copy it just made. FORMAT.md lists the fields and PROVENANCE.md states what the record does and does not prove.

What verify compares

For each installation: that every manifest file exists (a path the version never had is reported as not part of that version rather than failed), that SKILL.md carries a name and a version, that the engine actually runs — tools/handoff.mjs config must exit 0 with its resolved-root marker, which also proves the import graph resolves — and that a recomputed files_sha256 equals the recorded one. An installation made before this record existed is reported as having none, never silently passed.

What verify-package checks, and in what order

Each step makes the next one meaningful:

1. The registry’s own hashes. The tarball is downloaded for the installed version and must match the integrity (sha512) and shasum (sha1) the registry declares for it; otherwise “the published package” is just whatever the network handed over.
2. Per-file identity. The manifest is compared file by file against the extracted tarball, and every difference is named (not installed, not in the published package, or content differs).
3. The recorded hash. When the install record already holds a package sha256, it must match too.

Without --record nothing is written; with it, the fetched sha256, sha512, integrity and shasum are stored in package. A version that is not on the registry cannot pass this check, and it says so rather than reporting success.

What remove deletes

remove deletes what the install manifest owns, plus the record it wrote itself and the private package.json stub it created — and nothing else. Store directories, notes, a handoff.config.json, and any file a later version treats as user data survive by default, and every entry that was left is printed under Kept — not the installer's to delete:.

Environment variables

Files written

self-improve writes inside the skill directory on purpose: the candidate file describes the skill’s brief rules, so a configured store never collects rule candidates.