kiro-session

Interactive session manager for Kiro CLI — browse, search, resume by topic, save/restore, and manage your chat sessions.

📺 Showcase — see it in action

Why

Kiro CLI's built-in session management shows only session IDs and one-line summaries, scoped to the current directory. When you have dozens of sessions across multiple projects, it's hard to find what you need.

kiro-session solves this with:

• Cross-directory browsing — see all sessions from all projects in one place
• Hybrid search — keyword (FTS5) + semantic (embedding) search with RRF ranking
• Topic splitting — LLM groups turns by meaning, resume just the topic you need
• Private sessions — incognito mode that auto-deletes local data on exit
• Dual storage support — reads both SQLite (v1) and JSON/JSONL (v2) kiro-cli sessions

Install

git clone <repo> && cd kiro-session
./install.sh

The installer creates a Python venv, installs dependencies (simple-term-menu, orjson, pyyaml, jieba, fastembed, numpy, prompt_toolkit), and symlinks kiro-session to ~/.local/bin/.

Requirements

• Python 3.10+
• Kiro CLI installed and configured

Quick Start

kiro-session                          # interactive browser (default)
kiro-session list --plain             # non-interactive list
kiro-session search "docker"          # hybrid search (keyword + semantic)
kiro-session list --dir temp          # filter by directory
kiro-session list --recent 7d         # filter by recency
kiro-session list --file "main.py"    # filter by file touched
kiro-session private                  # start a private session

Commands

Command	Description
kiro-session	Interactive session browser
kiro-session list [options]	List/filter sessions
kiro-session search <query>	Hybrid search (keyword + semantic) across all sessions
kiro-session enrich [--rebuild]	Build/refresh LLM index (alias: index)
kiro-session save <id> [path]	Export session to JSON
kiro-session restore <path>	Import session from JSON
kiro-session export <id> [--dir path]	Export session to Markdown
kiro-session resume <id> [--topic N]	Resume session (or topic) directly
kiro-session delete <id>	Delete session from kiro DB
kiro-session delete-topic <id> --topic N	Delete a specific topic
kiro-session tag <id> [tags]	Add/remove user tags
kiro-session rename <id> "name"	Rename session
kiro-session context <id> [--topic N]	Generate context summary for cross-session reference
kiro-session cleanup	Review cleanup suggestions
kiro-session redact <id> --turn N	Remove a turn from index
kiro-session config [key] [value]	View/set configuration
kiro-session private [-a]	Start private session (auto-deleted on exit)

list options

Flag	Description
--dir, -d	Filter by directory basename or path
--recent, -r	Filter by recency (e.g. 7d, 24h)
--file	Filter by file touched in session
--cmd	Filter by command run in session
--plain	Non-interactive output
--json	JSON output
<session-id>	Show detail for specific session

Keyboard Navigation

Key	Action
↑ / ↓	Move selection
Page Up / Page Down	Scroll by page
Ctrl-A / Ctrl-E	Jump to top / bottom
/	Quick text filter (in current list)
s	Semantic search (hybrid: keyword + embedding)
Enter	Select
Esc / q	Back / quit (clears search if active)

Session Detail & Actions

Select a session to see its detail page:

============================================================
Session: API Gateway Migration Plan
ID:      612381ac
Dir:     /home/user/docs
Updated: 4d ago
Turns:   58 prompts
Tags:    [api] [migration] [nodejs]

Topics (3):
  1. REST API endpoint refactoring
  2. Auth middleware integration
  3. Load testing and optimization
============================================================

  [r] Resume full session
  [1-3] Resume by topic
  [t] Edit tags
  [n] Rename
  [v] Save    [d] Delete
  [f] Feedback (re-analyze topics)
  [e] Enrich
  [Esc] Back    [q] Quit

• Resume full — uses kiro-cli's native --resume-picker to resume the original session in-place (TUI supported)
• Resume by topic — cherry-picks turns for that topic, writes to kiro DB, then resumes via --resume-picker
• Feedback — provide feedback on topic grouping, LLM re-analyzes with your guidance
• Enrich — runs LLM enrichment for better names, topics, and tags (~5s)
• Sessions without LLM index are marked ⏳ in the list
• Sessions with stale index (new content since last enrich) are marked 🔄 and can be re-indexed manually

Private Sessions

Start a private/incognito session that is automatically deleted when you exit:

kiro-session private          # start private session
kiro-session private -a       # with all tools trusted

• Runs kiro-cli in a sandboxed directory
• On normal exit: session is immediately deleted from all local storage
• On abnormal exit (window close): cleaned up on next kiro-session invocation

Note: This only deletes local session data. Content sent to the LLM provider during the session may still be retained server-side per the provider's data policies.

Privacy

# Exclude a directory — purges existing sessions and auto-deletes future ones
kiro-session config privacy.exclude_dirs /path/to/sensitive/project

# Purge entire index
kiro-session config privacy.purge

# Redact a specific turn
kiro-session redact abc12345 --turn 3

How It Works

Architecture

Layer 0: Extractor (read-only scan of kiro DB + JSONL files)
Layer 1: LLM Enrichment (names, topics, tags via kiro-cli headless)
Layer 1b: Embeddings (bge-small-zh per-turn vectors for semantic search)
Layer 2: Search (FTS5 keyword + embedding semantic, RRF merge)
Layer 3: UI (simple-term-menu interactive browser + CLI output)

Dual Storage

kiro-cli stores sessions in two backends:

• v1 (SQLite): ~/.local/share/kiro-cli/data.sqlite3
• v2 (JSON/JSONL): ~/.kiro/sessions/cli/*.json + *.jsonl

kiro-session reads both and converts them to a unified ConversationState format. The index is stored at ~/.kiro/session-index.db.

Indexing

• Layer 0 runs automatically on every command (<100ms incremental)
• LLM enrichment generates better names, topic summaries, and semantic tags
• Single-call analysis for most sessions; chunked multi-turn fallback for very large ones (>80k chars)
• Auto-enrichment runs in background on every startup when unindexed sessions exist
• Can also be triggered manually: kiro-session index or [i] in session detail

Resume

Resume uses kiro-cli's native --resume-picker flag. kiro-session automatically selects the target session in the picker via PTY automation:

1. Full resume — touches the session's updated_at in kiro DB so it sorts first, then launches --resume-picker which auto-selects it. The original session is resumed in-place — no new session is created.
2. Topic resume — generates a ConversationState JSON with cherry-picked turns, writes it to kiro DB as a new session, then launches --resume-picker to select it.

Both modes support TUI (kiro-session config resume.ui tui).

Testing

python3 tests/test_pty.py    # PTY-based integration tests

Tests include:

• list --plain output validation
• Resume JSON structure verification (ConversationState format)
• PTY-based /chat load acceptance test
• Topic resume file generation
• Save / export / search functionality

Configuration

kiro-session config                        # show all
kiro-session config llm.provider           # get value
kiro-session config llm.provider ollama    # set value

Key	Default	Description
llm.provider	auto	LLM provider: auto, kiro, ollama
llm.auto_enrich	true	Auto-enrich on detail view
resume.ui	``	Resume UI mode: tui, legacy, or empty (auto)
privacy.exclude_dirs	[]	Directories to exclude and purge
privacy.exclude_sessions	[]	Session IDs to exclude

License

MIT