Metadata-Version: 2.4
Name: kiro-cli-history
Version: 0.2.0
Summary: A terminal UI for fuzzy-searching, browsing, and resuming Kiro CLI conversations
Keywords: kiro,kiro-cli,tui,history
Author: Prabhu G
License-Expression: MIT
License-File: LICENSE
License-File: LICENSES/CC0-1.0.txt
License-File: LICENSES/MIT.txt
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: textual>=0.60.0,<7
Requires-Dist: rich>=13.7.0,<15
Requires-Dist: platformdirs>=4.0.0,<5
Requires-Python: >=3.10, <4
Project-URL: Repository, https://github.com/mxmehl/kiro-cli-history
Project-URL: Changelog, https://github.com/mxmehl/kiro-cli-history/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

<!--
SPDX-License-Identifier: MIT
SPDX-FileCopyrightText: 2026 Prabhu G <gangprab@amazon.com>
SPDX-FileCopyrightText: 2026 Max Mehl <https://mehl.mx>
-->

# kiro-cli-history

![kiro-cli-history demo](/meta/demo.gif)

A terminal UI for fuzzy-searching, browsing, and resuming [Kiro CLI](https://kiro.dev/docs/cli/) conversations.

## The problem

Kiro CLI has great built-in [conversation persistence](https://kiro.dev/docs/cli/chat/#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)
- `~/Library/Application Support/kiro-cli/data.sqlite3` (SQLite sessions, opened in read-only mode)

## Install

Requires at least Python 3.10.

With [pipx](https://pipx.pypa.io/):

```bash
pipx install kiro-cli-history
```

With [uv](https://docs.astral.sh/uv/):

```bash
uv tool install kiro-cli-history
```

With pip:

```bash
pip3 install kiro-cli-history
```

## Usage

```bash
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.

```bash
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) | `~/Library/Application Support/kiro-cli/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

Currently mainly macOS (uses `pbcopy` for clipboard, macOS-specific paths).

Community PRs for Linux/Windows support are welcome.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and quality checks. Commits to the default branch follow [Conventional Commits](https://www.conventionalcommits.org/), and releases are automated with [release-please](https://github.com/googleapis/release-please) — see [CHANGELOG.md](CHANGELOG.md) for the release history.

## Credits

Inspired by [raine/claude-history](https://github.com/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](https://github.com/prabhugr/kiro-cli-history) — thanks to Prabhu for the initial implementation!

## License

MIT
