kiro-session-index

Locate, outline, index and search Kiro agent session logs. Standard library only, no network access, sessions are opened read-only.

Supports both on-disk formats under ~/.kiro/sessions/:

• directory format (Kiro IDE / Kiro CLI --agent-engine=v3): session.json + messages.jsonl + sub-executions/
• three-file format (Kiro CLI default engine): cli/<id>.json + <id>.jsonl + <id>.lock

Usage

uvx kiro-session-index locate <session-id> [--children]
uvx kiro-session-index outline <session-id> [--json]
uvx kiro-session-index list [--workspace <path>] [--since-days N]
uvx kiro-session-index build --session <session-id> [--include-sub]
uvx kiro-session-index build --workspace <path> [--since-days N]   # all sessions of a workspace
uvx kiro-session-index build <files-or-dirs...>                    # index a codebase
uvx kiro-session-index search "query" --index <dir> [--top N]
uvx kiro-session-index clean --index <dir>                         # always clean up

• locate resolves an id (with or without sess_ prefix, prefix match allowed) or a path, detects the format, and prints metadata, lock liveness, and derived sessions.
• outline segments a transcript into turns with start/end line numbers, per-turn tool usage, credits, sub-agent dispatches, and compaction/tombstone markers.
• list shows storage areas, or every session of a workspace (dir-format workspacePaths plus cli-format cwd) with sizes and titles.
• build creates a disposable TF-IDF index (ASCII words + CJK bigrams) as SQLite under .tmp/session-index/<name>/ in the current directory. --workspace indexes every session of a workspace incrementally: per-session shards skip unchanged sessions, duplicate copies across buckets are deduplicated (newest wins), and a fully fresh index returns in about a second. Measured worst case: 914 sessions / 640 MB → 72 s cold, ~0.2 s per query.
• search ranks chunks by cosine similarity, reading only the postings of the query terms; every hit carries file:lineStart-lineEnd so the caller can read exactly the lines it needs.
• clean removes an index directory, refusing to delete anything it did not create.

Indexes are temporary artifacts. Delete them with clean when the task is done.

Part of kiro-steering-agents; built to back a session-loader sub agent that reads big sessions in an isolated context.