Peek Codex is a fast, read-only terminal browser for local Codex sessions. The first vertical slice lists real sessions through the supported Codex app-server boundary, keeps loading later pages in the background, and provides predictable keyboard navigation.
- macOS or Linux
- Go 1.25 or newer
- Codex CLI 0.146.0 or newer on
PATH - An interactive terminal
./scripts/launch.shThe launcher always runs the current checkout without relying on a prebuilt temporary binary. Use --help, --version, or --log-file <PATH> after the launcher command. Diagnostics are silent unless a log file is explicitly requested.
Sessions is the first screen. It refreshes the newest page and runtime thread states every 10 seconds; press r to refresh now. ● Running, ◉ Loaded, and ○ Not loaded show the current app-server runtime state. Use Up/k, Down/j, Home, and End to move; press / for fuzzy search across safe metadata, Enter for a read-only details view, and q/Ctrl-C to exit. While typing a search, every printable key—including j, k, and q—is query text; use arrows to move filtered rows and Esc to clear search or return from details before exiting Sessions.
go mod verify
test -z "$(gofmt -l .)"
go vet -mod=readonly ./...
go test -mod=readonly -race ./...
sh scripts/test-launcher.sh
go build -mod=readonly -o /tmp/peek-codex ./cmd/peek-codex
go install golang.org/x/vuln/cmd/govulncheck@v1.7.0
"$(go env GOPATH)/bin/govulncheck" ./...GitHub Actions validates pull requests and pushes to main. It caches Go dependencies, cancels superseded runs for the same branch or pull request, and runs the validation commands above with a 10-minute job limit. A manual run remains available through workflow_dispatch.
This release is read-only. It uses Bubble Tea, Bubbles, and Lip Gloss over codex app-server stdio; it does not inspect Codex SQLite databases or JSONL rollout files. Agent-output previews are neither displayed nor searchable. Enter opens a project-derived summary from safe list metadata; conversation turns are not loaded.
See TASKS.md for the roadmap and docs/ for product, architecture, integration, TUI, testing, and the small-commit delivery workflow.
MIT