# Poirot

> A native macOS companion for Claude Code that lets you browse sessions, explore diffs, and re-run commands.

- **Type:** MCP server
- **Install:** `agentstack add mcp-a7t-ai-poirot`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [a7t-ai](https://agentstack.voostack.com/s/a7t-ai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [a7t-ai](https://github.com/a7t-ai)
- **Source:** https://github.com/a7t-ai/poirot
- **Website:** https://poirot.fyi

## Install

```sh
agentstack add mcp-a7t-ai-poirot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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](SHOWCASE.md).**

---

## Capabilities

| Category | Feature | Description |
|----------|---------|-------------|
| **Analytics** | Session Analytics Dashboard | Token consumption, cost breakdowns, model distribution, and session trends |
| | Usage Limits | Subscription 5-hour / 7-day rate-limit gauges with reset countdowns; reads Claude Code's existing OAuth token (no login), shown in the dashboard and menu bar |
| **Sessions** | JSONL Transcript Parser | Parses `~/.claude/projects/` transcripts into structured models |
| | Session History Browser | Sessions grouped by project with timestamps, model, token counts |
| | Real-time File Watching | Auto-updates via GCD dispatch sources with 1s debounce |
| | Per-Project Configuration | Supports global (`~/.claude/`) and per-project (`.claude/`) scopes |
| | Session Detail View | Full conversation timeline with collapsible blocks and scroll-to-bottom |
| **Conversation** | Markdown Rendering | Rich text with syntax highlighting via MarkdownUI + HighlightSwift |
| | Code Diff Viewer | Syntax-highlighted inline diffs for Edit tool blocks |
| | Bash Output Renderer | Terminal command output with monospace styling and exit status |
| | Extended Thinking | Collapsible thinking blocks with distinct purple accent |
| | Tool Blocks | Every tool invocation rendered with name, icon, file path, and result |
| | In-Session Search | ⌘F to search within the current conversation |
| **Diagnostics** | Debug Log Viewer | Parse and browse `~/.claude/debug/` logs with color-coded levels, search, filtering, and paginated lazy loading |
| | Auto-scroll to Error | Opens directly at the first error entry for quick triage |
| | Relative Timestamps | Toggle between absolute (HH:mm:ss.SSS) and relative (+offset) time display |
| **History** | Prompt History Browser | Browse `~/.claude/history.jsonl` with date grouping, project filtering, full-text search, and copy-to-clipboard |
| **AI Summaries** | Session Facets | AI-generated analysis (goal, outcome, helpfulness) from `~/.claude/usage-data/facets/` |
| | Outcome & Helpfulness Badges | Color-coded badges for success/partial/failure and helpfulness rating |
| | Goal Categories | Tag chips showing categorized session goals with counts |
| | Friction Indicators | Subtle indicators for tool failures, misunderstandings, and other friction |
| | Live File Watching | Auto-updates when new facets appear via GCD dispatch sources |
| **Search** | Universal Search (⌘K) | Fuzzy search across sessions, AI summaries, history, commands, skills, memory, MCP servers, plugins, output styles, models, sub-agents, plans, TODOs, and debug logs |
| | Grouped Results | Results organized by category with counts |
| | Quick Access | Empty state shows shortcuts, counts, and recent sessions |
| **Configuration** | Commands | Browse and manage slash commands (global and per-project) |
| | Skills | Browse and manage reusable skill modules |
| | MCP Servers | Browse configured Model Context Protocol servers with live connection status |
| | Models | Browse available models and capabilities |
| | Sub-agents | Create, edit, duplicate, and delete custom sub-agents with categorized tool selection and memory configuration |
| | Plugins | Browse installed plugins |
| | Output Styles | Browse and manage output style configurations |
| | Hooks | View and manage event hooks grouped by type with matcher patterns and handler details |
| | TODOs | Browse per-session todo lists with status tracking and session navigation |
| | Plans | Browse `~/.claude/plans/` markdown files with rendered/raw toggle, copy, delete, and file watching |
| | Memory | Browse per-project auto-memory files with rendered markdown, project filtering, and file watching |
| | Grid & List Views | Toggle between card grid and compact list layouts |
| | Scope Badges | Visual distinction between Global and Project-scoped items |
| **Integrations** | IDE/Editor | One-click open files in VS Code, Cursor, Xcode, or Zed |
| | Terminal Selection | Pick your terminal: Terminal, iTerm2, Warp, Ghostty, Kitty, Alacritty |
| | Quick Command Re-run | Click any Bash command to copy or open in your terminal |
| **Export** | Session Export | Export sessions as Markdown or PDF with configurable options |
| | Copy Markdown | One-click copy of session content as Markdown to clipboard |
| | Share Sheet | Native macOS share sheet integration for exported files |
| **Sub-agents** | Custom Agent Creation | Full form with name, description, system prompt, model, color, categorized tools, and persistent memory |
| | Auto File Naming | File path auto-derived from agent name (lowercase, dashes); file renamed on edit |
| | Tool Categories | Select tools by category (Read-only, Edit, Execution, Other) or individually |
| | Agent Memory | Configure persistent memory per agent (global or none) |
| | Import/Export | Share agents as JSON files between users |
| | Duplicate | Clone built-in or custom agents as starting points |
| **Navigation** | Font Scaling | ⌘+ / ⌘- / ⌘0 to zoom the entire UI |
| | Keyboard Shortcuts | Full keyboard navigation with discoverable shortcut hints |
| | Help Book (⌘?) | Keyboard reference, feature overview, and getting started guide |
| **App** | Onboarding Flow | First-run welcome with CLI detection, session discovery, and feature tour |
| | Homebrew Distribution | `brew install --cask poirot` with automated release workflow |
| **Design** | Dark Theme | Warm golden accent (`#E8A642`) on near-black backgrounds |
| | SF Symbols | All icons are SF Symbols with bounce, pulse, and replace animations |
| | Design Tokens | Centralized `PoirotTheme` for colors, spacing, radii, and typography |
| **Architecture** | Swift 6 | Strict concurrency with `@MainActor` default isolation |
| | Observation | `@Observable` with `@State` — no `ObservableObject` |
| | Protocol-Driven DI | Services injected via SwiftUI `EnvironmentValues` |
| | Provider System | Extensible `ProviderDescribing` protocol for multi-LLM support |
| | Swift Testing | `@Test`, `#expect`, `#require` with hand-written mocks |

---

## Getting Started

### Install with Homebrew

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

### Prerequisites

| Tool | Version | Install |
|------|---------|---------|
| macOS | 15.0+ | — |
| Xcode | 16.0+ | Mac App Store |

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

### Build & Run

```bash
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:

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

### Run Tests

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

Tests use [Swift Testing](https://developer.apple.com/documentation/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

| Layer | Choice |
|-------|--------|
| Language | Swift 6 with strict concurrency |
| UI | SwiftUI + Observation (`@Observable`) |
| Concurrency | `MainActor` default isolation |
| DI | Protocol-driven services via `EnvironmentValues` |
| Markdown | [MarkdownUI](https://github.com/gonzalezreal/swift-markdown-ui) |
| Syntax Highlighting | [HighlightSwift](https://github.com/nicklawls/HighlightSwift) |
| Linting | SwiftLint (strict profile) |
| Formatting | SwiftFormat |
| Testing | Swift Testing with hand-written mocks |

### 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`](Poirot/Sources/Theme/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](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](../../issues).

---

## Community

- **Found a bug?** [Open an issue](../../issues)
- **Have an idea?** [Start a discussion](../../discussions)
- **Want to contribute?** [Read the guide](CONTRIBUTING.md) and send a PR

---

## Acknowledgments

- Built with [Claude Code](https://claude.ai/code) — the tool this app is built to complement
- [MarkdownUI](https://github.com/gonzalezreal/swift-markdown-ui) for rich text rendering
- [HighlightSwift](https://github.com/nicklawls/HighlightSwift) for code syntax highlighting
- Every SF Symbol that made the UI feel native

---

## License

MIT — see [LICENSE](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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [a7t-ai](https://github.com/a7t-ai)
- **Source:** [a7t-ai/poirot](https://github.com/a7t-ai/poirot)
- **License:** MIT
- **Homepage:** https://poirot.fyi

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-a7t-ai-poirot
- Seller: https://agentstack.voostack.com/s/a7t-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.