https://github.com/Haleclipse/Claudiatron
https://github.com/Haleclipse/Claudiatron
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/Haleclipse/Claudiatron
- Owner: Haleclipse
- License: agpl-3.0
- Created: 2025-07-10T20:03:20.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2025-07-11T10:43:36.000Z (3 months ago)
- Last Synced: 2025-07-11T11:44:09.306Z (3 months ago)
- Language: TypeScript
- Size: 1.15 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - **Claudiatron**
README
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.
## π Table of Contents
- [π Overview](#-overview)
- [β¨ Features](#-features)
- [ποΈ Project & Session Management](#οΈ-project--session-management)
- [π€ AI Agents System](#-ai-agents-system)
- [π Usage Analytics Dashboard](#-usage-analytics-dashboard)
- [π MCP Server Management](#-mcp-server-management)
- [π CLAUDE.md Management](#-claudemd-management)
- [π Internationalization](#-internationalization)
- [π¨ Modern Interface](#-modern-interface)
- [π Usage](#-usage)
- [π Installation](#-installation)
- [π¨ Build from Source](#-build-from-source)
- [π οΈ Development](#οΈ-development)
- [π Security](#-security)
- [π€ Contributing](#-contributing)
- [π License](#-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](https://claude.ai/code)
### Release Downloads
Release executables will be published soon.
## π¨ Build from Source
### Development Environment
1. **Node.js** (18.0.0 or later)
```bash
# 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)
```bash
# Install pnpm
npm install -g pnpm
```
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
### Build Steps
1. **Clone the Repository**
```bash
git clone https://github.com/Haleclipse/Claudiatron.git
cd Claudiatron
```
2. **Install Dependencies**
```bash
pnpm install
```
3. **Build the Application**
**For Development (with hot reload)**
```bash
pnpm dev
```
**For Production Build**
```bash
# Build the application
pnpm build
# Platform-specific builds
pnpm build:win # Windows
pnpm build:mac # macOS
pnpm build:linux # Linux
```
### Development Commands
```bash
# 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:
```typescript
// 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](LICENSE) file for details.
**Important**: This project is based on [Claudia](https://github.com/getAsterisk/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.
---