Files

Mufeed VH ef1993cff3 docs: correct license reference from MIT to AGPL in README

The README incorrectly stated the project was licensed under MIT,
while the LICENSE file contains AGPL. This commit updates the README
to accurately reflect the AGPL license used by the project.

Fixes #30
Fixes #33

2025-06-23 19:14:02 +05:30

13 KiB

Raw Blame History

Claudia

A powerful GUI app and Toolkit for Claude Code

Create custom agents, manage interactive Claude Code sessions, run secure background agents, and more.

https://github.com/user-attachments/assets/bf0bdf9d-ba91-45af-9ac4-7274f57075cf

Tip

⭐ Star the repo and follow @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.

✨ 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
Secure Execution: Run agents in sandboxed environments with fine-grained permissions
Execution History: Track all agent runs with detailed logs and performance metrics

🛡️ Advanced Sandboxing

OS-Level Security: Platform-specific sandboxing (seccomp on Linux, Seatbelt on macOS)
Permission Profiles: Create reusable security profiles with granular access controls
Violation Tracking: Monitor and log all security violations in real-time
Import/Export: Share sandbox profiles across teams and systems

📊 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

Launch Claudia: Open the application after installation
Welcome Screen: Choose between CC Agents or CC Projects
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

Design Your Agent: Set name, icon, and system prompt
Configure Model: Choose between available Claude models
Set Sandbox Profile: Apply security restrictions
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

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

Rust (1.70.0 or later)

# Install via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Bun (latest version)

# Install bun
curl -fsSL https://bun.sh/install | bash

Git

# Usually pre-installed, but if not:
# Ubuntu/Debian: sudo apt install git
# macOS: brew install git
# Windows: Download from https://git-scm.com

Claude Code CLI
- Download and install from Claude's official site
- Ensure claude is available in your PATH

Platform-Specific Dependencies

Linux (Ubuntu/Debian)

# 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

# Install Xcode Command Line Tools
xcode-select --install

# Install additional dependencies via Homebrew (optional)
brew install pkg-config

Windows

Install Microsoft C++ Build Tools
Install WebView2 (usually pre-installed on Windows 11)

Build Steps

Clone the Repository

git clone https://github.com/getAsterisk/claudia.git
cd claudia

Install Frontend Dependencies
```
bun install
```

Build the Application

For Development (with hot reload)

bun run tauri dev

For Production Build

# Build the application
bun run tauri build

# The built executable will be in:
# - Linux: src-tauri/target/release/bundle/
# - macOS: src-tauri/target/release/bundle/
# - Windows: src-tauri/target/release/bundle/

Platform-Specific Build Options

Debug Build (faster compilation, larger binary)
```
bun run tauri build --debug
```
Build without bundling (creates just the executable)
```
bun run tauri build --no-bundle
```
Universal Binary for macOS (Intel + Apple Silicon)
```
bun run tauri build --target universal-apple-darwin
```

Troubleshooting

Common Issues

"cargo not found" error
- Ensure Rust is installed and ~/.cargo/bin is in your PATH
- Run source ~/.cargo/env or restart your terminal
Linux: "webkit2gtk not found" error
- Install the webkit2gtk development packages listed above
- On newer Ubuntu versions, you might need libwebkit2gtk-4.0-dev
Windows: "MSVC not found" error
- Install Visual Studio Build Tools with C++ support
- Restart your terminal after installation
"claude command not found" error
- Ensure Claude Code CLI is installed and in your PATH
- Test with claude --version
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:

# 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/bundle/.

🛠️ 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
│   │   ├── sandbox/       # Security sandboxing
│   │   └── checkpoint/    # Timeline management
│   └── tests/             # Rust test suite
└── public/                # Public assets

Development Commands

# 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 implements multiple layers of security:

Process Isolation: Agents run in separate sandboxed processes
Filesystem Access Control: Whitelist-based file access
Network Restrictions: Control external connections
Audit Logging: All security violations are logged
No Data Collection: Everything stays local on your machine

🤝 Contributing

We welcome contributions! Please see our Contributing Guide 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 file for details.

🙏 Acknowledgments

Built with Tauri - The secure framework for building desktop apps
Claude by Anthropic

Made with ❤️ by the Asterisk

Report Bug · Request Feature

13 KiB Raw Blame History

Claudia

🌟 Overview

📋 Table of Contents

✨ Features

🗂️ Project & Session Management

🤖 CC Agents

🛡️ Advanced Sandboxing

📊 Usage Analytics Dashboard

🔌 MCP Server Management

⏰ Timeline & Checkpoints

📝 CLAUDE.md Management

📖 Usage

Getting Started

Managing Projects

Creating Agents

Tracking Usage

Working with MCP Servers

🚀 Installation

Prerequisites

Release Executables Will Be Published Soon

🔨 Build from Source

Prerequisites

System Requirements

Required Tools

Platform-Specific Dependencies

Build Steps

Troubleshooting

Common Issues

Verify Your Build

Build Artifacts

🛠️ Development

Tech Stack

Project Structure

Development Commands

🔒 Security

🤝 Contributing

Areas for Contribution

📄 License

🙏 Acknowledgments

Star History

13 KiB

Raw Blame History