Skip to content

Commit fea1ec5

Browse files
lroolleclaude
andcommitted
docs: rewrite README for v0.3.0 multi-provider release
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2607e2d commit fea1ec5

1 file changed

Lines changed: 62 additions & 34 deletions

File tree

README.md

Lines changed: 62 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
# ccx
22

3-
**Session viewer for Claude Code** - Browse, search, and export your conversations.
4-
5-
Inspired by [Simon Willison's claude-code-transcripts](https://github.com/simonw/claude-code-transcripts) ([announcement](https://x.com/simonw/status/1872004339799512305)) - rebuilt in Go with live tailing, web UI, and two-panel navigation.
3+
**Session viewer for coding agents** — Browse, search, and export conversations from Claude Code and Codex.
64

75
```
86
ccx web
97
```
108

11-
That's it. Opens a browser at `localhost:8080`.
9+
Opens a browser at `localhost:8080`. That's it.
1210

1311
## Screenshots
1412

@@ -27,20 +25,30 @@ That's it. Opens a browser at `localhost:8080`.
2725

2826
</details>
2927

30-
## Features
28+
## What it does
29+
30+
ccx reads session files from `~/.claude/` and `~/.codex/` and gives you a fast, keyboard-driven interface to browse them.
31+
32+
- **Multi-provider** — Claude Code + Codex sessions merged by project, with provider badges
33+
- **Two-panel navigation** — Projects → Sessions → Conversation tree
34+
- **Live tail** — Watch active sessions update in real-time
35+
- **In-session search** — Filter by User, Response, Tools, Agents, Thinking
36+
- **Memory inspector** — View CLAUDE.md, MEMORY.md, AGENTS.md per project
37+
- **Brief export** — Conversation-only mode strips tool noise
38+
- **Export** — HTML, Markdown, Org-mode, JSON
39+
- **Provider filter**`--provider cc` or `--provider cx` on any command
40+
- **Date filter**`--after 2026-03-01 --before 2026-04-01`
41+
- **Keyboard shortcuts**`j/k` scroll, `/` search, `z` fold, `r` refresh, `d` theme
3142

32-
- **Two-panel navigation** - Projects → Sessions → Conversation
33-
- **Live tail mode** - Watch active sessions in real-time
34-
- **In-session search** - Filter by User, Response, Tools, Agents, Thinking
35-
- **Tree-aware threading** - parentUuid, sidechains, compaction markers
36-
- **Collapsible blocks** - Thinking, tool calls, agent responses
37-
- **Export** - HTML, Markdown, Org-mode, JSON
38-
- **Keyboard shortcuts** - `j/k` scroll, `/` search, `z` fold, `r` refresh, `d` theme
43+
Single binary, zero dependencies, read-only. Never touches your session files.
3944

40-
## Installation
45+
## Install
4146

42-
Requires Go 1.24+ (pure Go, no C compiler needed).
47+
```bash
48+
curl -fsSL https://raw.githubusercontent.com/thevibeworks/ccx/main/install.sh | bash
49+
```
4350

51+
Or via Go:
4452
```bash
4553
go install github.com/thevibeworks/ccx/cmd/ccx@latest
4654
```
@@ -52,38 +60,58 @@ cd ccx && make build
5260
./bin/ccx web
5361
```
5462

55-
## CLI Commands
63+
## Usage
5664

5765
```bash
58-
ccx web # Start web UI (recommended)
59-
ccx projects # List all projects
60-
ccx sessions [project] # List sessions
61-
ccx view [session] # View in terminal
62-
ccx export -f html # Export to HTML/Markdown/Org
63-
ccx search QUERY # Search projects and sessions
64-
ccx doctor # Check configuration
66+
ccx web # Start web UI (recommended)
67+
ccx projects # List all projects
68+
ccx sessions # List recent sessions
69+
ccx sessions --provider=cx # Codex sessions only
70+
ccx sessions --after=2026-03-01 # Date filtered
71+
ccx view [session] # View in terminal
72+
ccx export -f html --brief # Export conversation-only HTML
73+
ccx search "auth bug" # Search across sessions + memory
74+
ccx doctor # Check setup
6575
```
6676

6777
## Configuration
6878

69-
ccx reads from `~/.claude/` (or `CLAUDE_CODE_HOME`) and never modifies those files.
79+
```yaml
80+
# ~/.config/ccx/config.yaml
81+
theme: dark
82+
show_thinking: collapsed
83+
default_format: html
84+
providers:
85+
claude-code:
86+
enabled: true
87+
codex:
88+
enabled: true
89+
```
7090
91+
Override provider homes:
7192
```bash
72-
# Override Claude Code home
73-
ccx --claude-home /path/to/claude web
74-
CLAUDE_CODE_HOME=/path/to/claude ccx web
93+
ccx --claude-home /path web
94+
ccx --codex-home /path web
95+
```
96+
97+
## Data safety
98+
99+
ccx treats all agent data as **read-only**. Writes only to its own directories:
100+
- `$XDG_CONFIG_HOME/ccx/` — config
101+
- `$XDG_DATA_HOME/ccx/` — stars database
75102

76-
# Config locations
77-
~/.config/ccx/config.yaml # User config
78-
~/.local/share/ccx/ # ccx data (stars, cache)
103+
## Claude Code skill
104+
105+
ccx ships as a Claude Code skill. Install alongside the binary:
106+
```bash
107+
curl -fsSL https://raw.githubusercontent.com/thevibeworks/ccx/main/install.sh | bash
79108
```
80109

81-
## Data Safety
110+
Or manually copy `skills/ccx/` to `~/.claude/skills/ccx/`.
111+
112+
## Credits
82113

83-
ccx treats Claude Code data as **read-only**. It only writes to its own directories:
84-
- `$XDG_CONFIG_HOME/ccx/` - configuration
85-
- `$XDG_DATA_HOME/ccx/` - SQLite data (stars, if using web UI)
86-
- Export files you explicitly request
114+
Inspired by [Simon Willison's claude-code-transcripts](https://github.com/simonw/claude-code-transcripts). Rebuilt in Go with live tailing, multi-provider support, and a web UI.
87115

88116
## License
89117

0 commit comments

Comments
 (0)