|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +hyprland-autoname-workspaces is a Rust application that automatically renames Hyprland workspaces with icons based on running applications. It integrates with the Hyprland compositor's IPC system to monitor window events and update workspace names in real-time. |
| 8 | + |
| 9 | +## Common Development Commands |
| 10 | + |
| 11 | +### Building |
| 12 | +- `make build-dev` - Development build with feature flag and dependency updates |
| 13 | +- `make build` - Release build with locked dependencies |
| 14 | +- `cargo build` - Standard Rust build |
| 15 | + |
| 16 | +### Testing |
| 17 | +- `make test` - Run all tests with locked dependencies |
| 18 | +- `cargo test` - Standard Rust test command |
| 19 | +- `cargo test --test <test_name>` - Run specific test |
| 20 | + |
| 21 | +### Linting and Formatting |
| 22 | +- `make lint` - Run both formatter check and clippy linter |
| 23 | +- `cargo fmt` - Format code |
| 24 | +- `cargo clippy` - Run linter with warnings as errors |
| 25 | + |
| 26 | +### Running |
| 27 | +- `make run` - Run the application |
| 28 | +- `cargo run -- -c path/to/config.toml` - Run with custom config |
| 29 | + |
| 30 | +### Release Process |
| 31 | +- `make release` - Create new release with version bump and git tag |
| 32 | + |
| 33 | +## Architecture Overview |
| 34 | + |
| 35 | +### Core Components |
| 36 | + |
| 37 | +1. **Main Entry Point** (`src/main.rs`): |
| 38 | + - Initializes the application |
| 39 | + - Sets up Hyprland event monitoring |
| 40 | + - Manages the main event loop |
| 41 | + |
| 42 | +2. **Renamer Module** (`src/renamer/`): |
| 43 | + - `mod.rs` - Core renaming logic and workspace management |
| 44 | + - `formatter.rs` - Handles formatting of workspace names with placeholders |
| 45 | + - `icon.rs` - Icon mapping and resolution logic |
| 46 | + - `macros.rs` - Helper macros for the module |
| 47 | + |
| 48 | +3. **Config Module** (`src/config/`): |
| 49 | + - Handles TOML configuration parsing |
| 50 | + - Manages config file watching for auto-reload |
| 51 | + - Provides default configuration generation |
| 52 | + |
| 53 | +4. **Params Module** (`src/params/`): |
| 54 | + - Command-line argument parsing using clap |
| 55 | + |
| 56 | +### Key Design Patterns |
| 57 | + |
| 58 | +1. **Event-Driven Architecture**: The application subscribes to Hyprland IPC events and reacts to window/workspace changes. |
| 59 | + |
| 60 | +2. **Regex-Based Matching**: Window classes and titles are matched using regex patterns for flexible icon assignment. |
| 61 | + |
| 62 | +3. **Configuration Hot-Reload**: File system watching enables configuration changes without restart. |
| 63 | + |
| 64 | +4. **Placeholder System**: Flexible formatting using placeholders like `{icon}`, `{class}`, `{title}`, etc. |
| 65 | + |
| 66 | +## Testing Approach |
| 67 | + |
| 68 | +Tests are integrated directly in source files using Rust's built-in testing framework: |
| 69 | +- Unit tests use `#[cfg(test)]` modules |
| 70 | +- Test functions are marked with `#[test]` |
| 71 | +- Key test locations: `src/renamer/mod.rs`, `src/config/mod.rs`, `src/renamer/formatter.rs` |
| 72 | + |
| 73 | +## Configuration System |
| 74 | + |
| 75 | +The application uses TOML configuration with these main sections: |
| 76 | +- `[format]` - Display formatting options |
| 77 | +- `[class]` - Application class to icon mappings |
| 78 | +- `[title_in_class]` - Title-based icon mappings within specific classes |
| 79 | +- `[exclude]` - Window exclusion rules |
| 80 | +- `[workspaces_name]` - Custom workspace names |
| 81 | + |
| 82 | +Default config location: `~/.config/hyprland-autoname-workspaces/config.toml` |
| 83 | + |
| 84 | +## Dependencies |
| 85 | + |
| 86 | +Key dependencies (from Cargo.toml): |
| 87 | +- `hyprland` - Hyprland IPC integration |
| 88 | +- `clap` - Command-line parsing |
| 89 | +- `toml` & `serde` - Configuration handling |
| 90 | +- `regex` - Pattern matching |
| 91 | +- `notify` - File system watching |
| 92 | + |
| 93 | +## Development Notes |
| 94 | + |
| 95 | +1. The project is seeking maintainers (see README) |
| 96 | +2. Use `--features dev` for development builds |
| 97 | +3. The systemd service file enables automatic startup |
| 98 | +4. Icon generation helper script available at `contrib/generate_icons.py` |
| 99 | +5. All regex patterns support case-insensitive matching with `(?i)` flag |
0 commit comments