Poirot — Summary

Poirot is a native macOS SwiftUI companion app for Claude Code that reads session transcripts from ~/.claude/projects/, renders them with rich markdown and syntax highlighting, and provides browsing, analytics, search, and configuration management in a polished read-only viewer.

Problem it solves: Claude Code stores all sessions as JSONL files with no native viewer; Poirot parses those files and presents sessions as searchable timelines with token costs, diff viewers, tool-call blocks, AI-generated facets (goal/outcome/helpfulness), and live file watching — all without cloud connectivity.

Distinctive trait: Poirot is entirely read-only for sessions — it never modifies what Claude Code does. Its value is investigation (named after Hercule Poirot, Agatha Christie's detective). The exception is the sub-agent editor, where users can create/edit/delete custom sub-agent definitions stored as .claude/agents/ files.

Tech stack: Swift 6, SwiftUI, macOS 15+, @Observable, XcodeGen-managed project, MarkdownUI + HighlightSwift for rendering, GCD dispatch sources for live file watching. Binary is under 6 MB.

Target audience: Individual Claude Code users on macOS who want a polished companion for reviewing what their agent did — session analytics, debug log browsing, tool-call inspection, and configuration overview — without any workflow methodology imposed.

Production-readiness: 184 stars, MIT license, 3 contributors; actively maintained (pushed May 2026). Available via brew install --cask poirot.

differs_from_seeds: Poirot is a pure read-only session inspector — it adds no methodology, no skills, no hooks, and no commands. Unlike any of the 11 seeds (all of which shape agent behavior), Poirot only visualizes it. The closest seed is ccmemory in that both consume Claude session data, but ccmemory actively writes and queries memory while Poirot only reads.

Poirot — Overview

Origin

Poirot was "vibe-coded in a weekend" by Leonardo Cardoso using Claude Code as co-pilot. From the README:

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

Philosophy

Poirot's philosophy is strict non-interference: it reads Claude Code's data files but never modifies session transcripts, never injects into Claude's reasoning, and never adds to the .claude/ configuration beyond what the user explicitly does through the sub-agent editor.

From the README badge line:

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

This positions Poirot explicitly against tools that require cloud accounts, collect telemetry, or proxy API calls. The binary fits in a single download under 6 MB — a deliberate minimalism statement.

Development discipline

The AI_INSTRUCTIONS.md file (the project's own CLAUDE.md equivalent) is unusually detailed — it prescribes Swift 6 concurrency patterns, SwiftUI state management with @Observable, SF Symbols naming conventions with specific animation types, a design token system (PoirotTheme), and a feature checklist (search integration, live file watching, navigation history). The instructions reference skills (sf-symbols-expert, swiftui-expert-skill, swift-testing-expert) by name — Poirot was itself built with a Claude Code skill-based development methodology.

Design system

• Warm golden accent (#E8A642) on near-black backgrounds
• All icons: SF Symbols with bounce/pulse/replace/breathe/wiggle/rotate animations
• Centralized PoirotTheme design token system
• Accessibility: @Environment(\.accessibilityReduceMotion) guards all animations

Poirot — Architecture

Distribution

• Homebrew Cask: brew install --cask poirot (automated release workflow)
• Source: xcodegen generate && xcodebuild
• Size: < 6 MB binary

Requirements

• macOS 15.0+ (Sonoma)
• No additional runtimes, no Node, no Python, no cloud account

Project structure

Poirot/
├── project.yml                   # XcodeGen project definition
├── AI_INSTRUCTIONS.md            # Development rules (CLAUDE.md equivalent)
├── CLAUDE.md                     # Redirects to AI_INSTRUCTIONS.md
├── Poirot.xcodeproj/             # Generated by XcodeGen
├── Poirot/
│   ├── Resources/                # Assets, fonts, localizations
│   └── Sources/
│       ├── App/                  # App entry points
│       │   ├── PoirotApp.swift
│       │   ├── ContentView.swift
│       │   ├── AppState.swift
│       │   ├── AboutView.swift
│       │   └── SettingsView.swift
│       ├── Models/               # Data models (session, message, tool, config)
│       ├── Protocols/            # Service protocols for DI
│       ├── Services/             # JSONL parsing, file watching, analytics
│       ├── Theme/                # PoirotTheme design tokens
│       ├── Utilities/            # Helpers
│       └── Views/                # SwiftUI views
└── PoirotTests/
    └── Mocks/                    # Hand-written service mocks

Data sources read

Technology choices

• Swift 6 strict concurrency: SWIFT_DEFAULT_ACTOR_ISOLATION: MainActor — all types implicitly @MainActor unless opted out with nonisolated
• State management: @Observable with @State (no legacy ObservableObject)
• DI: Protocol-driven services injected via SwiftUI EnvironmentValues
• Testing: Swift Testing framework (@Suite, @Test, #expect)
• Live updates: GCD dispatch sources with 1 second debounce on file changes
• Markdown rendering: MarkdownUI + HighlightSwift
• Project generation: XcodeGen from project.yml

Poirot — Components

Poirot ships no Claude Code primitives (commands, skills, hooks, MCP). All components are SwiftUI views and service layers.

View modules

Service protocols (DI layer)

• JSONL transcript parser
• File system watcher (GCD)
• Analytics calculator
• AI facets reader
• Configuration file readers (commands, skills, agents, hooks, MCP)
• Export service (Markdown / PDF)

Sub-agents editor

Notable write capability: Poirot can create, edit, duplicate, and delete sub-agent definition files in ~/.claude/agents/ or .claude/agents/. The editor provides:

• Name, description, system prompt fields
• Model selection
• Tool category selection (Read-only, Edit, Execution, Other)
• Memory configuration (global or none)
• Auto file naming from agent name (kebab-case)
• Import/export as JSON

This is the only part of Poirot that modifies .claude/ files.

Poirot — Uniqueness & Positioning

differs_from_seeds

Poirot is a passive read-only viewer — entirely unlike all 11 seed frameworks:

• vs. all methodology seeds (superpowers, BMAD, spec-driver, spec-kit, openspec): Those inject behavior into the agent. Poirot records what the agent did.
• vs. MCP-toolserver seeds (claude-flow, ccmemory, taskmaster-ai): Those extend Claude's capabilities. Poirot only reads what Claude produced.
• vs. markdown-scaffold seeds (claude-conductor, agent-os): Those structure future work. Poirot inspects completed work.
• vs. kiro: kiro is a full IDE. Poirot is a companion to the IDE.

Poirot is most similar to an observability tool — the session equivalent of a log aggregator. Within the batch, it has the richest feature set for pure session investigation.

What makes Poirot distinctive within the GUI desktop batch

Among the 10 batch frameworks, Poirot stands out for:

1. Deepest CC integration: It reads more Claude Code data sources than any other tool — sessions, facets, debug logs, history, plans, memory, hooks, MCP configs, commands, skills, agents, plugins, output styles. The feature matrix is exhaustive.
2. Native Swift performance: Unlike Electron or Tauri competitors, it's < 6 MB with native macOS UI conventions.
3. AI facets display: It surfaces Claude Code's own AI-generated session analysis (goal/outcome/helpfulness) — a feature no other tool in this batch exposes.
4. Sub-agents editor: The only write capability — letting users create custom sub-agents directly from the viewer rather than editing JSONL manually.
5. Development self-documentation: Poirot was built using CC skills and its AI_INSTRUCTIONS.md is a model of how to write agent development guidelines for a native app.

Observable failure modes

1. macOS-only: Swift/SwiftUI limits this to macOS 15+; no Windows/Linux support.
2. JSONL format fragility: If Anthropic changes the session JSONL schema, parsing breaks. There is no versioned schema contract.
3. Feature surface vs. depth: The feature list is extremely long for a 3-contributor project; surface breadth risks maintenance burden.
4. No write-back loop: The sub-agent editor lets users create agents but doesn't provide any way to test them — users must switch to Claude Code terminal.
5. Facets dependency: The AI summaries feature depends on ~/.claude/usage-data/facets/ which is generated by Claude Code's internal background process; if Anthropic removes or changes this, the summaries feature silently stops working.