Claudiatron

A Powerful Claude Code GUI Desktop Application

Built with Electron + React + TypeScript, providing complete Claude Code integration

中文 | English

🌟 Overview

Claudiatron is a modern desktop application built with Electron + React + TypeScript, serving as a visual GUI for Claude Code. It evolved from the original Tauri version, providing a more comprehensive and stable Claude Code integration experience.

Think of Claudiatron as your command center for Claude Code - bridging the gap between the command-line tool and an intuitive visual interface that makes AI-assisted development more efficient and convenient.

✨ 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

🤖 AI Agents System

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
GitHub Agent Import: Import predefined agent configurations from GitHub

📊 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
Batch Import/Export: Support for bulk configuration import and export

📝 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

🌐 Internationalization

Multi-language Interface: Support for Chinese and English interfaces
Smart Language Detection: Automatically detect and apply system language
Dynamic Switching: Seamlessly switch languages at runtime
Complete Localization: All interface elements are localized

🎨 Modern Interface

Responsive Design: Adapts to different screen sizes and resolutions
Dark/Light Theme: Supports automatic system theme switching
Smooth Animations: Fluid interface animations using Framer Motion
Material Design: Modern component library based on shadcn/ui and Radix UI

📖 Usage

Getting Started

Launch Claudiatron: Open the application after installation
Welcome Screen: Choose between CC Agents or CC Projects
First Time Setup: Claudiatron 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 Permissions: Configure file read/write and network access
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

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

Prerequisites

Claude Code CLI: Install from Claude's official site

Release Downloads

Release executables will be published soon.

🔨 Build from Source

Development Environment

Node.js (18.0.0 or later)

# Install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

pnpm (latest version)
```
# Install pnpm
npm install -g pnpm
```

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

Build Steps

Clone the Repository

git clone https://github.com/Haleclipse/Claudiatron.git
cd Claudiatron

Install Dependencies
```
pnpm install
```

Build the Application

For Development (with hot reload)

pnpm dev

For Production Build

# Build the application
pnpm build

# Platform-specific builds
pnpm build:win     # Windows
pnpm build:mac     # macOS
pnpm build:linux   # Linux

Development Commands

# Start development server
pnpm dev

# Code checking
pnpm lint
pnpm typecheck

# Code formatting
pnpm format

# Build for production
pnpm build

🛠️ Development

Tech Stack

Frontend: React 19 + TypeScript + Vite 6
Backend: Electron + Node.js
UI Framework: Tailwind CSS v4 + shadcn/ui
Database: SQLite (via TypeORM + better-sqlite3)
Package Manager: pnpm
Animations: Framer Motion
Internationalization: react-i18next

Project Structure

claudiatron/
├── src/
│   ├── main/                  # Electron main process
│   │   ├── api/              # IPC API handlers
│   │   ├── database/         # Database layer
│   │   ├── detection/        # Claude detection
│   │   └── process/          # Process management
│   ├── preload/              # Preload scripts
│   └── renderer/             # React renderer process
│       ├── src/
│       │   ├── components/   # UI components
│       │   ├── lib/         # API client & utilities
│       │   ├── i18n/        # Internationalization
│       │   └── types/       # TypeScript types
│       └── assets/          # Static assets
├── build/                    # Build resources
└── dist/                     # Build output

Core Architecture

Main Process: Manages app lifecycle, file system access, child process management
Preload Scripts: Provides secure communication bridge between main and renderer processes
Renderer Process: React application interface, handles user interactions
Database: SQLite stores application data, session history, usage statistics

IPC Communication

The project uses type-safe IPC communication:

// Renderer process calls
const projects = await api.getProjects()
const session = await api.createClaudeSession(projectPath)

// Main process handlers
ipcMain.handle('get-projects', async () => { ... })
ipcMain.handle('create-claude-session', async (_, projectPath) => { ... })

🔒 Security

Claudiatron prioritizes your privacy and security:

Process Isolation: Agents run in separate processes
Permission Control: Configure file and network access per agent
Local Storage: All data stays on your machine
No Telemetry: No data collection or tracking
Open Source: Full transparency through open source code
Sandboxed Environment: Renderer process runs in a restricted environment

🤝 Contributing

We welcome contributions of all kinds!

Areas for Contribution

🐛 Bug fixes and improvements
✨ New features and enhancements
📚 Documentation improvements
🎨 UI/UX enhancements
🧪 Test coverage
🌐 Internationalization

Development Workflow

Fork the project
Create a feature branch
Commit your changes
Open a Pull Request

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Important: This project is based on Claudia, which is licensed under AGPL-3.0. As required by the AGPL-3.0 license terms, all derivative works must maintain the same license.

Built with Electron for modern desktop experiences

Report Bug · Request Feature

csuffyy/Claudiatron