kiro-cli-history 0.3.0

A terminal UI for fuzzy-searching, browsing, and resuming Kiro CLI conversations

kiro-cli-history

A terminal UI for fuzzy-searching, browsing, and resuming Kiro CLI conversations.

The problem

Kiro CLI has great built-in conversation persistence — it saves your sessions and lets you resume them with --resume and --resume-picker. However, these are scoped to the directory where the session was started. If you work across many projects and directories, finding a specific past conversation means remembering which folder you were in at the time.

kiro-cli-history complements Kiro CLI's native persistence by adding global fuzzy search across all sessions — regardless of which directory they were started in. It searches the full content of every message exchanged, not just session titles.

What it offers

• Global search — find conversations across all directories, not just the current one
• Full-text fuzzy search — searches every message you and Kiro exchanged, not just titles
• Conversation preview — read through the full exchange with markdown rendering before deciding to resume
• One-key resume — press Ctrl+R to jump into Kiro CLI and continue the conversation
• Copy to clipboard — press Ctrl+Y to copy an entire conversation
• All session formats — reads all three Kiro CLI storage versions (v1 SQLite, v2 SQLite, v3 JSONL), covering both --classic and new TUI modes

Read-only

This tool never writes to or modifies your Kiro CLI session data. It only reads from:

• ~/.kiro/sessions/cli/ (JSONL sessions)
• The Kiro CLI SQLite database (data.sqlite3), opened in read-only mode — located at ~/Library/Application Support/kiro-cli/ on macOS, ~/.local/share/kiro-cli/ on Linux, or %APPDATA%\kiro-cli\ on Windows

Install

Requires at least Python 3.10.

With pipx:

pipx install kiro-cli-history

With uv:

uv tool install kiro-cli-history

With pip:

pip3 install kiro-cli-history

Usage

kiro-cli-history

Run it from anywhere. It searches globally.

Keyboard shortcuts

Key	Action
/	Focus search bar
j / k or arrows	Navigate sessions
Ctrl+R	Resume the highlighted session in Kiro CLI
Ctrl+Y	Copy conversation to clipboard
Ctrl+F	Focus search bar
Esc	Clear search / Quit
Ctrl+C	Quit

Searching

Type in the search bar to fuzzy-search across:

• Session titles
• Working directories
• Full conversation content (every message exchanged)

Search is case-insensitive and covers all session formats.

Text selection

Hold Option (Alt) while dragging to select text from the preview pane. Or press Ctrl+Y to copy the full conversation to clipboard.

Configuration

Settings are stored in a JSON file managed via the config subcommand — no need to edit it by hand.

kiro-cli-history config show          # print all settings and the config file path
kiro-cli-history config get scroll_top
kiro-cli-history config set scroll_top true

Available settings:

Key	Default	Description
scroll_top	false	Show the start of a conversation in the preview pane instead of jumping to the most recent messages

The config file lives at the platform's standard config location (e.g. ~/Library/Application Support/kiro-cli-history/config.json on macOS).

How it works

Kiro CLI stores conversations in three formats depending on the version and mode:

Format	Location	Used by
v3 (JSONL)	~/.kiro/sessions/cli/*.json + *.jsonl	kiro-cli --classic
v2 (SQLite)	Platform data dir (~/Library/Application Support/kiro-cli/ on macOS, ~/.local/share/kiro-cli/ on Linux, %APPDATA%\kiro-cli\ on Windows), data.sqlite3	New TUI mode (kiro-cli)
v1 (SQLite)	Same database, conversations table	Legacy

kiro-cli-history reads all three and presents them in a unified view. Each session shows:

• Title — first message or auto-generated title
• Directory — where the session was started
• Date — last activity (e.g., "7 Apr 2026")
• Message count — total exchanges
• Duration — elapsed time
• Credit usage — total credits spent on the session (JSONL/v3 sessions only — older SQLite sessions don't record this)

How this complements Kiro CLI

Kiro CLI's native --resume and --resume-picker work well when you know which directory a session was started in. kiro-cli-history is a companion tool for when you need to find a conversation but don't remember where it happened — it gives you a global view with full-text search.

	--resume-picker (native)	kiro-cli-history
Scope	Current directory	All directories
Search	Browse by title	Full-text across all messages
Preview	Title + message count	Full conversation with markdown

Platform

Session discovery and clipboard support now work across macOS, Linux, and Windows:

• Session storage — resolved via the same platform-specific data directory convention Kiro CLI itself uses (~/Library/Application Support/, ~/.local/share/, or %APPDATA%)
• Clipboard — tries pbcopy (macOS), clip (Windows), then wl-copy, xclip, or xsel (Linux, Wayland/X11)

This has been tested on macOS. Linux and Windows support is implemented but not yet verified in practice — bug reports and PRs are welcome if something doesn't work as expected.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development setup and quality checks. Commits to the default branch follow Conventional Commits, and releases are automated with release-please — see CHANGELOG.md for the release history.

Credits

Inspired by raine/claude-history — an excellent fuzzy-search tool for Claude Code conversations. If you use Claude Code, check that out.

Forked from prabhu-g/kiro-cli-history — thanks to Prabhu for the initial implementation!

License

MIT