Skip to content

Commit 732a35a

Browse files
neongreenneongreen
authored
Merge pull request #27 from neongreen/copilot/add-log-review-tool-go
Add claude-trace: TUI tool for reviewing and annotating Claude Code conversation logs
2 parents 008f2de + 6862b03 commit 732a35a

File tree

13 files changed

+1220
-0
lines changed

13 files changed

+1220
-0
lines changed

‎claude-trace/.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Binaries
2+
claude-trace
3+
*.exe
4+
*.exe~
5+
*.dll
6+
*.so
7+
*.dylib
8+
9+
# Test binary
10+
*.test
11+
12+
# Output of go coverage tool
13+
*.out
14+
15+
# Go workspace file
16+
go.work
17+
18+
# Annotations (these are user-specific)
19+
*.annotations.json

‎claude-trace/IMPLEMENTATION.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# claude-trace Implementation Summary
2+
3+
## Overview
4+
5+
`claude-trace` is a terminal user interface (TUI) tool for reviewing and annotating Claude Code conversation logs. It provides an interactive way to go through session traces and mark them up with tags and notes.
6+
7+
## Architecture
8+
9+
### Project Structure
10+
11+
```
12+
claude-trace/
13+
├── cmd/
14+
│ └── main.go # Application entry point
15+
├── pkg/
16+
│ ├── storage/ # Trace file management
17+
│ │ ├── discovery.go # Finds Claude Code trace locations
18+
│ │ └── trace.go # Load/save traces and annotations
19+
│ └── tui/ # Terminal user interface
20+
│ └── model.go # Bubbletea TUI model and views
21+
├── traces/ # Sample trace files for testing
22+
├── README.md # User documentation
23+
└── go.mod # Go module dependencies
24+
```
25+
26+
## Key Components
27+
28+
### 1. Trace Discovery (`pkg/storage/discovery.go`)
29+
30+
The tool searches for Claude Code traces in multiple platform-specific locations:
31+
32+
**Linux/XDG:**
33+
- `~/.config/Claude/traces`
34+
- `~/.local/share/Claude/traces`
35+
- `~/.local/share/claude-code/traces`
36+
37+
**macOS:**
38+
- `~/Library/Application Support/Claude/traces`
39+
- `~/Library/Application Support/claude-code/traces`
40+
41+
**Windows:**
42+
- `%APPDATA%/Claude/traces`
43+
- `%LOCALAPPDATA%/Claude/traces`
44+
45+
**Fallback:**
46+
- `./traces` (current directory for testing)
47+
48+
The tool automatically finds all available trace locations and loads files from them.
49+
50+
### 2. Trace Management (`pkg/storage/trace.go`)
51+
52+
**Data Structure:**
53+
```go
54+
type Trace struct {
55+
Path string // Full path to trace file
56+
Name string // Filename
57+
Content string // File content
58+
ModTime time.Time // Last modification time
59+
Annotations []Annotation // History of annotations
60+
Tags map[string]bool // Active tags
61+
FreeformNote string // User's notes
62+
}
63+
```
64+
65+
**Features:**
66+
- Loads trace files (`.log`, `.json`, `.txt`, `.md`)
67+
- Sorts traces by modification time (newest first)
68+
- Saves annotations as JSON files (`.annotations.json`)
69+
- Loads existing annotations on startup
70+
71+
### 3. Terminal UI (`pkg/tui/model.go`)
72+
73+
Built with [Charm's Bubbletea](https://github.com/charmbracelet/bubbletea) framework.
74+
75+
**Three Modes:**
76+
77+
1. **List Mode** - Browse traces
78+
- Navigate with arrow keys or vim bindings (j/k)
79+
- Quick tag application
80+
- Shows active tags inline
81+
82+
2. **View Mode** - Read trace content
83+
- Scrollable viewport
84+
- Tag display
85+
- Notes display
86+
- Apply tags while viewing
87+
88+
3. **Annotate Mode** - Add freeform notes
89+
- Multi-line text input
90+
- Save with Ctrl+S
91+
- Cancel with Esc
92+
93+
## Tag System
94+
95+
Five quick-access tags for common annotations:
96+
97+
- **G** (Good) - Sessions that went well
98+
- **S** (Suspicious) - Potential issues
99+
- **F** (Frustration) - Challenging sessions
100+
- **B** (Bug) - Bug-related conversations
101+
- **W** (Win) - Successful outcomes
102+
103+
Tags can be toggled on/off and are saved with timestamp history.
104+
105+
## Annotation Persistence
106+
107+
Annotations are saved as JSON files alongside traces:
108+
109+
```
110+
session-2024-03-15.log # Original trace
111+
session-2024-03-15.log.annotations.json # Annotations
112+
```
113+
114+
The annotation file contains:
115+
- All trace metadata
116+
- Active tags
117+
- Freeform notes
118+
- Complete annotation history with timestamps
119+
120+
## Dependencies
121+
122+
- **bubbletea** (v1.3.10) - TUI framework
123+
- **lipgloss** (v1.1.0) - Terminal styling
124+
- **bubbles** (v0.21.0) - TUI components (viewport, textarea)
125+
126+
All dependencies checked for vulnerabilities - none found.
127+
128+
## Usage Flow
129+
130+
1. **Discovery** - Tool searches common locations for traces
131+
2. **Loading** - Loads all trace files and existing annotations
132+
3. **Browsing** - User navigates through traces in list view
133+
4. **Reviewing** - User views trace content in detail
134+
5. **Annotating** - User adds tags and notes
135+
6. **Saving** - Annotations saved to disk (manual with 'S' or automatic with Ctrl+S)
136+
137+
## Testing
138+
139+
The repository includes three sample trace files in `traces/`:
140+
- `session-2024-03-15.log` - Simple successful session
141+
- `session-2024-03-16.log` - Debugging session with frustration
142+
- `session-2024-03-17.log` - Test writing session
143+
144+
These can be used to explore the tool's functionality.
145+
146+
## Future Enhancements
147+
148+
Potential improvements (not implemented):
149+
- Search/filter traces by content or tags
150+
- Export annotations to different formats (markdown, CSV)
151+
- Aggregate statistics (most common tags, session duration analysis)
152+
- Integration with actual Claude Code trace format parsing
153+
- Support for trace format auto-detection
154+
- Multi-trace comparison view

‎claude-trace/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# claude-trace
2+
3+
A terminal user interface tool for reviewing and annotating Claude Code conversation logs and traces.
4+
5+
## Overview
6+
7+
`claude-trace` helps you review your Claude Code sessions by providing an interactive TUI to:
8+
- Browse through conversation logs
9+
- Mark traces with quick tags (Good, Suspicious, Frustration, Bug, Win)
10+
- Add freeform notes and annotations
11+
- Save your reviews for future reference
12+
13+
## Installation
14+
15+
### Build from source
16+
17+
```bash
18+
cd claude-trace
19+
go build -o claude-trace ./cmd
20+
```
21+
22+
### Run directly
23+
24+
```bash
25+
go run ./cmd
26+
```
27+
28+
## Usage
29+
30+
The tool automatically searches for Claude Code traces in these locations:
31+
- `~/.claude/projects/` (conversation histories in JSONL format)
32+
- `~/.claude/debug/` (debug logs per session)
33+
- `~/.claude/traces/` (user-created traces)
34+
- `~/.config/Claude/traces` (legacy location)
35+
- `~/Library/Application Support/Claude/traces` (legacy location)
36+
- `~/.local/share/Claude/traces` (legacy location)
37+
- `./traces` (current directory)
38+
39+
Simply run:
40+
41+
```bash
42+
./claude-trace
43+
```
44+
45+
### Keyboard Shortcuts
46+
47+
#### List View
48+
- `↑/k`: Move up in the list
49+
- `↓/j`: Move down in the list
50+
- `enter`: View selected trace
51+
- `g`: Toggle "Good" tag
52+
- `s`: Toggle "Suspicious" tag
53+
- `f`: Toggle "Frustration" tag
54+
- `b`: Toggle "Bug" tag
55+
- `w`: Toggle "Win" tag
56+
- `n`: Add/edit freeform notes
57+
- `q`: Quit
58+
59+
#### View Mode
60+
- `↑/↓`: Scroll through trace content
61+
- `g/s/f/b/w`: Toggle tags
62+
- `n`: Add/edit notes
63+
- `S`: Save annotations to disk
64+
- `q` or `esc`: Return to list
65+
66+
#### Annotation Mode
67+
- Type your notes freely
68+
- `ctrl+s`: Save and return to view mode
69+
- `esc`: Cancel and return to view mode
70+
71+
## Trace Discovery
72+
73+
Since Claude Code's actual trace storage location may vary by version and platform, this tool searches multiple locations. The primary locations are:
74+
75+
1. **`~/.claude/projects/`** - Contains conversation histories in JSONL format, organized by project path
76+
2. **`~/.claude/debug/`** - Contains debug logs for each session
77+
3. **`~/.claude/traces/`** - User-created trace files
78+
79+
Legacy locations are also searched for compatibility:
80+
- `~/.config/Claude/traces`
81+
- `~/Library/Application Support/Claude/traces`
82+
- `~/.local/share/Claude/traces`
83+
84+
If your traces are stored elsewhere, you can:
85+
86+
1. Create a symbolic link from one of the searched locations to your actual trace directory
87+
2. Copy your traces to the `./traces` directory in the claude-trace folder
88+
3. Modify the `pkg/storage/discovery.go` file to add your custom location
89+
90+
## Annotations
91+
92+
Annotations are saved as JSON files alongside the original traces with a `.annotations.json` extension. For example:
93+
- Original trace: `session-2024-03-15.log`
94+
- Annotations: `session-2024-03-15.log.annotations.json`
95+
96+
The annotation file contains:
97+
- All applied tags
98+
- Freeform notes
99+
- Timestamp history of annotations
100+
101+
## Example Traces
102+
103+
The repository includes sample traces in the `traces/` directory for testing purposes.
104+
105+
## Features
106+
107+
- **Tag System**: Quick keyboard shortcuts for common annotations
108+
- `g`: Good - Mark sessions that went well
109+
- `s`: Suspicious - Flag potential issues
110+
- `f`: Frustration - Note sessions with challenges
111+
- `b`: Bug - Identify bug-related sessions
112+
- `w`: Win - Celebrate successful outcomes
113+
114+
- **Freeform Notes**: Add detailed observations and thoughts about each session
115+
116+
- **Persistent Storage**: Annotations are saved to disk and reloaded when viewing traces again
117+
118+
- **File Format Support**: Automatically detects `.log`, `.json`, `.jsonl`, `.txt`, and `.md` files
119+
120+
## Requirements
121+
122+
- Go 1.24.4 or later
123+
- Terminal with color support (for best experience)
124+
125+
## Dependencies
126+
127+
- [bubbletea](https://github.com/charmbracelet/bubbletea) - TUI framework
128+
- [lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions
129+
- [bubbles](https://github.com/charmbracelet/bubbles) - TUI components
130+
131+
## License
132+
133+
See [LICENSE](../LICENSE) in the repository root.

0 commit comments

Comments
 (0)