POIROT

Investigating your Claude Code sessions.
A native macOS companion that lets you browse sessions, explore diffs, and re-run commands — all from a polished SwiftUI interface.

Features • Capabilities • Getting Started • Architecture • Contributing • Roadmap

No login. No tracking. No analytics. No BYOK. No extra cost. Works offline. Less than 6 MB.

_{Click to watch the demo on YouTube}

The Story

Poirot 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.

Named 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.

Features

• Session Analytics — Token consumption, cost breakdowns, model distribution, and session trends
• Usage Limits — Live subscription rate-limit gauges (5-hour and 7-day windows) with utilization and reset countdowns, in the dashboard and menu bar — no login, reusing the token Claude Code already stores
• Session History Browser — Sessions grouped by project with timestamps, model info, and token counts
• Rich Conversation View — Full timeline with markdown rendering, syntax highlighting, and collapsible tool blocks
• Tool Block Display — Every tool invocation rendered with name, icon, file path, and result
• Extended Thinking — Collapsible thinking blocks with distinct purple accent
• Fuzzy Search (⌘K) — Spotlight-style search across sessions, commands, file paths, and more
• Slash Commands — Browse global and per-project commands with descriptions and permissions
• Skills — Explore reusable skill modules with parsed frontmatter
• MCP Servers — Live connection status indicators with color-coded SF Symbols
• Models — Browse available models and their capabilities
• Sub-agents — Create, edit, and manage custom sub-agents with tools, model, memory, and system prompt
• Plugins — View installed plugins and their metadata
• Output Styles — Preview output formatting styles
• Hooks — Event hooks grouped by type with matcher patterns and handler details
• Session TODOs — Per-session todo lists with status tracking
• Plans — Browse ~/.claude/plans/ with rendered markdown and file watching
• Debug Log Viewer — Color-coded log levels, search, filtering, and paginated loading
• Prompt History — Browse input history with date grouping and project filtering
• AI Session Summaries — Goal, outcome, helpfulness, and friction indicators from facets
• Memory — Per-project auto-memory files with rendered markdown and live watching

See all features with screenshots in the Feature Showcase.

Capabilities

Getting Started

Install with Homebrew

brew tap a7t-ai/poirot
brew install --cask poirot

Prerequisites

Install SwiftLint and SwiftFormat via Homebrew: brew install swiftlint swiftformat.

Build & Run

git clone https://github.com/a7t-ai/poirot.git
cd Poirot
brew install swiftlint swiftformat
open Poirot.xcodeproj

Hit ⌘R in Xcode and you're up. Or build from the command line:

xcodebuild -scheme Poirot -destination 'platform=macOS' -skipMacroValidation build

Run Tests

xcodebuild test -scheme Poirot -destination 'platform=macOS' -skipMacroValidation

Tests use Swift Testing (@Test, #expect, #require) — not XCTest.

Architecture

Poirot/Sources/
├── App/           # Entry point, ContentView, AppState, Settings
├── Models/        # Value-type structs — Project, Session, Message, ContentBlock
├── Protocols/     # Service protocols (SessionLoading, ProviderDescribing)
├── Services/      # Concrete implementations + SwiftUI Environment DI
│   └── Providers/ # LLM provider configs (ClaudeCodeProvider)
├── Theme/         # Design tokens (PoirotTheme) + Markdown theme
├── Utilities/     # Parsers, terminal launcher
└── Views/         # SwiftUI views organized by feature
    ├── Components/    # Sidebar, StatusBar, Shimmer
    ├── Configuration/ # Config dashboard
    ├── History/       # Prompt history browser
    ├── Home/          # Welcome / empty state
    ├── Memory/        # Memory file browser
    ├── Project/       # Project sessions list
    ├── Plans/         # Plans browser
    ├── Search/        # ⌘K overlay
    ├── Session/       # Conversation detail, tool blocks, thinking
    └── Todos/         # Per-session todo overview

Tech Stack

Design System

Poirot 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 (⌘+/⌘-).

Design tokens live in PoirotTheme.swift — colors, spacing, radii, and typography all in one place.

How It Works

~/.claude/projects/          Poirot reads JSONL transcripts
        │                    from Claude Code's local storage
        ▼
┌─────────────────┐
│  SessionLoader   │──▶ Discovers projects & session files
└────────┬────────┘
         ▼
┌─────────────────┐
│ TranscriptParser │──▶ Parses JSONL into Session/Message models
└────────┬────────┘
         ▼
┌─────────────────┐
│    AppState      │──▶ Observable state with in-memory caching
└────────┬────────┘
         ▼
┌─────────────────┐
│   SwiftUI Views  │──▶ Sidebar → Session Detail → Tool Blocks
└─────────────────┘

Contributing

We welcome contributions of all sizes — bug fixes, new features, documentation, or just fixing a typo.

Quick Start

1. Fork the repo
2. Create a feature branch from main
3. Make your changes with tests
4. Ensure the build passes with zero warnings
5. Ensure all tests pass
6. Ensure SwiftLint passes
7. Open a PR against main

See CONTRIBUTING.md for the full guide on code style, architecture conventions, and testing expectations.

Code Style at a Glance

• Swift 6 — All types are implicitly @MainActor (no manual annotations needed)
• @Observable with @State — not ObservableObject
• SF Symbols only — No custom icon assets
• Swift Testing — @Test, #expect, #require for all new tests
• Hand-written mocks — In PoirotTests/Mocks/, no mocking frameworks

Roadmap

Poirot 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.

Community

• Found a bug? Open an issue
• Have an idea? Start a discussion
• Want to contribute? Read the guide and send a PR

Acknowledgments

• Built with Claude Code — the tool this app is built to complement
• MarkdownUI for rich text rendering
• HighlightSwift for code syntax highlighting
• Every SF Symbol that made the UI feel native

License

MIT — see LICENSE for details.

No tracking. No analytics. Analyze the code yourself, or ask your Claude to do it. :)

Made with coffee and Claude Code in a weekend.

_{If you find Poirot useful, consider giving it a star. It helps others discover the project.}