Module annotations 

Per-step annotations — the first persistent write-back feature.

Notes live outside the session file (agx is read-only with respect to session data, always), in a sidecar JSON under ~/.agx/notes/. Keyed by a FNV-1a hash of the canonical session path so moves-within-the- same-canonical-path keep their notes while renames start fresh (a deliberate trade-off — session UUID extraction varies per format and isn’t available for all of them).

File format (version 1):

{
  "version": 1,
  "path": "/absolute/path/to/session.jsonl",
  "notes": {
    "0": {"text": "...", "created_at_ms": 1704000000000, "updated_at_ms": 1704000000000},
    "5": {...}
  }
}

Key is the 0-based step index as a JSON-string (since JSON objects require string keys). created_at_ms never changes; updated_at_ms refreshes on every edit.

Writes go through a temp-file + rename so a partial write never corrupts an existing notes file. Reads are fault-tolerant: a missing file or a malformed parse yields an empty Annotations so the TUI always has something to render against.

Structs

Annotations

Note

Functions

agx_home_dir

Root directory for agx’s persistent state. AGX_HOME overrides for tests; otherwise ~/.agx. Returns an error when the HOME environment variable is unset (which is very unusual on the platforms we target, but we surface it explicitly rather than silently dropping writes).

annotations_file_for

Resolve the annotations file path for a given session.