Skip to main content

​
AI Session System

NIIA reads the durable session formats produced by AI coding CLIs and presents them through one local command surface. The provider remains the owner of its transcript; NIIA provides discovery, indexing, search, and continuation. Documents NIIA 0.9.41.

​
Supported session families

Availability depends on which tools are installed and which local session sources exist on the current machine.

​
Discover recent sessions

The list is grouped by provider and prints runnable session read commands for the discovered identifiers.

​
Read one session

session read addresses a provider session directly. It does not require the cross-session search index to be current.

​
Index and search across sessions

session search queries the indexed session corpus. Re-run niia index --sessions when newly created conversations must become searchable.

​
Entry witness vs provider transcript

The self-drive witness and the session corpus are different evidence surfaces. niia gauge records the rung, signals, [NEXT] promise, provider brand, and transcript path supplied by the hook in gauge.json; it does not copy the transcript into the witness. niia finish adds finish.json, and niia audit-entry writes audit-report.json beside it. The pointer and the witness are also separate. Only a hook-carried session id may move the repository’s atomic current pointer. A benchmark that uses --session <id> can update its own witness without redirecting a later bare niia finish away from the live interactive session. For an ad-hoc or benchmark run that has no hook event, pass the transcript before the trailing task text:
This stores the path in the witness so audit-entry can inspect it. It does not import the provider transcript into the NIIA session corpus. The current audit reader understands Claude JSONL and ad-hoc transcript paths. A Codex hook can still create and carry the gauge witness, but transcript-level Codex audit is returned as SUSPENDED until a Codex reader ships. A suspended audit is neither a pass nor a violation. It also does not fall back to the cross-provider session search index and pretend that indexed snippets prove event order. See work-entry self-drive for the promise-derived audit classes and witness storage paths.

​
Continue in a real terminal

Session memory and PTY control are separate layers. A historical transcript can be readable even when the original process is gone; a visible terminal can be stale even when its last frame still looks valid.
The health report checks whether the session, child process, reader, and daemon relationship are still live enough to drive.

​
Screen answer vs provider answer

Use the rendered screen for ordinary interactive output:
Use the provider transcript when its structured record is more reliable than stdout:

​
Assertions, not sleeps

expect-*, step, and scenario turn missing output, failed guards, and timeouts into non-zero exits. This makes terminal automation an assertable workflow instead of a sequence of arbitrary sleeps.

​
Raw-mode Enter

Interactive terminal applications commonly expect carriage return:
Use \r for Enter. A plain newline may not submit input in a raw-mode application.

​
Privacy boundary

  • Session parsing is local-first and does not require proxying a model API.
  • Each provider owns its own credentials and subscription.
  • Remote recall or synchronization is explicit; local session discovery alone does not publish a transcript.
  • A transcript being readable does not authorize OS control, remote execution, or MCP access.
See the complete command map for flags and the security model for the boundaries shared with terminal and remote operations.