|
| 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 | +FileCtrl is a Terminal User Interface (TUI) file manager written in Rust using the Ratatui framework. It provides a keyboard-driven interface for file operations with extensive theming and configuration support. |
| 8 | + |
| 9 | +## Common Development Commands |
| 10 | + |
| 11 | +### Build and Run |
| 12 | +- `cargo build` - Build the project |
| 13 | +- `cargo build --release` - Build optimized release version |
| 14 | +- `cargo run` - Run the application |
| 15 | +- `cargo run -- <directory>` - Run with specific directory |
| 16 | +- `cargo run -- --write-config` - Write default config to ~/.config/filectrl/config.toml |
| 17 | + |
| 18 | +### Testing and Quality |
| 19 | +- `cargo test` - Run tests |
| 20 | +- `cargo clippy` - Run linter |
| 21 | +- `cargo fix --allow-dirty --allow-staged` - Auto-fix linting issues |
| 22 | + |
| 23 | +### Debugging |
| 24 | +- `RUST_LOG=debug cargo run 2>err` - Run with debug logging to ./err file |
| 25 | +- Set `log_level = "debug"` in config.toml for application-level logging |
| 26 | + |
| 27 | +### Git Hooks |
| 28 | +The project uses cargo-husky for git hooks. Pre-commit hooks run `cargo test` and `cargo check`. To modify hooks: |
| 29 | +1. Edit `[dev-dependencies.cargo-husky]` in Cargo.toml |
| 30 | +2. Remove `.git/hooks/pre-commit` |
| 31 | +3. Run `cargo clean && cargo test` |
| 32 | + |
| 33 | +## Architecture |
| 34 | + |
| 35 | +### Core Structure |
| 36 | +- `src/main.rs` - Entry point with CLI argument parsing using argh |
| 37 | +- `src/lib.rs` - Main library with logging configuration and app initialization |
| 38 | +- `src/app.rs` - Core application state and event loop |
| 39 | +- `src/views/` - UI components organized by responsibility |
| 40 | +- `src/file_system/` - File operations with async support and debouncing |
| 41 | +- `src/command/` - Command handling system with modes and tasks |
| 42 | + |
| 43 | +### Key Components |
| 44 | + |
| 45 | +#### Configuration System |
| 46 | +- `src/app/config/` - Configuration management |
| 47 | +- `default_config.toml` - Comprehensive default configuration with theming |
| 48 | +- Supports both truecolor and 256-color terminal themes |
| 49 | +- Configuration precedence: CLI option → ~/.config/filectrl/config.toml → built-in defaults |
| 50 | + |
| 51 | +#### File Operations |
| 52 | +- `src/file_system/` - Handles all file system operations |
| 53 | +- `async.rs` - Asynchronous file operations with buffering (64KB-64MB) |
| 54 | +- `watcher.rs` - File system change monitoring with notify crate |
| 55 | +- `debounce.rs` - Prevents excessive refreshes (100ms default) |
| 56 | + |
| 57 | +#### UI Architecture |
| 58 | +- Uses Ratatui for terminal UI rendering |
| 59 | +- `src/views/root.rs` - Main view coordinator |
| 60 | +- `src/views/table/` - File listing table with scrolling and selection |
| 61 | +- `src/views/prompt/` - Input handling for rename/filter operations |
| 62 | +- `src/views/status/` - Status bar with directory and selection info |
| 63 | +- `src/views/notices/` - Progress indicators and clipboard status |
| 64 | + |
| 65 | +#### Command System |
| 66 | +- `src/command/` - Command processing with different modes |
| 67 | +- Supports Normal, Filter, and Rename modes |
| 68 | +- Task-based async operations for file operations |
| 69 | + |
| 70 | +### Key Features |
| 71 | +- Extensive keyboard navigation (vim-like bindings) |
| 72 | +- Copy/cut/paste operations with clipboard integration |
| 73 | +- Real-time file system monitoring |
| 74 | +- Configurable external program integration |
| 75 | +- Comprehensive theming with LS_COLORS support |
| 76 | +- Double-click detection for file opening |
| 77 | +- Word-based navigation in text inputs |
| 78 | + |
| 79 | +### External Dependencies |
| 80 | +- ratatui - Terminal UI framework |
| 81 | +- rat-* crates - Additional UI widgets (from git) |
| 82 | +- notify - File system watching |
| 83 | +- cli-clipboard - System clipboard integration |
| 84 | +- open - Opening files with default applications |
| 85 | +- chrono - Date/time handling for file timestamps |
| 86 | +- toml/serde - Configuration serialization |
| 87 | + |
| 88 | +### Development Notes |
| 89 | +- Uses cargo-husky for git pre-commit hooks |
| 90 | +- Logging configured via RUST_LOG environment variable or config file |
| 91 | +- Terminal truecolor detection with 256-color fallback |
| 92 | +- Comprehensive error handling with anyhow |
| 93 | +- Unicode-aware text processing for file names and input |
0 commit comments