Projectv0.2.2

Tether

Tether keeps each code explanation on the code it explains.

Write the explanation where the code is, as a comment on a function or a file beside a file or folder. When the code changes and the explanation doesn't, Tether reports it, and committing the code doesn't clear the report.

npm install -g @skastr0/tether

View source See it run

The pain

The doc is stale, and the agent trusts it. docs/architecture.md was right a month ago. The agent answers from it anyway.
You spend the session correcting it. You type "ignore the docs, read the code", and the agent rebuilds what the doc was meant to save.
Nothing tells you which notes went stale. A doc that lives apart from the code can drift for weeks, and nobody notices.

See it run

An agent patches a function in place and adds an architecture doc.

$ tether lint '{"root":"."}'{ "facts": [    { "kind": "rogue_document",           "path": "docs/architecture.md" },    { "kind": "host_fingerprint_changed", "path": "src.tether" },    { "kind": "host_fingerprint_changed", "path": "src/session.ts" } ],  "failed": true }exit 1

Committing the change doesn't clear the report. Updating the explanation does.

$ git commit -qam "patch session in place"; tether lint '{"root":"."}'host_fingerprint_changed src.tetherhost_fingerprint_changed src/session.ts # edit the @tether comment to describe the new behavior, commit$ tether lint '{"root":"."}'host_fingerprint_changed src.tether   # the folder's note still needs its own updatefailed False

What an agent reads before it edits.

$ tether get '{"root":".","path":"src/session.ts","symbol":"refreshSession","context":true}'{ "layers": [    { "host": { "kind": "symbol", "path": "src/session.ts", "name": "refreshSession" },      "tethers": [ { "doc": "Refresh renames the session row. Never patch it in place: …" } ] },    { "host": { "kind": "folder", "path": "src" },      "tethers": [ { "path": "src.tether", "doc": "Sessions live in src/session.ts. …" } ] } ],  "facts": [ { "kind": "host_fingerprint_changed", "path": "src/session.ts" }, … ] }exit 0

How it works

Each explanation is bound to the code under it and fingerprinted from the syntax tree, so a reformat leaves it alone and a rename or logic change does not. tether lint compares the fingerprint from the commit where the explanation last changed with the fingerprint now. rogue_document means a standalone doc outside the allowlist; host_fingerprint_changed means the code changed after its explanation did. Everything Tether generates lives under ~/.config/tether/, never in your repo.

where you write it	what it explains
a `@tether` comment above a declaration	that function, type, or method
`foo.ts.tether` beside `foo.ts`	that file
`src.tether` beside `src/`	that folder
`root.tether` at the repo root	the whole repo

Where it fits

When several agents work on one codebase, Tether holds the notes one agent leaves on the code for the next, and says when a note has gone stale.

Install

Version: 0.2.2
Runs on: macOS and Linux (glibc), arm64 and x64
Install: npm install -g @skastr0/tetherNeeds Node 22.14+ and Git.
Source: github.com/skastr0/tether

View source npm

Other projects

projectJuntoJunto puts coding agents on one canvas and lets them talk.projectPrismWrite agent workflows as programs. Run them anywhere. Run them again.projectQuartzQuartz answers an agent's TypeScript questions with the compiler's own answers.projectPulsarPulsar scores a repository and each agent diff under one shared policy.