# Conan

> A native macOS desktop app that wraps Claude Code in a live HUD, surfacing every prompt, tool call, skill, and token as it happens.

Conan is a native macOS desktop application built by thewhatmatters that wraps Claude Code in a real-time observability cockpit. It puts an `xterm.js` terminal front-and-center alongside a widget HUD showing context, usage, pulse, skills, and MCP servers — all backed by a loopback Node gateway packaged as a Tauri sidecar. The latest release is v1.0.5, published June 14, 2026.

## What It Is

Conan is a terminal-primary desktop app in the AI coding assistant and agent observability category. Its core job is to make Claude Code sessions fully transparent: instead of watching a scrolling terminal, users see a live timeline of every prompt, tool call, skill firing, and token burn as the agent works. It is built with Tauri v2, React 19, TypeScript, and Tailwind v4, and ships as a signed `.dmg` for Apple silicon Macs running macOS 13 or later.

## How the HUD Works

The app is organized around a VS-Code-style tab strip of terminals, each with its own `node-pty` process running `claude` in the active working directory. An optional Timeline split panel docks to the right of each terminal tab and shows a chronological log of hook events, skill firings (including heuristic "considered but didn't fire" reasons scored via BM25), TodoWrite/ExitPlanMode plan rows, and `/loop` cadence. A drag-resizable HUD panel provides five widget tabs:

- **Context** — live `/context` breakdown with a progress gauge, auto-refresh toggle, and a context-pressure toolbar that can trigger `/handoff` at ≥95% fill.
- **Usage** — the `/usage` session block and all three rate-limit windows, captured from the live pty.
- **Pulse** — a stacked area chart of activity throughput over 15m/1h/6h/24h windows.
- **Skills** — installed skills with name, description, and last-fired timestamp, grouped User/System.
- **MCP** — configured MCP servers with live health status from `claude mcp list`.

## Architecture and Stack

The gateway is a TypeScript ESM process (Express 4 + `ws` + `better-sqlite3` + `node-pty`) that binds loopback-only on port 3747. It exposes a REST API and two authenticated WebSockets — one for hook events and session data, one for the terminal pty. Authentication uses a token plus an Origin allowlist to prevent cross-site WebSocket hijacking (CVE-2025-52882). The Tauri v2 crate spawns the gateway as a bundled-node sidecar on launch and kills it on quit. Storage is SQLite (WAL) at `.data/conan.db`.

## Skills and MCP Observability

Conan surfaces the skills and MCP servers that Claude Code has in play during a session. The Skills tab shows each installed skill's name, description (from `SKILL.md`), source path, and last-fired timestamp. The Timeline panel shows not just when a skill fired but also when it was *considered* and why it didn't fire — using a BM25 heuristic match against each skill's description. MCP servers show connected, failed, or needs-auth status with a manual refresh.

## Update: Conan 1.0.5

The latest release, v1.0.5 (June 14, 2026), follows a series of rapid iterations. The v4.x series introduced the Tauri-only architecture (v4.2 removed the web-served UI and headless drive routes), added per-terminal Timeline split panels with skill-considered rows and plan rows (v4.5), and grew the route surface back deliberately in v4.3/v4.4. The roadmap documents (`docs/v4.7-licensing-design.md` and `docs/v4.7-update-design.md`) describe upcoming Ed25519 JWT offline licensing via Polar.sh and a Tauri-plugin-updater auto-update path hosted on Cloudflare R2. Windows and Linux support is listed as planned, with a waitlist on the homepage.

## Features
- Live streaming timeline of every prompt, tool call, and skill firing
- Context window breakdown with per-category token usage and auto-refresh
- Usage rate-limit window tracking captured from live pty
- Pulse throughput chart (15m/1h/6h/24h)
- Skills tab with last-fired timestamps and BM25 heuristic match reasons
- MCP server health monitoring (connected/failed/needs-auth)
- xterm.js terminal with VS-Code-style multi-tab support
- Context-pressure toolbar with /handoff trigger at ≥95% fill
- Claude Radio built-in ambient audio streaming
- Native macOS notifications when Claude is waiting for input
- Settings dialog with editable Claude config
- SQLite-backed session and event storage
- Loopback-only authenticated WebSocket gateway

## Integrations
Claude Code, Anthropic Claude, MCP (Model Context Protocol) servers, Playwright (via automate-browser skill), Polar.sh (licensing/payments)

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Freemium — Free tier available with paid upgrades

## Version
1.0.5

## Links
- Website: https://conan.sh
- Documentation: https://github.com/thewhatmatters/conan
- Repository: https://github.com/thewhatmatters/conan
- EveryDev.ai: https://www.everydev.ai/tools/conan-claude-code-hud