HEDDLE

CLI reference

heddle context

Shipped
heddle context [OPTIONS] <COMMAND>

Attach reasoning to files, symbols, line ranges, and states, with on-demand staleness detection via context check and context audit.

Output text (default)

Context is how Heddle stores the why alongside the code. An annotation targets a file (--path src/auth/mod.rs) or a state (--state hd-d01a8b4e7m9k), and a scope within it: file (the default), symbol:<name>, or lines:<start>-<end>.

Three kinds carry distinct intent: rationale (why this approach), invariant (must always hold), constraint (external requirement). Pass them as the full words; there are no short forms.

Annotations have logical IDs that survive revision. context edit adds a revision, context supersede replaces with a new logical annotation, context history walks the chain. context check and context audit surface stale and superseded notes; context suggest recommends symbols that would benefit from one.

Context does not reach a Git-only collaborator. Annotations and discussions move over heddle push and heddle pull to a Heddle remote and are not projected into Git. Someone who git clones the repository gets the source history and no Heddle store — and heddle context list there reports that no store is present, not that there are no annotations. Those are different answers.

context reason git --path mines local AI-coding-agent transcripts (Claude, Codex, OpenCode) for reasoning and attaches it as annotations to the matching states. It has a --dry-run.

Examples

Attach a rationale to a symbol

bash$ heddle context set --path src/auth/mod.rs --scope symbol:authorize -m "scope check happens before role check by design"

Read what is active on a file

bash$ heddle context get --path src/auth/mod.rs

See also

Subcommands

  • context set Attach a context annotation to a file, symbol, line range, or state
  • context get Show context annotations for a target
  • context list List all active context targets
  • context history Show full revision history for one logical annotation
  • context edit Add a new revision to an existing logical annotation
  • context supersede Create a replacement annotation and supersede an older one
  • context rm Remove context annotations
  • context check Check annotation staleness against current code
  • context suggest Suggest low-noise targets that may benefit from context
  • context audit Audit stale, superseded, and duplicate context
  • context reason git Mine Git-agent transcripts and attach reasoning as context annotations