Claudia

Claude Code, but pretty

Claude Code is powerful. The terminal is not where you want to live. Claudia wraps the CLI in a native macOS app so you keep everything—MCPs, CLAUDE.md files, hooks, session persistence—and gain a visual interface that doesn't hurt to look at.

Why rebuild the agent runtime when you can wrap it?

Requires macOS 12+ and Claude Code CLI installed

Screenshots

Parallel subagents running with real-time status tracking

Plan mode with task panel and detailed plan view

Interactive questions with multiple choice options

Note: Claudia is a personal project, provided as-is with no warranty or guaranteed support. Use at your own risk. Bug reports are welcome, but responses and fixes are best-effort.

Why Claudia?

Claude Code CLI is powerful but terminal-focused. Claudia gives you:

• Proportional fonts and styling — Who wants to stare at monospaced text all day
• Visual tool tracking — See what Claude is doing with collapsible, syntax-highlighted tool blocks
• Real-time streaming — Text and results appear as they're generated
• Desktop integration — Native macOS app, multi-window support, project-aware launching
• All of Claude Code's power — MCPs, skills, hooks, CLAUDE.md, session persistence, prompt caching

Why Claudia instead of Cowork?

Cowork is Anthropic's managed desktop experience—great for users who want zero-config simplicity. Claudia is for developers who already use Claude Code and want more control:

• Fully customizable — UI, workflows, features, and memory are yours to modify
• Per-project configuration — different context, tools, and MCPs for each project directory
• Your setup just works — existing CLAUDE.md files, hooks, and MCP configs carry over
• Direct file system access — no sandboxed VM sitting between you and your files
• Custom visualizations — build data renderers directly into your MCPs

Cowork wraps a sandboxed environment. Claudia wraps Claude Code itself—so you keep everything you've already built.

Features

• Native macOS app — Built with Tauri + SolidJS for fast, lightweight performance
• Rich markdown rendering — Full GitHub-flavored markdown with syntax-highlighted code blocks
• Inline image display — Images from Read tool results display inline, click to view full-size
• Visual tool tracking — Collapsible, syntax-highlighted tool blocks with JSON formatting
• Real-time streaming — Text and results appear as they're generated
• CLI launcher — Run claudia from any directory to use project-specific configs
• Multi-instance support — Multiple windows, each in different project directories
• Type-ahead input — Keep typing while waiting for responses
• Smart permissions — Auto-approve, plan mode, or per-tool dialogs
• Extended thinking — Expandable thinking blocks when enabled
• Subagent visualization — Track nested Task agents and their progress
• Session resume — Continue previous conversations with full context

Installation

Download (Recommended)

Download the latest release and drag Claudia.app to your Applications folder:

⬇ Download Claudia for macOS

Requires macOS 12+ and Claude Code CLI installed.

Build from Source

If you prefer to build from source, you'll need:

• Node.js 18+
• Rust toolchain
• Claude Code CLI (claude command available)

git clone https://github.com/JasonBates/claudia.git
cd claudia
npm install
npm run tauri build
cp -R src-tauri/target/release/bundle/macos/Claudia.app /Applications/

CLI Launcher

Install the claudia CLI launcher to open the app from any directory:

./install.sh

Or manually:

cp claudia ~/.local/bin/
chmod +x ~/.local/bin/claudia

Then from any project directory:

cd ~/Code/repos/my-project
claudia

This opens Claudia with that directory as the working directory, picking up project-specific .claude/ configs.

Usage

Keyboard Shortcuts

Commands

Resuming Sessions

1. Via sidebar: Press ⌘ ⇧ [ or type /resume to open the session sidebar
2. Via CLI: Launch with claudia --resume <session-id>
3. Browse history: The sidebar shows recent sessions with timestamps and previews

Custom Color Schemes

Claudia includes 6 bundled color schemes (Solarized Dark/Light, Dracula, Nord, One Dark, Gruvbox Dark). You can add more by installing iTerm2 color scheme files.

To install new color schemes:

1. Create the colors directory if it doesn't exist:

   mkdir -p ~/.config/iterm2/colors
   

2. Copy .itermcolors files into the directory:

   cp "My Theme.itermcolors" ~/.config/iterm2/colors/
   

3. Open Settings (⌘ ,) — your new schemes appear under "From iTerm2"

Where to find color schemes:

• iTerm2-Color-Schemes — 250+ schemes in the schemes/ directory
• Any .itermcolors file from the web will work

Note: iTerm2 does not need to be installed. Claudia reads the .itermcolors plist format directly.

Advanced Runtime Config

You can override model and runtime binaries in ~/.config/claudia/config.json (or per-project at .claudia/config.json):

{
  "claude_model": "opus",
  "claude_binary_path": "/opt/homebrew/bin/claude",
  "node_binary_path": "/opt/homebrew/bin/node",
  "legacy_permission_hook_polling": false
}

• claude_model: Passed to Claude CLI as --model
• claude_binary_path: Optional explicit path to Claude CLI
• node_binary_path: Optional explicit Node path used to launch the bridge
• legacy_permission_hook_polling: Enables legacy file-based permission flow (off by default)

Architecture

Claudia wraps the Claude Code CLI to leverage its built-in features (MCPs, skills, hooks, session management, prompt caching) while providing a custom native UI.

┌─────────────────────────────────────────────────────────────────┐
│                      Claudia.app (Tauri)                        │
│              Custom UI + Desktop Integration                    │
├─────────────────────────────────────────────────────────────────┤
│  Frontend (SolidJS)          │  Backend (Rust)                  │
│  └─ Reactive UI components   │  └─ Process management, IPC      │
├─────────────────────────────────────────────────────────────────┤
│                     sdk-bridge-v2.mjs (Node.js)                 │
│                     └─ Thin event translation layer             │
├─────────────────────────────────────────────────────────────────┤
│                     Claude Code CLI                             │
│         └─ Full agent runtime: MCPs, skills, hooks,             │
│            sessions, compaction, prompt caching                 │
└─────────────────────────────────────────────────────────────────┘

For detailed architecture, data flow, event types, and implementation details, see docs/architecture.md.

Development

# Development mode
npm run tauri dev

# Run all tests (608 tests: 113 Rust + 495 TypeScript)
npm run test:all

# TypeScript tests only
npm run test:run

# Rust tests only
npm run test:rust

Documentation

License

MIT