README
¶
codex-history
codex-history is a fast, local-first TUI for browsing, searching, and resuming
Codex CLI conversations.
The application talks to the supported Codex app-server protocol instead of parsing private rollout files. Conversation content stays on your machine; the optional full-text index is a local SQLite database.
Features
- Adaptive three-pane conversation, transcript, and turn-diff viewer, with two-pane and compact single-pane layouts
- Relevance-ranked full-text search with match snippets across user and assistant messages
- Conversation-first reading with plans, reasoning, commands, file changes, MCP calls, and other events grouped into inspectable Activity rows
- Resume a selected conversation with
codex resume <thread-id> - Strict, versioned TOML configuration with fully customizable key bindings
- Project, source, and archived-conversation filters
- macOS and Linux support, designed for Homebrew and Nix distribution
Installation
Codex CLI must be installed and available as codex unless another executable
is selected with --codex-bin or codex.binary in the configuration file.
Homebrew
brew install --cask HizKz/tap/codex-history
Release archive
Download the archive for your platform from the
GitHub releases, verify it
against checksums.txt, and place codex-history on your PATH.
From source
Requirements: Go 1.25 or newer and a working codex executable.
go install github.com/HizKz/codex-history/cmd/codex-history@latest
An upstream nixpkgs package is planned.
Usage
codex-history
codex-history --reindex
codex-history doctor
codex-history config init
codex-history config check
Default keys include:
| Key | Action |
|---|---|
j / k, arrows |
Move conversations or scroll transcript/diff vertically |
ctrl+u / ctrl+d |
Scroll transcript, diff, or detail by half a page |
h / l, left / right |
Scroll long diff lines horizontally |
[ / ] |
Jump to the previous or next turn |
tab |
Switch pane focus |
/ |
Full-text search |
p |
Select a working-directory project filter |
enter |
Resume the selected conversation; return to the shell when Codex exits |
space |
Open the selected turn's Activity inspector |
esc |
Return from event detail or Activity |
r |
Refresh conversations |
R |
Rebuild the search index |
ctrl+r |
Reload configuration without restarting |
s / a |
Toggle all sources / archived conversations |
? |
Show configured keys |
q |
Quit |
ctrl+c |
Emergency exit (always reserved) |
Configuration
The default path follows the operating system convention:
- macOS:
~/Library/Application Support/codex-history/config.toml - Linux:
${XDG_CONFIG_HOME:-~/.config}/codex-history/config.toml
CODEX_HISTORY_CONFIG or --config can select another file. Create a fully
commented starting point with:
codex-history config init
Configuration is strict: unknown fields, invalid colors, unsupported values,
and conflicting active key bindings are reported before the TUI starts. Missing
values inherit the embedded defaults. To define a keymap from scratch, set
keys.use_defaults = false. Explicit bindings take precedence over inherited
defaults; conflicts between explicit bindings are rejected.
See examples/config.toml for every option.
The default resume.mode = "replace" replaces codex-history with Codex, so
exiting Codex returns to the shell. Set it to "return" to reopen the history
browser instead, or "print_command" to print the command without running it.
The local index is stored below the OS cache directory. Command output, MCP
arguments/results, file-change paths and diff bodies, and other expandable tool
details are intentionally excluded from full-text indexing. Searches of three
or more characters use the trigram index for relevance ranking and match
snippets; shorter searches retain literal substring matching. Use --no-cache
for an in-memory index.
Development
go mod tidy -diff
go test ./...
go test -race ./...
go vet ./...
staticcheck ./...
nix build --no-link 'path:.#codex-history'
Release metadata is injected with Go linker flags; snapshots can be built with GoReleaser.
Repository conventions live in AGENTS.md. Architecture and release
details are documented in docs/architecture.md and
docs/releasing.md. Codex also discovers the checked-in
maintain-codex-history workflow from .agents/skills.
Issues and pull requests are welcome. See CONTRIBUTING.md, the Code of Conduct, and the Security Policy before contributing or reporting sensitive problems.
Privacy and compatibility
codex-history launches codex app-server --listen stdio:// and uses the
versioned thread/list and thread/read APIs. It does not upload conversation
data. The SQLite cache contains searchable conversation text and is created with
user-only permissions where supported.
This is a community project and is not an official OpenAI product.
License
MIT — see LICENSE.
Directories