docs: add README and CC BY-NC 4.0 license
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)
This commit is contained in:
Mathias Beaulieu-Duncan
parent
659dade82d
commit
e963b2edcd
49
LICENSE
Normal file
49
LICENSE
Normal file
@ -0,0 +1,49 @@
|
||||
Creative Commons Attribution-NonCommercial 4.0 International
|
||||
|
||||
Copyright (c) 2026 Svrnty
|
||||
|
||||
This work is provided under the terms of the Creative Commons
|
||||
Attribution-NonCommercial 4.0 International Public License
|
||||
("CC BY-NC 4.0"). A summary of the license is below. The full
|
||||
license text is available at:
|
||||
|
||||
https://creativecommons.org/licenses/by-nc/4.0/legalcode
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
You are free to:
|
||||
|
||||
Share — copy and redistribute the material in any medium or format
|
||||
|
||||
Adapt — remix, transform, and build upon the material
|
||||
|
||||
Under the following terms:
|
||||
|
||||
Attribution — You must give appropriate credit, provide a link to
|
||||
the license, and indicate if changes were made. You may do so in
|
||||
any reasonable manner, but not in any way that suggests the
|
||||
licensor endorses you or your use.
|
||||
|
||||
NonCommercial — You may not use the material for commercial purposes.
|
||||
This includes, but is not limited to, selling the software, using
|
||||
it as part of a commercial product or service, or charging for
|
||||
access to features built on top of it.
|
||||
|
||||
No additional restrictions — You may not apply legal terms or
|
||||
technological measures that legally restrict others from doing anything
|
||||
the license permits.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
NOTICES:
|
||||
|
||||
"Claude Session Viewer" is not affiliated with, endorsed by, or
|
||||
connected to Anthropic PBC. "Claude" is a trademark of Anthropic PBC.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
190
README.md
Normal file
190
README.md
Normal file
@ -0,0 +1,190 @@
|
||||
# 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.
|
||||
Loading…
Reference in New Issue
Block a user