> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Session System > NIIA 0.9.50 — recall, index, search, and safely continue work across AI CLI sessions and live PTYs. # 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.50.* ## Supported session families | Family | What NIIA can use | | ----------------- | ------------------------------------------------------------ | | Claude Code | Local structured conversations and assistant text blocks | | Codex | Rollout/session records and explicit answer output | | Grok CLI | Chat history with assistant answers separated from reasoning | | OpenCode | Discoverable local session data | | Gemini CLI | Discoverable local chat data | | agy / Antigravity | Structured planner and agent transcripts | Availability depends on which tools are installed and which local session sources exist on the current machine. ```text theme={null} provider session ── read ───────────────▶ immediate context │ └────────── index ── search ───▶ cross-session recall live PTY ────────── health ── ask ─────▶ interactive continuation ``` ## Discover recent sessions ```bash theme={null} niia recall "current feature" # session hits appear beside memory hits niia recall --list # provider counts and index horizon lag niia session list -n 5 niia session list --tool codex -n 10 ``` `recall` marks local session results with `[L]`. Its inventory reports the gap between discovered and indexed sessions for each provider and how far the index horizon trails. The scheduled session index normally refreshes every 600 seconds; `niia doctor` warns when that lane is no longer keeping up. `session list` is grouped by provider and prints runnable `session read` commands for the discovered identifiers. ## Read one session ```bash theme={null} niia session read latest --tool claude niia session read latest --tool codex --full niia session read --tool grok -n 30 ``` `session read` addresses a provider session directly. It does not require the cross-session search index to be current. ## Index and search across sessions ```bash theme={null} niia index --sessions niia session search "session gateway" niia session search "release boundary" -n 20 ``` `session search` queries the indexed session corpus. Re-run `niia index --sessions` when newly created conversations must become searchable. | Command | Reads | | --------------------- | --------------------------------------------------------------------- | | `niia session read` | One discovered provider session | | `niia session list` | Provider session inventories | | `niia session search` | The explicit cross-provider session index | | `niia search` | The wider NIIA search surface across memory, documents, code, and git | ## 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 ` 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: ```bash theme={null} niia gauge --transcript ./run.jsonl "audit this benchmark run" ``` 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](/niia-cli/commands#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. ```bash theme={null} niia health niia health --session niia ask --session "continue from the previous decision" niia follow-up --session "run the focused test" --expect-last "previous decision" ``` The health report checks whether the session, child process, reader, and daemon relationship are still live enough to drive. ## Screen answer vs provider answer ```text theme={null} rendered terminal screen ── niia get-answer ─────────▶ what the PTY shows provider transcript ─────── niia get-answer-system ─▶ what the CLI recorded ``` Use the rendered screen for ordinary interactive output: ```bash theme={null} niia write --session $'your question\r' niia wait-idle --session niia get-answer --session "your exact question" ``` Use the provider transcript when its structured record is more reliable than stdout: ```bash theme={null} niia get-answer-system --cli codex --transcript niia expect-system --cli claude --transcript "expected text" ``` ## Assertions, not sleeps ```bash theme={null} niia expect-screen --session "Finished" --max-wait 120 --show niia expect-history --session "Finished" --tail 100 --show niia step --session --send "cargo check" --expect "Finished" --read screen niia scenario --session ``` `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: ```bash theme={null} niia write --session $'claude\r' ``` 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](/niia-cli/commands) for flags and the [security model](/niia-cli/security) for the boundaries shared with terminal and remote operations.