From e963b2edcdb77bc3823ab8def8e5aec57178cb11 Mon Sep 17 00:00:00 2001 From: Mathias Beaulieu-Duncan Date: Tue, 7 Apr 2026 13:34:42 -0400 Subject: [PATCH] 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) --- LICENSE | 49 ++++++++++++++ README.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3ae25c1 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..757033c --- /dev/null +++ b/README.md @@ -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. + +![macOS 13.0+](https://img.shields.io/badge/platform-macOS%2013%2B-black) ![Free](https://img.shields.io/badge/license-CC--BY--NC--4.0-green) + +--- + +## 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) +→ SessionProvider caches filteredEntries +→ Screens consume via context.select() +``` + +### 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.