{"id":45778918,"url":"https://github.com/leonardocardoso/poirot","last_synced_at":"2026-04-01T22:37:40.375Z","repository":{"id":340231681,"uuid":"1161536004","full_name":"leonardocardoso/poirot","owner":"leonardocardoso","description":"A native macOS companion for Claude Code that lets you browse sessions, explore diffs, and re-run commands.","archived":false,"fork":false,"pushed_at":"2026-03-29T19:42:18.000Z","size":61772,"stargazers_count":142,"open_issues_count":8,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T20:15:58.549Z","etag":null,"topics":["ai","claude","claude-code","codex","dev-tools","open-ai"],"latest_commit_sha":null,"homepage":"https://poirot.fyi","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonardocardoso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"leonardocardoso"}},"created_at":"2026-02-19T08:14:00.000Z","updated_at":"2026-03-29T18:33:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leonardocardoso/poirot","commit_stats":null,"previous_names":["leonardocardoso/poirot"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/leonardocardoso/poirot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocardoso%2Fpoirot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocardoso%2Fpoirot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocardoso%2Fpoirot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocardoso%2Fpoirot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonardocardoso","download_url":"https://codeload.github.com/leonardocardoso/poirot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocardoso%2Fpoirot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","codex","dev-tools","open-ai"],"created_at":"2026-02-26T10:54:13.691Z","updated_at":"2026-04-01T22:37:40.364Z","avatar_url":"https://github.com/leonardocardoso.png","language":"Swift","funding_links":["https://github.com/sponsors/leonardocardoso"],"categories":["Swift"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/showcase/01-hero.png\" alt=\"Poirot — Investigating your Claude Code sessions\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePOIROT\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eInvestigating your Claude Code sessions.\u003c/strong\u003e\u003cbr/\u003e\n  A native macOS companion that lets you browse sessions, explore diffs, and re-run commands — all from a polished SwiftUI interface.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#capabilities\"\u003eCapabilities\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%2015%2B-black?style=flat-square\" alt=\"Platform\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/swift-6-F05138?style=flat-square\u0026logo=swift\u0026logoColor=white\" alt=\"Swift 6\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"MIT License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PRs-welcome-E8A642?style=flat-square\" alt=\"PRs Welcome\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/LeonardoCardoso/Poirot?style=flat-square\u0026color=E8A642\u0026label=stars\" alt=\"GitHub Stars\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  No login. No tracking. No analytics. No BYOK. No extra cost. Works offline. Less than 6 MB.\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://youtu.be/JLvNSRZrxdo\"\u003e\n    \u003cimg src=\"https://img.youtube.com/vi/JLvNSRZrxdo/maxresdefault.jpg\" alt=\"Poirot Demo Video\" width=\"720\" /\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003csub\u003eClick to watch the demo on YouTube\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n## The Story\n\nPoirot was **vibe-coded in a weekend**. The entire app — architecture, parser, UI, tests — was built in a single creative burst with Claude Code as the co-pilot. What started as \"I wonder if I can build a companion app for Claude Code... using Claude Code\" turned into a real, usable tool.\n\nNamed after **Hercule Poirot**, Agatha Christie's legendary detective. Because every great investigation needs the right tools — and Poirot helps you investigate exactly what your AI assistant has been up to.\n\n---\n\n## Features\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/showcase/02-analytics.png\" alt=\"Session Analytics\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/showcase/04-conversation.png\" alt=\"Rich Conversation View\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n- **Session Analytics** — Token consumption, cost breakdowns, model distribution, and session trends\n- **Session History Browser** — Sessions grouped by project with timestamps, model info, and token counts\n- **Rich Conversation View** — Full timeline with markdown rendering, syntax highlighting, and collapsible tool blocks\n- **Tool Block Display** — Every tool invocation rendered with name, icon, file path, and result\n- **Extended Thinking** — Collapsible thinking blocks with distinct purple accent\n- **Fuzzy Search (\u0026#x2318;K)** — Spotlight-style search across sessions, commands, file paths, and more\n- **Slash Commands** — Browse global and per-project commands with descriptions and permissions\n- **Skills** — Explore reusable skill modules with parsed frontmatter\n- **MCP Servers** — Live connection status indicators with color-coded SF Symbols\n- **Models** — Browse available models and their capabilities\n- **Sub-agents** — Create, edit, and manage custom sub-agents with tools, model, memory, and system prompt\n- **Plugins** — View installed plugins and their metadata\n- **Output Styles** — Preview output formatting styles\n- **Hooks** — Event hooks grouped by type with matcher patterns and handler details\n- **Session TODOs** — Per-session todo lists with status tracking\n- **Plans** — Browse `~/.claude/plans/` with rendered markdown and file watching\n- **Debug Log Viewer** — Color-coded log levels, search, filtering, and paginated loading\n- **Prompt History** — Browse input history with date grouping and project filtering\n- **AI Session Summaries** — Goal, outcome, helpfulness, and friction indicators from facets\n- **Memory** — Per-project auto-memory files with rendered markdown and live watching\n\n\u003e **See all features with screenshots in the [Feature Showcase](SHOWCASE.md).**\n\n---\n\n## Capabilities\n\n| Category | Feature | Description |\n|----------|---------|-------------|\n| **Analytics** | Session Analytics Dashboard | Token consumption, cost breakdowns, model distribution, and session trends |\n| **Sessions** | JSONL Transcript Parser | Parses `~/.claude/projects/` transcripts into structured models |\n| | Session History Browser | Sessions grouped by project with timestamps, model, token counts |\n| | Real-time File Watching | Auto-updates via GCD dispatch sources with 1s debounce |\n| | Per-Project Configuration | Supports global (`~/.claude/`) and per-project (`.claude/`) scopes |\n| | Session Detail View | Full conversation timeline with collapsible blocks and scroll-to-bottom |\n| **Conversation** | Markdown Rendering | Rich text with syntax highlighting via MarkdownUI + HighlightSwift |\n| | Code Diff Viewer | Syntax-highlighted inline diffs for Edit tool blocks |\n| | Bash Output Renderer | Terminal command output with monospace styling and exit status |\n| | Extended Thinking | Collapsible thinking blocks with distinct purple accent |\n| | Tool Blocks | Every tool invocation rendered with name, icon, file path, and result |\n| | In-Session Search | \u0026#x2318;F to search within the current conversation |\n| **Diagnostics** | Debug Log Viewer | Parse and browse `~/.claude/debug/` logs with color-coded levels, search, filtering, and paginated lazy loading |\n| | Auto-scroll to Error | Opens directly at the first error entry for quick triage |\n| | Relative Timestamps | Toggle between absolute (HH:mm:ss.SSS) and relative (+offset) time display |\n| **History** | Prompt History Browser | Browse `~/.claude/history.jsonl` with date grouping, project filtering, full-text search, and copy-to-clipboard |\n| **AI Summaries** | Session Facets | AI-generated analysis (goal, outcome, helpfulness) from `~/.claude/usage-data/facets/` |\n| | Outcome \u0026 Helpfulness Badges | Color-coded badges for success/partial/failure and helpfulness rating |\n| | Goal Categories | Tag chips showing categorized session goals with counts |\n| | Friction Indicators | Subtle indicators for tool failures, misunderstandings, and other friction |\n| | Live File Watching | Auto-updates when new facets appear via GCD dispatch sources |\n| **Search** | Universal Search (\u0026#x2318;K) | Fuzzy search across sessions, AI summaries, history, commands, skills, memory, MCP servers, plugins, output styles, models, sub-agents, plans, TODOs, and debug logs |\n| | Grouped Results | Results organized by category with counts |\n| | Quick Access | Empty state shows shortcuts, counts, and recent sessions |\n| **Configuration** | Commands | Browse and manage slash commands (global and per-project) |\n| | Skills | Browse and manage reusable skill modules |\n| | MCP Servers | Browse configured Model Context Protocol servers with live connection status |\n| | Models | Browse available models and capabilities |\n| | Sub-agents | Create, edit, duplicate, and delete custom sub-agents with categorized tool selection and memory configuration |\n| | Plugins | Browse installed plugins |\n| | Output Styles | Browse and manage output style configurations |\n| | Hooks | View and manage event hooks grouped by type with matcher patterns and handler details |\n| | TODOs | Browse per-session todo lists with status tracking and session navigation |\n| | Plans | Browse `~/.claude/plans/` markdown files with rendered/raw toggle, copy, delete, and file watching |\n| | Memory | Browse per-project auto-memory files with rendered markdown, project filtering, and file watching |\n| | Grid \u0026 List Views | Toggle between card grid and compact list layouts |\n| | Scope Badges | Visual distinction between Global and Project-scoped items |\n| **Integrations** | IDE/Editor | One-click open files in VS Code, Cursor, Xcode, or Zed |\n| | Terminal Selection | Pick your terminal: Terminal, iTerm2, Warp, Ghostty, Kitty, Alacritty |\n| | Quick Command Re-run | Click any Bash command to copy or open in your terminal |\n| **Export** | Session Export | Export sessions as Markdown or PDF with configurable options |\n| | Copy Markdown | One-click copy of session content as Markdown to clipboard |\n| | Share Sheet | Native macOS share sheet integration for exported files |\n| **Sub-agents** | Custom Agent Creation | Full form with name, description, system prompt, model, color, categorized tools, and persistent memory |\n| | Auto File Naming | File path auto-derived from agent name (lowercase, dashes); file renamed on edit |\n| | Tool Categories | Select tools by category (Read-only, Edit, Execution, Other) or individually |\n| | Agent Memory | Configure persistent memory per agent (global or none) |\n| | Import/Export | Share agents as JSON files between users |\n| | Duplicate | Clone built-in or custom agents as starting points |\n| **Navigation** | Font Scaling | ⌘+ / ⌘- / ⌘0 to zoom the entire UI |\n| | Keyboard Shortcuts | Full keyboard navigation with discoverable shortcut hints |\n| | Help Book (⌘?) | Keyboard reference, feature overview, and getting started guide |\n| **App** | Onboarding Flow | First-run welcome with CLI detection, session discovery, and feature tour |\n| | Homebrew Distribution | `brew install --cask poirot` with automated release workflow |\n| **Design** | Dark Theme | Warm golden accent (`#E8A642`) on near-black backgrounds |\n| | SF Symbols | All icons are SF Symbols with bounce, pulse, and replace animations |\n| | Design Tokens | Centralized `PoirotTheme` for colors, spacing, radii, and typography |\n| **Architecture** | Swift 6 | Strict concurrency with `@MainActor` default isolation |\n| | Observation | `@Observable` with `@State` — no `ObservableObject` |\n| | Protocol-Driven DI | Services injected via SwiftUI `EnvironmentValues` |\n| | Provider System | Extensible `ProviderDescribing` protocol for multi-LLM support |\n| | Swift Testing | `@Test`, `#expect`, `#require` with hand-written mocks |\n\n---\n\n## Getting Started\n\n### Install with Homebrew\n\n```bash\nbrew tap leonardocardoso/poirot\nbrew install --cask poirot\n```\n\n### Prerequisites\n\n| Tool | Version | Install |\n|------|---------|---------|\n| macOS | 15.0+ | — |\n| Xcode | 16.0+ | Mac App Store |\n\nInstall SwiftLint and SwiftFormat via Homebrew: `brew install swiftlint swiftformat`.\n\n### Build \u0026 Run\n\n```bash\ngit clone https://github.com/LeonardoCardoso/Poirot.git\ncd Poirot\nbrew install swiftlint swiftformat\nopen Poirot.xcodeproj\n```\n\nHit **\u0026#x2318;R** in Xcode and you're up. Or build from the command line:\n\n```bash\nxcodebuild -scheme Poirot -destination 'platform=macOS' -skipMacroValidation build\n```\n\n### Run Tests\n\n```bash\nxcodebuild test -scheme Poirot -destination 'platform=macOS' -skipMacroValidation\n```\n\nTests use [Swift Testing](https://developer.apple.com/documentation/testing/) (`@Test`, `#expect`, `#require`) — not XCTest.\n\n---\n\n## Architecture\n\n```\nPoirot/Sources/\n├── App/           # Entry point, ContentView, AppState, Settings\n├── Models/        # Value-type structs — Project, Session, Message, ContentBlock\n├── Protocols/     # Service protocols (SessionLoading, ProviderDescribing)\n├── Services/      # Concrete implementations + SwiftUI Environment DI\n│   └── Providers/ # LLM provider configs (ClaudeCodeProvider)\n├── Theme/         # Design tokens (PoirotTheme) + Markdown theme\n├── Utilities/     # Parsers, terminal launcher\n└── Views/         # SwiftUI views organized by feature\n    ├── Components/    # Sidebar, StatusBar, Shimmer\n    ├── Configuration/ # Config dashboard\n    ├── History/       # Prompt history browser\n    ├── Home/          # Welcome / empty state\n    ├── Memory/        # Memory file browser\n    ├── Project/       # Project sessions list\n    ├── Plans/         # Plans browser\n    ├── Search/        # \u0026#x2318;K overlay\n    ├── Session/       # Conversation detail, tool blocks, thinking\n    └── Todos/         # Per-session todo overview\n```\n\n### Tech Stack\n\n| Layer | Choice |\n|-------|--------|\n| Language | Swift 6 with strict concurrency |\n| UI | SwiftUI + Observation (`@Observable`) |\n| Concurrency | `MainActor` default isolation |\n| DI | Protocol-driven services via `EnvironmentValues` |\n| Markdown | [MarkdownUI](https://github.com/gonzalezreal/swift-markdown-ui) |\n| Syntax Highlighting | [HighlightSwift](https://github.com/nicklawls/HighlightSwift) |\n| Linting | SwiftLint (strict profile) |\n| Formatting | SwiftFormat |\n| Testing | Swift Testing with hand-written mocks |\n\n### Design System\n\nPoirot uses a custom dark theme built around a warm golden accent (`#E8A642`) on near-black backgrounds (`#0D0D0F`). All icons are **SF Symbols** with symbol effects (bounce, pulse, replace transitions). Typography scales dynamically with user preference (\u0026#x2318;+/\u0026#x2318;-).\n\nDesign tokens live in [`PoirotTheme.swift`](Poirot/Sources/Theme/PoirotTheme.swift) — colors, spacing, radii, and typography all in one place.\n\n### How It Works\n\n```\n~/.claude/projects/          Poirot reads JSONL transcripts\n        │                    from Claude Code's local storage\n        ▼\n┌─────────────────┐\n│  SessionLoader   │──▶ Discovers projects \u0026 session files\n└────────┬────────┘\n         ▼\n┌─────────────────┐\n│ TranscriptParser │──▶ Parses JSONL into Session/Message models\n└────────┬────────┘\n         ▼\n┌─────────────────┐\n│    AppState      │──▶ Observable state with in-memory caching\n└────────┬────────┘\n         ▼\n┌─────────────────┐\n│   SwiftUI Views  │──▶ Sidebar → Session Detail → Tool Blocks\n└─────────────────┘\n```\n\n---\n\n## Contributing\n\nWe welcome contributions of all sizes — bug fixes, new features, documentation, or just fixing a typo.\n\n### Quick Start\n\n1. Fork the repo\n2. Create a feature branch from `main`\n3. Make your changes with tests\n4. Ensure the build passes with zero warnings\n5. Ensure all tests pass\n6. Ensure SwiftLint passes\n7. Open a PR against `main`\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide on code style, architecture conventions, and testing expectations.\n\n### Code Style at a Glance\n\n- **Swift 6** — All types are implicitly `@MainActor` (no manual annotations needed)\n- **`@Observable`** with `@State` — not `ObservableObject`\n- **SF Symbols only** — No custom icon assets\n- **Swift Testing** — `@Test`, `#expect`, `#require` for all new tests\n- **Hand-written mocks** — In `PoirotTests/Mocks/`, no mocking frameworks\n\n---\n\n## Roadmap\n\nPoirot is early. There's a lot to build and we'd love your help. Track what's planned and in progress on the [issues page](../../issues).\n\n---\n\n## Community\n\n- **Found a bug?** [Open an issue](../../issues)\n- **Have an idea?** [Start a discussion](../../discussions)\n- **Want to contribute?** [Read the guide](CONTRIBUTING.md) and send a PR\n\n---\n\n## Acknowledgments\n\n- Built with [Claude Code](https://claude.ai/code) — the tool this app is built to complement\n- [MarkdownUI](https://github.com/gonzalezreal/swift-markdown-ui) for rich text rendering\n- [HighlightSwift](https://github.com/nicklawls/HighlightSwift) for code syntax highlighting\n- Every SF Symbol that made the UI feel native\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n\nNo tracking. No analytics. Analyze the code yourself, or ask your Claude to do it. :)\n\nMade with coffee and Claude Code in a weekend.\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eIf you find Poirot useful, consider giving it a star. It helps others discover the project.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardocardoso%2Fpoirot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardocardoso%2Fpoirot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardocardoso%2Fpoirot/lists"}