{"id":31274110,"url":"https://github.com/linux-brat/bclicker","last_synced_at":"2025-09-23T22:36:37.623Z","repository":{"id":314774540,"uuid":"1056709385","full_name":"linux-brat/BClicker","owner":"linux-brat","description":"A professional Rust-based auto-clicker with a sleek Terminal User Interface","archived":false,"fork":false,"pushed_at":"2025-09-14T17:04:41.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T18:41:44.186Z","etag":null,"topics":["auto-clicker","cps","linux","powershell","rust","rust-crate","rust-lang","tui","windows"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linux-brat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T16:42:44.000Z","updated_at":"2025-09-14T17:07:31.000Z","dependencies_parsed_at":"2025-09-14T18:41:53.751Z","dependency_job_id":"3716c3ca-912d-44d7-a7dc-13894cfcd6c8","html_url":"https://github.com/linux-brat/BClicker","commit_stats":null,"previous_names":["linux-brat/bclicker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/linux-brat/BClicker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-brat%2FBClicker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-brat%2FBClicker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-brat%2FBClicker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-brat%2FBClicker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-brat","download_url":"https://codeload.github.com/linux-brat/BClicker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-brat%2FBClicker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276662196,"owners_count":25682027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto-clicker","cps","linux","powershell","rust","rust-crate","rust-lang","tui","windows"],"created_at":"2025-09-23T22:36:34.831Z","updated_at":"2025-09-23T22:36:37.612Z","avatar_url":"https://github.com/linux-brat.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n\n# BClicker Professional\n\n[![GitHub release](https://img.shields.io/github/v/release/linux-brat/BClicker?include_prereleases\u0026style=for-the-badge\u0026color=blue)](https://github.com/linux-brat/BClicker/releases)\n[![GitHub license](https://img.shields.io/github/license/linux-brat/BClicker?style=for-the-badge\u0026color=green)](https://github.com/linux-brat/BClicker/blob/main/LICENSE)\n[![Rust](https://img.shields.io/badge/Rust-2025-orange?style=for-the-badge\u0026logo=rust)](https://www.rust-lang.org/)\n[![WARP](https://img.shields.io/badge/WARP-Compatible-purple?style=for-the-badge)](https://warp.dev)\n\n**A professional Rust-based auto-clicker with a sleek Terminal User Interface**\n\n\u003cimg src=\"screenshot/ss.png\" alt=\"BClicker Screenshot\"\u003e\n\n\u003c/div\u003e\n\n## 🚀 Project Overview\n\nBClicker Professional is a high-performance auto-clicker application with a TUI (Terminal User Interface) built using crossterm and tui-rs. The application provides professional auto-clicking functionality with global hotkey support, system tray integration, audio feedback, and statistics tracking.\n\n## ✨ Key Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎮 Core Features\n\n- 🖱️ **High-Precision Clicking**: Microsecond-accurate timing\n- ⌨️ **Global Hotkeys**: Control from anywhere (Windows)\n- 🎨 **Beautiful TUI**: Terminal-based interface\n- 📈 **Statistics Tracking**: Monitor your usage\n- 🔊 **Audio Feedback**: Optional click sounds\n- 📱 **System Tray**: Background operation\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### ⚙️ Technical Features\n\n- 🏁 **Multi-threaded**: Non-blocking performance\n- 📋 **TOML Configuration**: Human-readable settings\n- 🔔 **Cross-platform**: Windows \u0026 Linux support\n- 📦 **Portable**: Single executable\n- 🚪 **Zero Dependencies**: Standalone operation\n- 🔒 **Memory Safe**: Rust guarantees\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🛠️ Technology Stack\n\n| Component            | Technology          | Purpose                              |\n| -------------------- | ------------------- | ------------------------------------ |\n| 🦀 **Language**      | Rust (2025 edition) | High-performance systems programming |\n| 🖥️ **UI Framework**  | tui-rs + crossterm  | Terminal-based user interface        |\n| 🖱️ **Mouse Control** | enigo               | Cross-platform mouse automation      |\n| 🔊 **Audio**         | rodio               | Non-blocking sound effects           |\n| ⚙️ **Configuration** | TOML + serde        | Human-readable config files          |\n| 📱 **System Tray**   | tray-item           | Background system integration        |\n| 🔔 **Notifications** | notify-rust         | Cross-platform notifications         |\n| 🪟 **Platform**      | Windows + Win32 API | Global hotkey support                |\n\n---\n\n## ⚡ Quick Start (TL;DR)\n\n```bash\n# 🚀 Get up and running in 30 seconds!\ngit clone https://github.com/linux-brat/BClicker.git\ncd BClicker\ncargo run --release\n```\n\n**🎮 Controls:**\n\n- `Space` - Start/Stop clicking\n- `Tab` - Switch between presets\n- `h` - Help menu\n- `q` - Quit\n\n\u003e 💫 **WARP Users**: This works perfectly in WARP terminal with full Unicode support and beautiful rendering!\n\n---\n\n## 📦 Detailed Installation\n\n### 🔧 Prerequisites\n\n- 🦀 **Rust toolchain**: Install from [rustup.rs](https://rustup.rs/)\n- 📋 **Git**: For cloning the repository\n- 🪟 **Windows**: Windows SDK for global hotkey functionality\n- 🐧 **Linux**: Audio development libraries (ALSA/PulseAudio)\n\n---\n\n### 💻 One-Click Installation\n\n#### 🪟 Windows (PowerShell)\n\n```powershell\n# 🚀 Quick Setup - Copy \u0026 Paste!\ngit clone https://github.com/linux-brat/BClicker.git\ncd BClicker\ncargo build --release\n\n# ▶️ Run BClicker\n.\\target\\release\\bclicker.exe\n\n# 🌍 Optional: Add to PATH for global access\n# Copy target\\release\\bclicker.exe to C:\\Windows\\System32\\ or your preferred PATH directory\n```\n\n\u003e **📝 Note**: Replace `bclicker.exe` with the actual executable name if different\n\n#### 🐧 Linux (Bash)\n\n```bash\n# 📦 Install audio libraries (Ubuntu/Debian)\nsudo apt update \u0026\u0026 sudo apt install libasound2-dev pkg-config\n\n# 🎆 For other distributions:\n# Fedora: sudo dnf install alsa-lib-devel pkgconf\n# Arch: sudo pacman -S alsa-lib pkgconf\n\n# 🚀 Quick Setup - Copy \u0026 Paste!\ngit clone https://github.com/linux-brat/BClicker.git\ncd BClicker\ncargo build --release\n\n# ▶️ Run BClicker\n./target/release/bclicker\n\n# 🌍 Optional: Install system-wide\nsudo cp target/release/bclicker /usr/local/bin/\n```\n\n### 📦 Direct Cargo Installation\n\n```bash\n# 🚀 Install directly from GitHub\ncargo install --git https://github.com/linux-brat/BClicker.git\n\n# 🎆 Or install from crates.io (when published)\ncargo install bclicker\n```\n\n---\n\n## ⚙️ WARP Development Commands\n\n\u003e 💡 **WARP Users**: These commands work perfectly in WARP terminal with syntax highlighting and autocompletion!\n\n### 🔨 Build \u0026 Run Commands\n\n| Command                 | Description                | WARP Tip                                                     |\n| ----------------------- | -------------------------- | ------------------------------------------------------------ |\n| `cargo build`           | 🚀 Debug build             | 📝 Use WARP's AI to explain any build errors                 |\n| `cargo build --release` | ⚡ Optimized release build | 📊 View build progress in WARP's enhanced output             |\n| `cargo run`             | ▶️ Run in debug mode       | 🔍 Perfect for development with WARP's terminal multiplexing |\n| `cargo run --release`   | 🏁 Run optimized version   | ⚙️ Best performance for testing                              |\n\n```bash\n# 🚀 Quick Development Cycle\ncargo run          # Fast compilation, debug info\ncargo run --release # Optimized performance\n```\n\n### 🧪 Testing \u0026 Code Quality\n\n| Command                       | Purpose              | WARP Feature                          |\n| ----------------------------- | -------------------- | ------------------------------------- |\n| `cargo test`                  | 🧪 Run all tests     | 📈 Test results beautifully formatted |\n| `cargo check`                 | ⚙️ Fast syntax check | ⚡ Lightning-fast feedback loop       |\n| `cargo fmt`                   | 🎨 Format code       | 📝 Instant code beautification        |\n| `cargo clippy`                | 🔍 Lint analysis     | 💡 Smart suggestions in WARP          |\n| `cargo clippy -- -D warnings` | 🛡️ Strict linting    | 🚫 Zero tolerance for warnings        |\n\n```bash\n# 🚀 Code Quality Pipeline\ncargo check      # Quick syntax validation\ncargo fmt        # Auto-format code\ncargo clippy     # Catch common issues\ncargo test       # Ensure everything works\n```\n\n### 🛠️ Development Utilities\n\n```bash\n# 🧼 Clean build artifacts\ncargo clean\n\n# 🆕 Update dependencies\ncargo update\n\n# 🌳 Show dependency tree\ncargo tree\n\n# 🔒 Security audit (install with: cargo install cargo-audit)\ncargo audit\n\n# 📂 Generate documentation\ncargo doc --open\n\n# 📈 Performance profiling\ncargo build --release\ntime ./target/release/bclicker\n```\n\n\u003e 💫 **WARP Pro Tip**: Use WARP's AI assistant to explain any cargo commands or help debug build issues!\n\n## Architecture Overview\n\n### Core Application Structure\n\nThe application follows a modular architecture with clear separation of concerns:\n\n**Main Components:**\n\n1. **App State Management** (`App` struct) - Central application state, configuration, and UI modes\n2. **Event System** - Multi-threaded event handling for input, ticking, and quit signals\n3. **Auto-Clicker Engine** - Dedicated thread for mouse clicking with precise timing\n4. **UI Rendering** - TUI-based interface with dynamic content and help system\n5. **System Integration** - Global hotkeys, system tray, and notifications\n\n### Key Data Structures\n\n**Configuration System:**\n\n- `Config` struct handles all persistent settings\n- `Statistics` struct tracks usage metrics across sessions\n- `KeyCombo` struct represents global hotkey combinations\n- Auto-saves to `bclicker_config.toml` in the current directory\n\n**Threading Architecture:**\n\n- **Main Thread**: UI rendering and input handling\n- **Clicker Thread**: High-precision mouse clicking loop\n- **Event Threads**: Separate threads for input capture and tick events\n- **Hotkey Thread**: Windows-specific global hotkey monitoring\n- **Audio Threads**: Spawned per-sound for non-blocking audio\n\n### Input Mode System\n\nThe application uses a state machine for different input modes:\n\n- `Normal` - Standard navigation and controls\n- `EditingCps` - Custom CPS value input\n- `SettingKeybind` - Capturing hotkey combinations\n- `AwaitingKeybind` - Brief preparation state before capturing\n- `ShowingHelp` - Help screen display\n\n### Platform-Specific Features\n\n**Windows Integration:**\n\n- Global hotkey registration via Win32 API (`RegisterHotKey`)\n- System message loop for hotkey detection\n- Windows-specific virtual key code mapping\n\n**Cross-Platform Considerations:**\n\n- Mouse control works on all platforms via enigo\n- System tray and notifications have fallback behavior\n- Global hotkeys currently Windows-only with graceful degradation\n\n## Configuration and Data Files\n\n### Primary Configuration File\n\n- **Location**: `bclicker_config.toml` (current directory)\n- **Format**: TOML with nested sections\n- **Auto-generated**: Creates default config if missing\n- **Auto-saved**: Persists changes immediately\n\n### Configuration Structure\n\n```toml\ncps_presets = [20, 30, 40, 50]  # Available CPS preset values\nselected_preset = 2              # Currently selected preset index\ncustom_cps_value = 99           # User-defined CPS value\nusing_custom_cps = false        # Whether to use custom vs preset\nselected_button = 0             # 0=Left, 1=Right mouse button\nsound_enabled = false           # Audio feedback toggle\n\n[toggle_keybind]                # Global hotkey configuration\nmods = 6                        # Modifier bitmask (1=Shift, 2=Ctrl, 4=Alt)\nkey = \"B\"                       # Key character or function key\n\n[statistics]                    # Usage tracking\ntotal_clicks = 0                # All-time click count\nsession_clicks = 0              # Current session clicks\ntotal_sessions = 0              # Number of application launches\nlast_session_start = 0          # Unix timestamp\nsession_duration = 0            # Session length in seconds\n```\n\n## Development Considerations\n\n### Performance Characteristics\n\n- **Click Precision**: Microsecond-accurate timing using `Duration::from_micros(1_000_000 / cps)`\n- **UI Responsiveness**: 60 FPS rendering loop with conditional redrawing\n- **Memory Efficiency**: Minimal allocations in hot paths, Arc/Mutex for shared state\n- **CPU Usage**: Adaptive sleep timing based on UI visibility\n\n### Thread Safety Patterns\n\n- `Arc\u003cAtomicBool\u003e` for simple boolean flags (clicker running, UI visibility)\n- `Arc\u003cMutex\u003cT\u003e\u003e` for complex shared data (statistics, configuration)\n- MPSC channels for event communication between threads\n- Lock contention minimized through brief critical sections\n\n### Error Handling Strategy\n\n- Graceful degradation for system integration features\n- Configuration corruption handled with default fallback\n- Non-critical errors logged but don't crash application\n- Proper cleanup on exit with terminal restoration\n\n### Key Extension Points\n\n**Adding New Features:**\n\n1. **New Input Modes**: Extend `InputMode` enum and add handlers in `handle_input()`\n2. **Additional Statistics**: Add fields to `Statistics` struct with migration logic\n3. **Audio Enhancements**: Extend `AudioManager` with new sound methods\n4. **Platform Support**: Implement platform-specific modules for hotkeys/tray\n\n**UI Customization:**\n\n- Theme system already in place with `Theme` struct\n- Modular widget rendering in `draw_ui()` function\n- Help system supports scrolling and formatted content\n- Status bar easily extensible with new information\n\n### Common Patterns\n\n**Configuration Changes:**\n\n```rust\n// Always save config after modifications\napp.config.some_setting = new_value;\napp.save_config();\napp.needs_redraw = true;  // Trigger UI update\n```\n\n**Shared State Updates:**\n\n```rust\n// Safe access to shared statistics\nif let Ok(mut stats) = app.stats_tracker.lock() {\n    stats.some_field += 1;\n    // Lock automatically released\n}\n```\n\n**Event-Driven Updates:**\n\n```rust\n// Mark redraw needed for next frame\napp.needs_redraw = true;\n// Only redraw when UI is visible and needs update\n```\n\n## Troubleshooting\n\n### Common Build Issues\n\n- **Missing Windows SDK**: Global hotkeys require Windows development headers\n- **Audio Dependencies**: rodio may need system audio libraries on Linux\n- **Terminal Compatibility**: Some terminals may not support all TUI features\n\n### Runtime Considerations\n\n- **Hotkey Conflicts**: Global hotkeys may conflict with other applications\n- **Permission Issues**: Some antivirus software may flag mouse automation\n- **Terminal Encoding**: Unicode characters in UI require UTF-8 terminal support\n\n### Development Tips\n\n- Use `cargo run` for development with debug info and faster compilation\n- The application handles terminal cleanup automatically on exit\n- Configuration file is human-readable and can be manually edited\n- Statistics are preserved across application restarts\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-brat%2Fbclicker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-brat%2Fbclicker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-brat%2Fbclicker/lists"}