Metadata-Version: 2.1
Name: codex-claude-history-viewer
Version: 0.1.0
Summary: Local-first web viewer for Codex CLI and Claude Code session logs
Author: wangpeng
License: MIT License
        
        Copyright (c) 2026 wangpeng
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Keywords: codex,claude-code,agent,transcripts,jsonl,sqlite,local-first,history,viewer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# Codex & Claude History Viewer

Local-first, dependency-free web viewer for **Codex CLI** and **Claude Code** session logs.

- Browse sessions and projects (work dirs)
- Search sessions by keyword + date range
- Filter messages by role, and search within a session (highlight + next/prev)
- Sort sidebar by **start time** or **last activity**
- Highlight interruptions and common error outputs

> Not affiliated with OpenAI or Anthropic. “Codex” and “Claude” are trademarks of their respective owners.

![Codex UI screenshot](docs/codex.png)

<details>
<summary>More screenshots</summary>

![Claude Code UI screenshot](docs/claudecode.png)

</details>

## Why

Codex CLI and Claude Code both generate local, machine-readable transcripts (JSONL). This project turns those logs into a fast, searchable “history inbox” you can use to:

- find past commands/patches/discussions quickly
- audit tool failures and interruptions
- compare sessions across days/projects
- keep everything **local** (no uploads by default)

## Quick start

Requirements:

- Python 3.8+ (standard library only)
- A modern browser

Run:

```bash
python3 app.py
```

or install and use the global CLI:

```bash
CCHV install
CCHV serve
```

Open:

- http://127.0.0.1:8787

By default it reads:

- Codex logs: `~/.codex/sessions`
- Claude logs: `~/.claude/projects`

Indexes (SQLite) are stored by default in `~/.cache/cchv` (or `$XDG_CACHE_HOME/cchv`) unless you set `--data-dir`.

## Configuration

Show all options:

```bash
python3 app.py --help
```

`CCHV` subcommands:

```bash
CCHV --help
CCHV serve --help
CCHV demo --help
CCHV install
```

## Demo data (included)

This repo includes a small set of **synthetic** Codex/Claude logs under `demo/` so you can try the UI without using your own transcripts.

```bash
python3 app.py \
  --codex-dir ./demo/codex \
  --claude-dir ./demo/claude \
  --data-dir ~/.cache/cchv/demo
```

Common examples:

```bash
# Store indexes outside the repo (recommended)
python3 app.py --data-dir ~/.cache/cchv

# Same thing via the bundled CLI
CCHV serve --data-dir ~/.cache/cchv

# Bind to LAN (be careful: your logs may contain secrets)
python3 app.py --host 0.0.0.0 --port 8787

# Launch with bundled synthetic logs
CCHV demo

# Install CCHV into ~/.local/bin so it works globally
CCHV install

# Custom log locations (these are the *base dirs* that contain `sessions/` and `projects/`)
python3 app.py --codex-dir ~/.codex --claude-dir ~/.claude

# Faster/slower auto-rescan (seconds)
python3 app.py --scan-interval 2
```

## Using the UI

- **Source**: switch between Codex / Claude Code logs.
- **Browse**:
  - **Sessions**: list individual sessions.
  - **Projects**: group sessions by working directory (cwd).
- **Sidebar sort**: top-right dropdown in the sessions list:
  - `Start time` (default)
  - `Last activity`
- **Roles**: toggle user/assistant/system/developer/tool/other.
- **Role jump**: click a message on the right, then use each role row’s `▲/▼` buttons to jump across that role. The `n/m` counter shows the selected message’s position within that role.
- **Search**
  - Left panel: keyword search across sessions + optional date range, with a keyword clear button.
  - Right panel: search within the opened session (highlight + ▲/▼ navigation). The summary uses `n/m` format.
- **Error highlighting**
  - User interruptions (e.g. `turn_aborted`) are highlighted.
  - Common tool failures (HTTP 4xx/5xx, Traceback/Exception, `Status: error`, etc.) are highlighted.

## Privacy & safety notes

- Your local transcripts may contain sensitive info (API keys, file paths, proprietary code).
- If you bind `--host 0.0.0.0`, anyone on your network may be able to access the UI. Prefer `127.0.0.1`.
- Index files are local SQLite databases; this repo’s `.gitignore` excludes them.

## License

MIT (see `LICENSE`).
