e963b2edcd
README includes: - Non-technical user section (installation, quick start, tips) - Developer section (architecture, data flow, design decisions, build instructions, signed DMG workflow, dependencies) - License summary (free to use/modify/distribute, no monetization)
191 lines
7.5 KiB
Markdown
191 lines
7.5 KiB
Markdown
# Claude Session Viewer
|
|
|
|
A macOS desktop app for browsing and analyzing your Claude AI conversation sessions. Explore your prompts, assistant responses, tool usage, token consumption, and subagent activity — all in a fast, searchable interface.
|
|
|
|
 
|
|
|
|
---
|
|
|
|
## For Everyone
|
|
|
|
### What It Does
|
|
|
|
If you use [Claude](https://claude.ai) with the CLI (`claude`), every conversation is saved as a `.jsonl` file on your Mac. **Claude Session Viewer** lets you open those files and browse them with:
|
|
|
|
- **Timeline view** — See your conversation as a visual tree with user prompts, assistant responses, and tool calls all laid out chronologically
|
|
- **Search & filter** — Find specific messages, filter by type (user/assistant/system), or narrow down to a specific subagent
|
|
- **Tool usage analytics** — See which tools were used, how often, and with what arguments
|
|
- **Token tracking** — Break down token consumption by agent (input, output, cache hits)
|
|
- **Subagent inspection** — Drill into subagent conversations that were spawned during a session
|
|
|
|
### Installation
|
|
|
|
1. Download the latest `Claude Session Viewer.dmg` from the [Releases](../../releases) page
|
|
2. Double-click the DMG
|
|
3. Drag **Claude Session Viewer** to your **Applications** folder
|
|
4. Launch it — no Gatekeeper warnings, the app is signed and notarized by Apple
|
|
|
|
### Quick Start
|
|
|
|
1. Open the app
|
|
2. It automatically scans `~/.claude/projects` for your session files
|
|
3. Pick a project → pick a session → browse the timeline
|
|
4. Or use **File → Open** to load any `.jsonl` file directly
|
|
|
|
### Tips
|
|
|
|
- Use the **search bar** in the timeline to find specific messages or tool calls
|
|
- Click the **type toggles** (User / Assistant / System) to filter what's shown
|
|
- Use the **agent dropdown** to focus on a specific subagent's activity
|
|
- Expand **tool use cards** to see arguments, results, and inline subagent conversations
|
|
- Expand **Thinking** blocks to see Claude's reasoning (when available)
|
|
|
|
---
|
|
|
|
## For Developers
|
|
|
|
### Architecture
|
|
|
|
```
|
|
lib/
|
|
├── main.dart # Entry point, Provider setup
|
|
├── models/
|
|
│ ├── agent_info.dart # AgentInfo + SessionLog aggregates
|
|
│ ├── content_block.dart # ContentBlock hierarchy (Text, Thinking, ToolUse, ToolResult)
|
|
│ ├── log_entry.dart # LogEntry hierarchy (User, Assistant, System, Progress, FileSnapshot)
|
|
│ └── token_usage.dart # TokenUsage value type
|
|
├── providers/
|
|
│ └── session_provider.dart # ChangeNotifier with cached filtering + debounced search
|
|
├── services/
|
|
│ └── jsonl_parser.dart # Isolate-based JSONL parser + session builder
|
|
├── screens/
|
|
│ ├── home/ # Project/session browser (scans ~/.claude/projects)
|
|
│ ├── timeline/ # Flat virtualized timeline with tree connectors
|
|
│ ├── agents/ # Agent analytics cards
|
|
│ ├── tokens/ # Token usage dashboard (pie chart + data table)
|
|
│ └── toolbelt/ # Tool usage bar chart + per-tool details
|
|
├── theme/
|
|
│ └── app_theme.dart # Dark theme + color constants
|
|
└── widgets/
|
|
├── common/ # ExpandableCard (lazy expand), JsonTreeView
|
|
└── navigation/ # AppShell (IndexedStack), Sidebar
|
|
```
|
|
|
|
### Data Flow
|
|
|
|
```
|
|
FilePicker → SessionProvider.loadSession()
|
|
→ Isolate.run(JsonlParser._parseInIsolate) # CPU work off main thread
|
|
→ jsonDecode per line + LogEntry.fromJson
|
|
→ _linkToolResults() + _buildAgents()
|
|
→ ParseResult(SessionLog, List<ParseError>)
|
|
→ SessionProvider caches filteredEntries
|
|
→ Screens consume via context.select<SessionProvider, T>()
|
|
```
|
|
|
|
### Key Design Decisions
|
|
|
|
| Decision | Rationale |
|
|
|----------|-----------|
|
|
| **Single ChangeNotifier** | App has one data source (a session file). No need for Riverpod/Bloc complexity. |
|
|
| **Isolate-based parsing** | 50K-line JSONL files parse in 2-4s — must not block the UI thread. |
|
|
| **Flat virtualized timeline** | Flattened turns into `List<_TimelineItem>` so `ListView.builder` recycles every card independently. |
|
|
| **Cached filter results** | `_FilterKey`-based invalidation avoids O(n) recomputation on every rebuild. |
|
|
| **Lazy ExpandableCard** | `AnimatedCrossFade` builds both children eagerly. Replaced with `SizeTransition` + `_hasBeenExpanded` guard. |
|
|
| **IndexedStack navigation** | Preserves scroll position and state across tab switches. |
|
|
| **No code generation** | 17 source files, single-user tool — hand-written `fromJson` is fine. |
|
|
|
|
### Building from Source
|
|
|
|
**Requirements:** Flutter 3.29+ / Dart 3.10+, macOS 13.0+, Xcode 16+
|
|
|
|
```bash
|
|
# Clone
|
|
git clone https://github.com/your-org/claude_session_viewer.git
|
|
cd claude_session_viewer
|
|
|
|
# Install dependencies
|
|
flutter pub get
|
|
|
|
# Run in debug mode
|
|
flutter run -d macos
|
|
|
|
# Build release
|
|
flutter build macos --release
|
|
```
|
|
|
|
### Building a Signed & Notarized DMG
|
|
|
|
The project is pre-configured for Developer ID distribution. Set your team ID in `macos/Runner.xcodeproj/project.pbxproj` and `macos/Runner/Configs/AppInfo.xcconfig`, then:
|
|
|
|
```bash
|
|
# Build
|
|
flutter build macos --release
|
|
|
|
# Re-sign with hardened runtime (inside-out)
|
|
APP="build/macos/Build/Products/Release/Claude Session Viewer.app"
|
|
SIGN_ID="Developer ID Application: Your Name (TEAMID)"
|
|
|
|
find "$APP/Contents/Frameworks" -name "*.framework" -maxdepth 1 | while read fw; do
|
|
codesign --force --deep --sign "$SIGN_ID" --timestamp --options runtime \
|
|
--entitlements macos/Runner/Release.entitlements "$fw"
|
|
done
|
|
|
|
codesign --force --deep --sign "$SIGN_ID" --timestamp --options runtime \
|
|
--entitlements macos/Runner/Release.entitlements "$APP"
|
|
|
|
# Create DMG
|
|
hdiutil create -volname "Claude Session Viewer" \
|
|
-srcfolder "$APP" -ov -format UDZO \
|
|
"build/Claude Session Viewer.dmg"
|
|
|
|
# Sign DMG
|
|
codesign --sign "$SIGN_ID" --timestamp "build/Claude Session Viewer.dmg"
|
|
|
|
# Notarize
|
|
xcrun notarytool submit "build/Claude Session Viewer.dmg" \
|
|
--keychain-profile "notarytool" --wait
|
|
|
|
# Staple ticket
|
|
xcrun stapler staple "build/Claude Session Viewer.dmg"
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `provider` | State management (ChangeNotifier) |
|
|
| `file_picker` | Native file picker dialog |
|
|
| `flutter_markdown` | Markdown rendering in assistant messages |
|
|
| `fl_chart` | Pie chart (tokens) + bar chart (tool usage) |
|
|
| `google_fonts` | Inter font family |
|
|
| `intl` | Number/date formatting |
|
|
|
|
### Entitlements (macOS Sandbox)
|
|
|
|
The release build runs in the macOS **App Sandbox** with:
|
|
- `com.apple.security.app-sandbox` — enabled
|
|
- `com.apple.security.files.user-selected.read-only` — open files via dialog
|
|
- `com.apple.security.files.home-directory.read-only` — scan `~/.claude/projects`
|
|
|
|
### Contributing
|
|
|
|
Contributions are welcome! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/my-feature`)
|
|
3. Commit your changes
|
|
4. Open a pull request
|
|
|
|
Note: This project is **non-commercial** — contributions must respect the CC BY-NC 4.0 license.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This project is licensed under [Creative Commons Attribution-NonCommercial 4.0 International](./LICENSE).
|
|
|
|
You are free to use, modify, and distribute this software for personal and non-commercial purposes. Commercial use, resale, or monetization is not permitted without written permission.
|
|
|
|
© 2026 Svrnty. All rights reserved.
|