Metadata-Version: 2.5
Name: kiro-session-index
Version: 0.2.0
Summary: Locate, outline, and build disposable TF-IDF search indexes over Kiro agent session logs (IDE directory format and CLI three-file format).
License: MIT
Keywords: agent,kiro,logs,search,session,tf-idf
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# kiro-session-index

Locate, outline, index and search [Kiro](https://kiro.dev) 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

```bash
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](https://github.com/fanjie/kiro-steering-agents); built to back a session-loader sub agent that reads big sessions in an isolated context.
