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 four Kiro CLI storage versions (CLI 1.x SQLite, CLI 2.x SQLite, CLI 2.x classic-mode JSONL, CLI 3.0), covering both --classic and TUI modes across versions

Read-only

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

• ~/.kiro/sessions/<workspace-hash>/sess_*/ (CLI 3.0 sessions)
• ~/.kiro/sessions/cli/ (CLI 2.x classic-mode 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

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:

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 four formats depending on the version and mode:

kiro-cli-history reads all four 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 (CLI 2.x and CLI 3.0 sessions only — 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.

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