https://github.com/user-attachments/assets/bf0bdf9d-ba91-45af-9ac4-7274f57075cf
> [!TIP]
> **โญ Star the repo and follow [@getAsterisk](https://x.com/getAsterisk) on X for early access to `asteria-swe-v0`**.
## ๐ Overview
**Claudia** is a powerful desktop application that transforms how you interact with Claude Code. Built with Tauri 2, it provides a beautiful GUI for managing your Claude Code sessions, creating custom agents, tracking usage, and much more.
Think of Claudia as your command center for Claude Code - bridging the gap between the command-line tool and a visual experience that makes AI-assisted development more intuitive and productive.
## ๐ Table of Contents
- [๐ Overview](#-overview)
- [โจ Features](#-features)
- [๐๏ธ Project & Session Management](#๏ธ-project--session-management)
- [๐ค CC Agents](#-cc-agents)
- [๐ Usage Analytics Dashboard](#-usage-analytics-dashboard)
- [๐ MCP Server Management](#-mcp-server-management)
- [โฐ Timeline & Checkpoints](#-timeline--checkpoints)
- [๐ CLAUDE.md Management](#-claudemd-management)
- [๐ Usage](#-usage)
- [Getting Started](#getting-started)
- [Managing Projects](#managing-projects)
- [Creating Agents](#creating-agents)
- [Tracking Usage](#tracking-usage)
- [Working with MCP Servers](#working-with-mcp-servers)
- [๐ Installation](#-installation)
- [๐จ Build from Source](#-build-from-source)
- [๐ ๏ธ Development](#๏ธ-development)
- [๐ Security](#-security)
- [๐ค Contributing](#-contributing)
- [๐ License](#-license)
- [๐ Acknowledgments](#-acknowledgments)
## โจ Features
### ๐๏ธ **Project & Session Management**
- **Visual Project Browser**: Navigate through all your Claude Code projects in `~/.claude/projects/`
- **Session History**: View and resume past coding sessions with full context
- **Smart Search**: Find projects and sessions quickly with built-in search
- **Session Insights**: See first messages, timestamps, and session metadata at a glance
### ๐ค **CC Agents**
- **Custom AI Agents**: Create specialized agents with custom system prompts and behaviors
- **Agent Library**: Build a collection of purpose-built agents for different tasks
- **Background Execution**: Run agents in separate processes for non-blocking operations
- **Execution History**: Track all agent runs with detailed logs and performance metrics
### ๐ **Usage Analytics Dashboard**
- **Cost Tracking**: Monitor your Claude API usage and costs in real-time
- **Token Analytics**: Detailed breakdown by model, project, and time period
- **Visual Charts**: Beautiful charts showing usage trends and patterns
- **Export Data**: Export usage data for accounting and analysis
### ๐ **MCP Server Management**
- **Server Registry**: Manage Model Context Protocol servers from a central UI
- **Easy Configuration**: Add servers via UI or import from existing configs
- **Connection Testing**: Verify server connectivity before use
- **Claude Desktop Import**: Import server configurations from Claude Desktop
### โฐ **Timeline & Checkpoints**
- **Session Versioning**: Create checkpoints at any point in your coding session
- **Visual Timeline**: Navigate through your session history with a branching timeline
- **Instant Restore**: Jump back to any checkpoint with one click
- **Fork Sessions**: Create new branches from existing checkpoints
- **Diff Viewer**: See exactly what changed between checkpoints
### ๐ **CLAUDE.md Management**
- **Built-in Editor**: Edit CLAUDE.md files directly within the app
- **Live Preview**: See your markdown rendered in real-time
- **Project Scanner**: Find all CLAUDE.md files in your projects
- **Syntax Highlighting**: Full markdown support with syntax highlighting
## ๐ Usage
### Getting Started
1. **Launch Claudia**: Open the application after installation
2. **Welcome Screen**: Choose between CC Agents or CC Projects
3. **First Time Setup**: Claudia will automatically detect your `~/.claude` directory
### Managing Projects
```
CC Projects โ Select Project โ View Sessions โ Resume or Start New
```
- Click on any project to view its sessions
- Each session shows the first message and timestamp
- Resume sessions directly or start new ones
### Creating Agents
```
CC Agents โ Create Agent โ Configure โ Execute
```
1. **Design Your Agent**: Set name, icon, and system prompt
2. **Configure Model**: Choose between available Claude models
3. **Set Permissions**: Configure file read/write and network access
4. **Execute Tasks**: Run your agent on any project
### Tracking Usage
```
Menu โ Usage Dashboard โ View Analytics
```
- Monitor costs by model, project, and date
- Export data for reports
- Set up usage alerts (coming soon)
### Working with MCP Servers
```
Menu โ MCP Manager โ Add Server โ Configure
```
- Add servers manually or via JSON
- Import from Claude Desktop configuration
- Test connections before using
## ๐ Installation
### Prerequisites
- **Claude Code CLI**: Install from [Claude's official site](https://claude.ai/code)
### Release Executables Will Be Published Soon
## ๐จ Build from Source
### Prerequisites
Before building Claudia from source, ensure you have the following installed:
#### System Requirements
- **Operating System**: Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+)
- **RAM**: Minimum 4GB (8GB recommended)
- **Storage**: At least 1GB free space
#### Required Tools
1. **Rust** (1.70.0 or later)
```bash
# Install via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
2. **Bun** (latest version)
```bash
# Install bun
curl -fsSL https://bun.sh/install | bash
```
3. **Git**
```bash
# Usually pre-installed, but if not:
# Ubuntu/Debian: sudo apt install git
# macOS: brew install git
# Windows: Download from https://git-scm.com
```
4. **Claude Code CLI**
- Download and install from [Claude's official site](https://claude.ai/code)
- Ensure `claude` is available in your PATH
#### Platform-Specific Dependencies
**Linux (Ubuntu/Debian)**
```bash
# Install system dependencies
sudo apt update
sudo apt install -y \
libwebkit2gtk-4.1-dev \
libgtk-3-dev \
libayatana-appindicator3-dev \
librsvg2-dev \
patchelf \
build-essential \
curl \
wget \
file \
libssl-dev \
libxdo-dev \
libsoup-3.0-dev \
libjavascriptcoregtk-4.1-dev
```
**macOS**
```bash
# Install Xcode Command Line Tools
xcode-select --install
# Install additional dependencies via Homebrew (optional)
brew install pkg-config
```
**Windows**
- Install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
- Install [WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) (usually pre-installed on Windows 11)
### Build Steps
1. **Clone the Repository**
```bash
git clone https://github.com/getAsterisk/claudia.git
cd claudia
```
2. **Install Frontend Dependencies**
```bash
bun install
```
3. **Build the Application**
**For Development (with hot reload)**
```bash
bun run tauri dev
```
**For Production Build**
```bash
# Build the application
bun run tauri build
# The built executable will be in:
# - Linux: src-tauri/target/release/
# - macOS: src-tauri/target/release/
# - Windows: src-tauri/target/release/
```
4. **Platform-Specific Build Options**
**Debug Build (faster compilation, larger binary)**
```bash
bun run tauri build --debug
```
**Universal Binary for macOS (Intel + Apple Silicon)**
```bash
bun run tauri build --target universal-apple-darwin
```
### Troubleshooting
#### Common Issues
1. **"cargo not found" error**
- Ensure Rust is installed and `~/.cargo/bin` is in your PATH
- Run `source ~/.cargo/env` or restart your terminal
2. **Linux: "webkit2gtk not found" error**
- Install the webkit2gtk development packages listed above
- On newer Ubuntu versions, you might need `libwebkit2gtk-4.0-dev`
3. **Windows: "MSVC not found" error**
- Install Visual Studio Build Tools with C++ support
- Restart your terminal after installation
4. **"claude command not found" error**
- Ensure Claude Code CLI is installed and in your PATH
- Test with `claude --version`
5. **Build fails with "out of memory"**
- Try building with fewer parallel jobs: `cargo build -j 2`
- Close other applications to free up RAM
#### Verify Your Build
After building, you can verify the application works:
```bash
# Run the built executable directly
# Linux/macOS
./src-tauri/target/release/claudia
# Windows
./src-tauri/target/release/claudia.exe
```
### Build Artifacts
The build process creates several artifacts:
- **Executable**: The main Claudia application
- **Installers** (when using `tauri build`):
- `.deb` package (Linux)
- `.AppImage` (Linux)
- `.dmg` installer (macOS)
- `.msi` installer (Windows)
- `.exe` installer (Windows)
All artifacts are located in `src-tauri/target/release/`.
## ๐ ๏ธ Development
### Tech Stack
- **Frontend**: React 18 + TypeScript + Vite 6
- **Backend**: Rust with Tauri 2
- **UI Framework**: Tailwind CSS v4 + shadcn/ui
- **Database**: SQLite (via rusqlite)
- **Package Manager**: Bun
### Project Structure
```
claudia/
โโโ src/ # React frontend
โ โโโ components/ # UI components
โ โโโ lib/ # API client & utilities
โ โโโ assets/ # Static assets
โโโ src-tauri/ # Rust backend
โ โโโ src/
โ โ โโโ commands/ # Tauri command handlers
โ โ โโโ checkpoint/ # Timeline management
โ โ โโโ process/ # Process management
โ โโโ tests/ # Rust test suite
โโโ public/ # Public assets
```
### Development Commands
```bash
# Start development server
bun run tauri dev
# Run frontend only
bun run dev
# Type checking
bunx tsc --noEmit
# Run Rust tests
cd src-tauri && cargo test
# Format code
cd src-tauri && cargo fmt
```
## ๐ Security
Claudia prioritizes your privacy and security:
1. **Process Isolation**: Agents run in separate processes
2. **Permission Control**: Configure file and network access per agent
3. **Local Storage**: All data stays on your machine
4. **No Telemetry**: No data collection or tracking
5. **Open Source**: Full transparency through open source code
## ๐ค Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Areas for Contribution
- ๐ Bug fixes and improvements
- โจ New features and enhancements
- ๐ Documentation improvements
- ๐จ UI/UX enhancements
- ๐งช Test coverage
- ๐ Internationalization
## ๐ License
This project is licensed under the AGPL License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- Built with [Tauri](https://tauri.app/) - The secure framework for building desktop apps
- [Claude](https://claude.ai) by Anthropic
---
