From e02a7568f34ea71915677d5a7cd4c4727aedd4a7 Mon Sep 17 00:00:00 2001
From: miltonvve <milton@vectorverseevole.ai>
Date: Sat, 5 Jul 2025 23:04:18 -0400
Subject: [PATCH 1/2] feat: add comprehensive project-specific CLAUDE.md
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enhanced the generic claude.md template with detailed, project-specific
documentation for Claudia development using KickAss-Claude.md-Builder
principles.

## Key Improvements:

### Project-Specific Context
- Detailed overview of Claudia as a Tauri-based Claude Code GUI toolkit
- Complete technology stack documentation (React 18, Rust, Tauri 2, SQLite)
- Architecture overview with frontend/backend separation
- Target user identification and use cases

### Development Environment Setup
- Platform-specific dependency installation (Linux, macOS, Windows)
- Required tools and versions (Rust 1.70+, Bun, Claude Code CLI)
- Step-by-step setup instructions with commands
- Cross-platform compatibility considerations

### Code Organization Guidelines
- Frontend development patterns (React/TypeScript best practices)
- Backend development patterns (Rust modules and Tauri commands)
- Inter-process communication via Tauri invoke API
- State management strategies for desktop applications

### Technical Documentation
- Complete project structure breakdown
- Database schema and data storage locations
- Integration points (Claude CLI, MCP servers, file system)
- Security considerations for local desktop applications

### Development Workflow
- Build and deployment processes
- Testing strategies for both frontend and backend
- Performance optimization guidelines
- Troubleshooting common development issues

### Contribution Guidelines
- Code style standards for TypeScript and Rust
- Development workflow and PR requirements
- Areas for community contribution
- Claude Code specific development practices

## Benefits:
- Significantly improved developer onboarding experience
- Clear guidance for maintaining cross-platform compatibility
- Comprehensive troubleshooting section for Tauri-specific issues
- Enhanced code quality through documented best practices
- Better integration with Claude Code development workflows

## Generated Using:
- KickAss-Claude.md-Builder enhanced script
- Project analysis of existing codebase and documentation
- Best practices from leading AI coding assistants

This replaces the generic template with actionable, project-specific
guidance that will improve development efficiency and code quality.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 333 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 333 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..aa2af7f0d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,333 @@
+# Claudia - Claude Code GUI Toolkit Development Guide
+
+## 📋 Project 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.
+
+- **Project Type**: Desktop Application (Tauri-based)
+- **Primary Languages**: Rust (Backend), TypeScript/React (Frontend)
+- **Architecture**: Client-side desktop app with local data storage
+- **Target Users**: Developers using Claude Code CLI who want a visual interface
+
+### Key Technologies
+- **Frontend**: React 18 + TypeScript + Vite 6 + Tailwind CSS v4 + shadcn/ui
+- **Backend**: Rust with Tauri 2
+- **Database**: SQLite (via rusqlite) 
+- **Package Manager**: Bun
+- **Build System**: Tauri 2 with Cargo (Rust) and Bun (Frontend)
+
+## 🎯 Core Features & Functionality
+
+### 🗂️ Project & Session Management
+- Visual project browser for `~/.claude/projects/`
+- Session history with full context restoration
+- Smart search for projects and sessions
+- Session insights with metadata display
+
+### 🤖 CC Agents (Custom Claude Agents)
+- Create specialized agents with custom system prompts
+- Agent library management with execution history
+- Background agent execution in separate processes
+- Performance metrics and detailed logs
+
+### 📊 Usage Analytics Dashboard
+- Real-time Claude API usage and cost tracking
+- Token analytics by model, project, and time period
+- Visual charts showing usage trends
+- Data export capabilities for accounting
+
+### 🔌 MCP Server Management
+- Model Context Protocol server registry
+- UI-based server configuration and testing
+- Claude Desktop configuration import
+- Connection health monitoring
+
+### ⏰ Timeline & Checkpoints
+- Session versioning with checkpoint creation
+- Visual timeline navigation with branching
+- Instant checkpoint restoration
+- Session forking and diff viewing
+
+### 📝 CLAUDE.md Management
+- Built-in markdown editor with live preview
+- Project-wide CLAUDE.md file scanning
+- Syntax highlighting and real-time rendering
+
+## 🏗️ Project Structure
+
+```
+claudia/
+├── src/                     # React frontend application
+│   ├── components/          # Reusable UI components
+│   │   ├── ui/             # Base UI primitives (shadcn/ui)
+│   │   ├── AgentExecution.tsx
+│   │   ├── ClaudeCodeSession.tsx
+│   │   ├── MCPManager.tsx
+│   │   ├── Settings.tsx
+│   │   └── UsageDashboard.tsx
+│   ├── lib/                # Utilities and API client
+│   │   ├── api.ts          # Tauri backend communication
+│   │   └── utils.ts        # Helper functions
+│   └── assets/             # Static assets
+├── src-tauri/              # Rust backend (Tauri)
+│   ├── src/
+│   │   ├── commands/       # Tauri command handlers
+│   │   │   ├── agents.rs   # Agent management
+│   │   │   ├── claude.rs   # Claude CLI integration
+│   │   │   ├── storage.rs  # Database operations
+│   │   │   └── usage.rs    # Usage tracking
+│   │   ├── checkpoint/     # Session timeline management
+│   │   └── process/        # Background process management
+│   └── Cargo.toml         # Rust dependencies
+├── scripts/               # Build and automation scripts
+├── cc_agents/            # Pre-built agent configurations
+└── public/               # Static web assets
+```
+
+## 🛠️ Development Environment Setup
+
+### Prerequisites
+1. **Rust** (1.70.0+): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+2. **Bun** (latest): `curl -fsSL https://bun.sh/install | bash`
+3. **Claude Code CLI**: Download from [claude.ai/code](https://claude.ai/code)
+4. **Git**: For version control
+
+### Platform-Specific Dependencies
+
+**Linux (Ubuntu/Debian)**:
+```bash
+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
+xcode-select --install
+brew install pkg-config  # optional
+```
+
+**Windows**:
+- Install Microsoft C++ Build Tools
+- Install WebView2 (pre-installed on Windows 11)
+
+### Development Setup
+```bash
+# Clone repository
+git clone https://github.com/getAsterisk/claudia.git
+cd claudia
+
+# Install frontend dependencies
+bun install
+
+# Start development server (includes frontend + Tauri backend)
+bun run tauri dev
+
+# Alternative: Frontend only
+bun run dev
+```
+
+## 🔧 Development Guidelines
+
+### Code Organization Principles
+- **Frontend**: React components with TypeScript, following functional component patterns
+- **Backend**: Rust modules with clear separation of concerns
+- **State Management**: React hooks for frontend, Tauri state management for backend
+- **Data Flow**: Frontend communicates with Rust backend via Tauri's invoke API
+
+### Key Development Patterns
+
+#### Frontend Development
+- Use TypeScript for all React components
+- Implement error boundaries for robust UI
+- Follow shadcn/ui patterns for consistent styling
+- Use Tailwind CSS for styling with design system consistency
+- Implement proper loading states and error handling
+
+#### Backend Development (Rust)
+- Organize code into logical modules under `src-tauri/src/commands/`
+- Use `#[tauri::command]` for frontend-callable functions
+- Implement proper error handling with Result types
+- Use SQLite for local data persistence
+- Follow Rust best practices for memory safety
+
+#### Inter-Process Communication
+- Frontend calls backend via `invoke<T>(command, args)`
+- Backend functions marked with `#[tauri::command]`
+- Use proper serialization/deserialization with serde
+- Handle async operations properly
+
+### Testing Strategy
+```bash
+# Frontend type checking
+bunx tsc --noEmit
+
+# Rust tests
+cd src-tauri && cargo test
+
+# Format Rust code
+cd src-tauri && cargo fmt
+```
+
+## 🚀 Build and Deployment
+
+### Development Build
+```bash
+bun run tauri dev          # Hot reload development
+```
+
+### Production Build
+```bash
+bun run tauri build        # Creates installers in src-tauri/target/release/bundle/
+bun run tauri build --debug  # Debug build (faster compilation)
+```
+
+### Build Outputs
+- **Linux**: `.deb`, `.AppImage`
+- **macOS**: `.dmg`, `.app`
+- **Windows**: `.msi`, `.exe`
+
+## 📊 Database Schema & Data Management
+
+### SQLite Schema
+- **agents**: Custom agent configurations
+- **agent_runs**: Execution history and metrics
+- **app_settings**: Application configuration
+
+### Data Storage Locations
+- **User Data**: `~/.claude/` directory
+- **Project Data**: `~/.claude/projects/`
+- **Settings**: `~/.claude/settings.json`
+- **Application Database**: Local SQLite in app data directory
+
+## 🔌 Integration Points
+
+### Claude Code CLI Integration
+- Automatic binary detection and version management
+- Process management for background executions
+- Session resumption and state persistence
+- Real-time output streaming and capture
+
+### MCP Server Integration
+- Dynamic server registration and management
+- Configuration import from Claude Desktop
+- Connection testing and health monitoring
+- Protocol compliance validation
+
+### File System Integration
+- Project directory scanning and indexing
+- CLAUDE.md file discovery and management
+- Session transcript storage and retrieval
+- Checkpoint creation and restoration
+
+## 🛡️ Security Considerations
+
+### Local Data Security
+- All data stored locally on user machine
+- No telemetry or data collection
+- Secure handling of Claude API credentials
+- Process isolation for agent executions
+
+### Permission Management
+- Configurable agent permissions per execution
+- File system access controls
+- Network access restrictions
+- Safe command execution practices
+
+## 🐛 Common Development Issues & Solutions
+
+### Build Issues
+1. **"cargo not found"**: Ensure Rust installed and `~/.cargo/bin` in PATH
+2. **"webkit2gtk not found"**: Install required Linux dependencies
+3. **"MSVC not found"**: Install Visual Studio Build Tools on Windows
+4. **"claude command not found"**: Install Claude Code CLI
+
+### Runtime Issues
+1. **Settings not loading**: Check `~/.claude/settings.json` exists and is valid
+2. **Agent execution fails**: Verify Claude CLI installation and permissions
+3. **Database errors**: Check SQLite file permissions and disk space
+4. **MCP connection issues**: Validate server configurations and network access
+
+## 📈 Performance Optimization
+
+### Frontend Performance
+- Implement virtual scrolling for large lists
+- Use React.memo for expensive components
+- Optimize bundle size with code splitting
+- Implement proper caching strategies
+
+### Backend Performance
+- Use async/await for I/O operations
+- Implement connection pooling for database
+- Cache frequently accessed data
+- Optimize SQLite queries with proper indexing
+
+## 🤝 Contributing Guidelines
+
+### Code Style
+- **Rust**: Follow `rustfmt` formatting
+- **TypeScript**: Use Prettier with project config
+- **Commits**: Follow conventional commit format
+- **PRs**: Include tests and documentation updates
+
+### Development Workflow
+1. Fork repository and create feature branch
+2. Implement changes with proper testing
+3. Run linting and type checking
+4. Update documentation as needed
+5. Submit PR with clear description
+
+### Areas for Contribution
+- 🐛 Bug fixes and improvements
+- ✨ New features and enhancements
+- 📚 Documentation improvements
+- 🎨 UI/UX enhancements
+- 🧪 Test coverage expansion
+- 🌐 Internationalization support
+
+## 📝 Claude Code Specific Guidelines
+
+When working on this project with Claude Code:
+
+### Essential Context
+- This is a **desktop application** built with Tauri 2
+- **Primary codebase**: Frontend (React/TS) + Backend (Rust)
+- **Key integration**: Claude Code CLI for AI assistant functionality
+- **Data persistence**: Local SQLite database + file system
+
+### Development Priorities
+1. **Cross-platform compatibility** - ensure features work on Windows, macOS, Linux
+2. **Performance** - desktop app should be responsive and efficient
+3. **User experience** - intuitive GUI for Claude Code power users
+4. **Data safety** - reliable local storage and backup capabilities
+5. **Integration robustness** - handle Claude CLI updates and changes gracefully
+
+### Code Quality Standards
+- Implement proper error handling for both Rust and TypeScript
+- Use TypeScript strictly (no `any` types without justification)
+- Follow Rust ownership and borrowing principles
+- Implement comprehensive logging for debugging
+- Create automated tests for critical functionality
+
+### Architecture Considerations
+- **Frontend-Backend Communication**: Use Tauri's invoke API efficiently
+- **State Management**: Prefer React hooks, avoid complex state libraries unless necessary
+- **Database Operations**: Use transactions for data consistency
+- **File Operations**: Handle permissions and cross-platform path differences
+- **Process Management**: Ensure proper cleanup of background processes
+
+---
+
+*This guide is tailored specifically for Claudia development and should be updated as the project evolves. For general Claude Code best practices, see the standard CLAUDE.md template.*
\ No newline at end of file

From f1df89dae5f8ed39237a35b70bb331cd86df7b1d Mon Sep 17 00:00:00 2001
From: miltonvve <milton@vectorverseevole.ai>
Date: Mon, 21 Jul 2025 13:13:05 -0400
Subject: [PATCH 2/2] Add Claude.md documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 claude.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 claude.md

diff --git a/claude.md b/claude.md
new file mode 100644
index 000000000..fde7e8813
--- /dev/null
+++ b/claude.md
@@ -0,0 +1,167 @@
+# Claude Code Development Guide
+
+This guide contains the best practices extracted from leaked system prompts of leading AI coding assistants including Cursor IDE, GitHub Copilot, Codeium Windsurf, Bolt.new, and others.
+
+## Core Principles
+
+### Immediate Functionality First
+- Generate code that can be executed immediately without modification
+- Address the root cause of problems, not just symptoms  
+- Ensure complete context before making changes
+
+### Collaborative Development
+- Act as a true pair programming partner
+- Explain actions before taking them (but don't mention tool names)
+- Seek user feedback before adding complexity
+
+## Code Quality Standards
+
+### Writing Clean Code
+- Use modular architecture - split functionality into smaller modules
+- Follow consistent naming conventions and formatting
+- Add import statements, dependencies, and endpoints required to run code
+- Create beautiful, modern UI with best UX practices for web applications
+
+### Planning and Structure
+- Think step-by-step and describe plans in pseudocode first
+- Consider the entire project holistically before making changes
+- Group related edits to the same file in a single operation
+- Limit error-fixing iterations to 3 attempts maximum
+
+## Tool Usage Best Practices
+
+### Efficient Tool Selection
+- Prefer semantic search over grep search when available
+- Read larger sections of files at once rather than multiple small calls
+- Use tools only when necessary, not for general knowledge
+- Batch related tool calls together for efficiency
+
+### File Management
+- Always read file contents before editing (unless making small appends)
+- Create appropriate dependency management files (requirements.txt, package.json)
+- Include helpful README files with setup instructions
+- Use imports to connect modules effectively
+
+## Debugging Strategies
+
+### Systematic Debugging
+- Add descriptive logging statements to track variable and code state
+- Create test functions to isolate problems
+- Make code changes only when certain the problem can be solved
+- Address underlying issues rather than surface symptoms
+
+### Error Handling
+- Implement graceful degradation when functionality can't be fully implemented
+- Use clear, user-friendly error messages
+- Document limitations explicitly in both code and communication
+- Follow progressive enhancement principles
+
+## Security Best Practices
+
+### API and Data Security
+- Never hardcode API keys in exposed locations
+- Use environment variables for sensitive configuration
+- Point out API key requirements to users
+- Never create forms for collecting sensitive information
+
+### Code Safety
+- Never run potentially destructive commands automatically
+- Avoid creating code that could be used maliciously
+- Implement proper input validation and sanitization
+- Follow principle of least privilege
+
+## Testing and Validation
+
+### Immediate Testing
+- Execute code yourself to verify functionality
+- Test from the human user's perspective
+- Include version numbers when instructing library installations
+- Ensure code works 100% from user's perspective
+
+### Quality Assurance
+- Run linter and type checking commands when available
+- Verify all dependencies are properly included
+- Test edge cases and error conditions
+- Validate user interface components thoroughly
+
+## Documentation Practices
+
+### Strategic Documentation
+- Leave comments explaining the 'why', not just the 'what'
+- Include usage examples in README files
+- Document security considerations and limitations
+- Provide clear setup and installation instructions
+
+### Change Documentation
+- Explain specific changes made within each modified file
+- Include filenames, function names, and package names
+- Summarize how changes solve the user's task
+- Document any limitations or assumptions
+
+## Communication Guidelines
+
+### User Interaction
+- Never refer to tool names when speaking to users
+- Explain what you're going to do before doing it
+- Communicate limitations and constraints clearly
+- Seek confirmation before making significant changes
+
+### Technical Communication
+- Focus on actionable, technical information
+- Provide specific examples and code snippets
+- Explain complex concepts in understandable terms
+- Offer alternative approaches when appropriate
+
+## Git and Version Control
+
+### Repository Management
+- Be aware of git availability in the environment
+- Follow conventional commit message formats
+- Consider branching strategies for significant changes
+- Keep commits focused and atomic
+
+### Change Management
+- Group related changes logically
+- Test changes before committing
+- Include appropriate commit messages
+- Consider impact on other developers
+
+## Advanced Techniques
+
+### Performance Optimization
+- Consider performance implications of code changes
+- Optimize for readability first, then performance
+- Use appropriate data structures and algorithms
+- Monitor resource usage in applications
+
+### Scalability Considerations
+- Design for future growth and changes
+- Use appropriate architectural patterns
+- Consider maintainability over cleverness
+- Plan for different deployment environments
+
+## Common Pitfalls to Avoid
+
+- Don't loop endlessly trying to fix linter errors
+- Don't create monolithic files - prefer modular design
+- Don't assume libraries are available without checking
+- Don't hardcode sensitive information
+- Don't ignore user feedback and requirements
+- Don't create code that can't be immediately executed
+
+## Key Takeaways
+
+1. **Prioritize immediate functionality** - code must work without modification
+2. **Think holistically** - consider the entire project context
+3. **Communicate clearly** - explain actions and limitations
+4. **Secure by design** - implement security best practices from the start
+5. **Test thoroughly** - verify functionality from user perspective
+6. **Document strategically** - focus on why, not just what
+7. **Iterate carefully** - limit error-fixing loops to prevent infinite cycles
+8. **Modularize consistently** - split functionality into manageable pieces
+9. **Handle errors gracefully** - implement proper error handling and user feedback
+10. **Stay updated** - follow current best practices and conventions
+
+---
+
+*This guide is based on analysis of system prompts from leading AI coding assistants and represents distilled best practices for effective code development and collaboration.*
\ No newline at end of file