Metadata-Version: 2.4
Name: gora-cli
Version: 0.1.4
Summary: Local CLI chat history index for Codex, Claude Code, and Pi.
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.13
Description-Content-Type: text/markdown

<p align="center">
  <img src="images/gora-header.png" alt="Gora header" width="100%">
</p>

# gora

Local memory for coding-agent chats.

`gora` indexes chat history from Codex, Claude Code, and Pi into one local
SQLite archive. Use it when you need to remember what you asked a model, what a
coding agent changed, which repo a conversation belonged to, or which harness
and model were used.

## Why

Coding-agent history is spread across different local folders. Some harnesses
also prune or rewrite old logs. `gora` gives you one place to search them.

Common uses:

- Find an old debugging session by keyword.
- Check what a coding agent did in a repo last week.
- Recover a command, error, plan, or explanation from a past chat.
- See tool calls and command output inline with the chat transcript.
- Search across Codex, Claude Code, and Pi at the same time.
- Filter history by harness, repo, role, or model.

## Supported History

`gora` reads local history files from:

```text
Codex       ~/.codex/sessions/**/*.jsonl
Claude Code ~/.claude/projects/**/*.jsonl
Pi          ~/.pi/agent/sessions/**/*.jsonl
```

No cloud service is required. The index stays on your machine.

## Install

```bash
uv tool install gora-cli
gora
```

The PyPI package is `gora-cli`. The installed command is `gora`.

Install directly from GitHub:

```bash
uv tool install git+https://github.com/mertdeveci5/gora
```

For local development:

```bash
git clone <repo-url>
cd gora
uv tool install --editable .
```

## Quick Start

1. Check what Gora can see:

```bash
gora doctor
```

2. Import local history:

```bash
gora import
```

3. Open the terminal UI:

```bash
gora
```

4. Search from the CLI:

```bash
gora search "render deploy"
gora search "ctx7 login" --provider codex
gora search "database migration" --model "model-from-gora-models"
```

5. Show a full transcript:

```bash
gora show codex:<session-id>
```

## Terminal UI

Run:

```bash
gora
```

The interactive UI is a Bubble Tea app built with Bubbles components. Gora
builds a cached local helper from the bundled Go source on first launch when Go
is available. For a prebuilt local helper:

```bash
go -C gora/go_tui build -o ../../dist/gora-tui .
GORA_TUI_BIN=dist/gora-tui gora
```

Live search starts after two characters and updates as you type.

Controls:

```text
Type             search chats
Tab              move focus between search, filters, and results
Ctrl-F           open the filter editor
Enter            open the selected chat or edit focused filters
Click Filters    open the filter editor
Space            select or clear a filter option in the filter editor
1/H 2/R 3/M 4/O jump between filter editor steps
Enter            select a filter option and move to the next filter step
Up/Down          move through results or filter options
M                export the selected chat as Markdown from results/transcript
T                export the selected chat as plain text from results/transcript
Left/Esc         return from transcript or apply filters and go back
Ctrl-U           clear search or all filters in the filter editor
Esc              clear search, clear active filters, or quit
```

The filter editor supports multi-select harnesses, repos, and models. For
example, select Claude Code and two repos to show only Claude Code sessions from
those repos.

Exports are written to `~/Downloads/gora-exports` and keep the transcript in a
portable Markdown or plain-text file.

## CLI Commands

```bash
gora doctor
gora import
gora harnesses
gora repos
gora models
gora recent
gora list --limit 20
gora search "query"
gora show <session>
```

Filters:

```bash
gora list --provider codex
gora list --cwd tlmc
gora list --model "model-from-gora-models"
gora list --include-children
gora search "auth bug" --provider claude --model "model-from-gora-models"
gora search "review output" --include-children
gora show <session> --role user --role assistant
```

Most list-style commands print numbered results and a quick command for the top
result.

Example:

```bash
gora models
```

```text
1. Model: gpt-5.4
   Provider: openai
   Chats: 460
   Messages: 43079

2. Model: gpt-5.3-codex
   Provider: openai
   Chats: 333
   Messages: 14585

Quick command:
  gora search "<query>" --model gpt-5.4
```

Useful one-shot commands:

```bash
gora harnesses
gora repos --limit 10
gora models --limit 10
gora recent --provider codex --limit 5
gora search "migration bug" --cwd tlmc
gora search "auth bug" --model "model-from-gora-models"
gora show claude:<session-id>
```

## Import Behavior

`gora import` is archive-oriented.

Once a chat is imported, Gora keeps it searchable even if the original harness
later deletes, prunes, or rewrites its local log file. Refreshing a changed
source file merges in new messages but does not delete messages already in the
archive.

Tool calls and tool-result output are imported by default so transcripts show
what the agent actually ran. Gora redacts common token shapes before storing
message text.

Codex can create child rollout files for subagents and review tasks. Gora stores
those records with their parent thread metadata, but normal list, recent, repos,
search, and TUI views show root user chats by default. Use `--include-children`
on CLI list and search style commands when you want to inspect child rollout
records too.

## Models

Gora does not use a fixed model-name list.

It extracts model metadata from each harness's logged structure:

```text
Codex        turn context model metadata
Claude Code  assistant message model metadata
Pi           model change records and message metadata
```

List indexed models:

```bash
gora models
```

Filter by an indexed model:

```bash
gora search "cache bug" --model gpt-5.5
```

## Data Location

Default index path:

```text
macOS  ~/Library/Application Support/gora/history.sqlite
Linux  ~/.local/share/gora/history.sqlite
```

Use another path:

```bash
GORA_DB=/path/to/history.sqlite gora import
gora --db /path/to/history.sqlite search "query"
```

The default data directory is created with owner-only permissions.

## Development

```bash
uv run python -m unittest
uv run python -m compileall gora tests main.py
uv build
```
