This project has been ARCHIVED and is planned for a complete rewrite.

This repository is no longer maintained and has been archived. We are planning to rewrite the entire project with a new architecture and modern technologies. Please do not use this codebase for production purposes.

---

---

🌟 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.

📋 Table of Contents

• 🌟 Overview
• ✨ Features
  • 🗂️ Project & Session Management
  • 🤖 AI Agents System
  • 📊 Usage Analytics Dashboard
  • 🔌 MCP Server Management
  • 📝 CLAUDE.md Management
  • 🌐 Internationalization
  • 🎨 Modern Interface
• 📖 Usage
• 🚀 Installation
• 🔨 Build from Source
• 🛠️ Development
• 🔒 Security
• 🤝 Contributing
• 📄 License

✨ 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

1. Launch Claudiatron: Open the application after installation
2. Welcome Screen: Choose between CC Agents or CC Projects
3. 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

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

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

1. 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
   

2. pnpm (latest version)

   # Install pnpm
   npm install -g pnpm
   

3. Git

   # 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
   • Ensure claude is available in your PATH

Build Steps

1. Clone the Repository

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

2. Install Dependencies

   pnpm install
   

3. 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:

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
6. 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

1. Fork the project
2. Create a feature branch
3. Commit your changes
4. 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.

---