A .handoff file (kind handoff, versions 1 and 2, MIME application/x-handoff) carries what another chat needs to continue a job: a paste block plus the files it must open. The type is declared in handoff.kind and is not an OS MIME registration.
| File | Content |
|---|---|
language.md |
the language spec, source of truth |
handoff.kind |
spec: structure, parse rules, write rules |
sample.handoff |
v2 example that continues Lumen from lumen.py |
parse_handoff.py |
standard-library Python validator and summary printer |
handoff-README.md |
short description |
- Line 1 is
# handoff v1or# handoff v2. - A
---fenced block withmission,continue_from, andstop_rule(required), andrepo(http(s) URL) andcommit(7-40 hex git SHA) (optional in v1, required in v2;commitneedsrepo). FILES(one path per line),PASTE(verbatim text), andRULES(KEY: value).
A handoff with an empty FILES or PASTE section is invalid.
python3 parse_handoff.py sample.handoff
It prints the mission, continue_from, stop_rule, the file list, the paste length, and the rule count. If the file is invalid it prints INVALID: <reason> to stderr and exits with code 1. With no argument it reads sample.handoff.
Reject the file unless line 1 is # handoff v1 or # handoff v2. Open every path under FILES, at commit in repo when set, before writing anything, and treat PASTE as the exact instruction. Do not claim the job continued unless the stop_rule test passed.
Copyright (c) 2026 Joshua Almeida. Released under the MIT License, see LICENSE.