Claude Code generated CLAUDE.md

2026-01-14 17:35:59 +01:00
1 changed files with 341 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,341 @@
 # Linux Workspace - Project Documentation
 ## Overview
 **Linux Workspace** is a comprehensive shell configuration and utility toolkit designed to quickly configure new Linux machines with development tools, environment initialization, and useful utility scripts. It provides a modular, source-able bootstrap system for both bash and fish shells.
 This is a **dotfiles & configuration management system** combined with a rich collection of utility scripts for system administration, development workflows, and daily convenience tasks.
 ## Quick Start
 ### Installation
 ```bash
 # Clone the repository
 git clone <repository-url> ~/linux-workspace
 # Run the installer
 cd ~/linux-workspace
 ./install.sh
 ```
 The installer automatically:
 - Detects the workspace directory location
 - Adds sourcing configuration to `~/.bashrc`
 - Creates Fish shell configuration at `~/.config/fish/conf.d/lws.fish`
 ### Manual Installation
 Add to your `~/.bashrc`:
 ```bash
 source /path/to/linux-workspace/bashrc
 ```
 ## Project Structure
 ### Root Files
 - [bashrc](bashrc) - Main bootstrap file that initializes the entire workspace
 - [fishrc](fishrc) - Fish shell configuration entry point
 - [functions.sh](functions.sh) - Core utility functions used throughout the system
 - [install.sh](install.sh) - Installation script for automated setup
 - [.editorconfig](.editorconfig) - EditorConfig formatting standards
 ### Key Directories
 #### [bin/](bin/) - Utility Scripts & Tools (45+ scripts)
 Collection of executable shell and Python scripts for various tasks:
 **Docker & Containers:**
 - [dcm](bin/dcm) - Advanced Docker Compose manager with dependency and health check features
 - [docker-bridge](bin/docker-bridge), [docker-noroot](bin/docker-noroot) - Docker helpers
 **Development Tools:**
 - [gws](bin/gws) - Gradle wrapper shortcuts for Kotlin development
 - [git-dif1](bin/git-dif1), [git-swl](bin/git-swl), [git-reset-master](bin/git-reset-master) - Git workflow utilities
 **System Utilities:**
 - [network-bandwidth](bin/network-bandwidth), [myip](bin/myip), [weather](bin/weather) - System info
 - [lock-screen](bin/lock-screen), [suspend.sh](bin/suspend.sh), [battery](bin/battery) - System control
 - [cs.sh](bin/cs.sh), [cheatsheet](bin/cheatsheet) - Cheatsheet lookup tools
 **Cloud & Infrastructure:**
 - [aws-login](bin/aws-login) - AWS authentication helper
 - [vpn-home.sh](bin/vpn-home.sh) - VPN configuration
 **Remote Tools:**
 - [xmosh](bin/xmosh), [xcat](bin/xcat), [xvim](bin/xvim) - Remote execution helpers
 #### [rc/](rc/) - Shell Configuration Modules (23 files)
 Modular initialization scripts loaded during shell startup:
 **Core Setup:**
 - [01-init.fish](rc/01-init.fish) - Fish shell initialization
 - [01-path.sh](rc/01-path.sh) - PATH initialization
 - [02-aliases.sh](rc/02-aliases.sh) - Common command aliases
 - [env.sh](rc/env.sh) - Environment variables (PAGER, EDITOR, MANPAGER)
 - [bash-prompt.sh](rc/bash-prompt.sh) - Colored bash prompt
 **Language/Framework Initialization:**
 - [nvm.sh](rc/nvm.sh) - Node Version Manager
 - [pyenv.sh](rc/pyenv.sh) - Python environment manager
 - [cargo.sh](rc/cargo.sh) - Rust Cargo
 - [dotnet.sh](rc/dotnet.sh) - .NET runtime
 - [sdkman.sh](rc/sdkman.sh) - SDKMAN Java/Kotlin tooling
 - [linuxbrew.sh](rc/linuxbrew.sh) - Homebrew for Linux
 **Development Tools:**
 - [ssh-agent.sh](rc/ssh-agent.sh) - SSH agent with WSL support
 - [git-prompt.sh](rc/git-prompt.sh) - Git prompt decoration
 - [direnv.sh](rc/direnv.sh) - Directory environment switching
 - [docker.sh](rc/docker.sh) - Docker initialization
 - [kubernetes.sh](rc/kubernetes.sh) - kubectl/k8s setup
 - [claude-code.sh](rc/claude-code.sh) - Claude Code integration
 **Other Tools:**
 - [gocryptfs.sh](rc/gocryptfs.sh) - Encrypted filesystem
 - [thefuck.sh](rc/thefuck.sh) - Command correction
 - [enhancd.sh](rc/enhancd.sh) - Directory navigation enhancement
 #### [install/](install/) - Installation Scripts (24 files)
 Automated setup scripts for various tools:
 **Development:**
 - [git-prompt.sh](install/git-prompt.sh), [awscli.sh](install/awscli.sh)
 - [docker-ce.sh](install/docker-ce.sh), [docker-compose-2.sh](install/docker-compose-2.sh)
 - [go-tools.sh](install/go-tools.sh), [rust.sh](install/rust.sh)
 - [npm.sh](install/npm.sh), [uv.sh](install/uv.sh)
 **Services:**
 - [k3s.sh](install/k3s.sh) - Lightweight Kubernetes
 - [lazygit.sh](install/lazygit.sh) - Git UI
 - [syncthing.sh](install/syncthing.sh) - File synchronization
 **Applications:**
 - [packages.sh](install/packages.sh) - Debian packages
 - [sublime.sh](install/sublime.sh), [vivaldi.sh](install/vivaldi.sh)
 - [pwsh.sh](install/pwsh.sh) - PowerShell
 #### [scripts/](scripts/) - Helper Scripts (16 files)
 Administrative and one-off scripts:
 - [git-config.sh](scripts/git-config.sh) - Git user/email configuration
 - [bash-template.sh](scripts/bash-template.sh) - Script template
 - [gnome-configuration.sh](scripts/gnome-configuration.sh) - GNOME settings automation
 - [gradle-init-kotlin.sh](scripts/gradle-init-kotlin.sh) - Gradle Kotlin project setup
 - [update-desktop-apps.sh](scripts/update-desktop-apps.sh) - Application updates
 #### [doc/](doc/) - Documentation (21 files)
 Reference guides and cheatsheets:
 - [bash.md](doc/bash.md) - Bash scripting guide
 - [git.md](doc/git.md) - Git workflows
 - [vim.md](doc/vim.md) - Vim editor tips
 - [cheatsheet.md](doc/cheatsheet.md) - General commands
 - [fzf.md](doc/fzf.md) - Fuzzy finder
 - [kotlin-coding-guideline.md](doc/kotlin-coding-guideline.md) - Kotlin style guide
 - [gnome.md](doc/gnome.md) - GNOME customization
 #### [conf/](conf/) - Configuration Files
 - [gnome-shortcuts.conf](conf/gnome-shortcuts.conf) - Keyboard shortcuts
 - [gradle.properties](conf/gradle.properties) - Gradle build config
 - [wsl.conf](conf/wsl.conf) - WSL settings
 - [wg-home.conf](conf/wg-home.conf) - WireGuard VPN
 - [packages.txt](conf/packages.txt) - Recommended Debian packages
 - [applications/](conf/applications/) - Application configs
 - [dircolors/](conf/dircolors/) - Directory coloring schemes
 - [vim/](conf/vim/) - Vim configurations
 #### [src/](src/) - Source Projects
 - [battery/](src/battery/) - Python project for reading notebook battery information
 ## Key Features
 ### Bootstrap System
 - **Single-entry point**: [bashrc](bashrc) sources [functions.sh](functions.sh) and loads all `.sh` files from `rc/`
 - **Modular design**: Each tool has its own configuration file
 - **Performance optimization**: `LWS_FAST=1` environment variable for fast initialization
 - **Debug mode**: `LWS_DEBUG=1` for troubleshooting
 - **Reloadable**: `reload-workspace` alias to refresh configuration
 ### Core Functions
 The [functions.sh](functions.sh) file provides essential utilities:
 - `append_path()`, `prepend_path()` - PATH manipulation with duplicate prevention
 - `source_directory()`, `source_directory_sh()` - Smart recursive sourcing
 - `is_fast_init()`, `is_slow_init()` - Performance-based initialization
 - `can_run()`, `is_alias()` - Command availability checks
 - `is_wsl()` - Windows Subsystem for Linux detection
 - `xlog()` - Conditional debug logging
 ### Common Aliases
 Defined in [rc/02-aliases.sh](rc/02-aliases.sh):
 - Directory: `ll`, `la` (enhanced listing)
 - Docker: `dc` (docker-compose), `dcl` (logs)
 - Navigation: `..`, `...`, `....`, `cdd` (Downloads)
 - Time: `now`, `nowsql`, `sqldate`
 - Kubernetes: `kl`, `kld`, `klg`
 - System: `ssha` (ssh-agent)
 ### SSH Agent Integration
 The [rc/ssh-agent.sh](rc/ssh-agent.sh) module provides:
 - **WSL-aware**: Special handling for Windows Subsystem for Linux
 - **Multi-key support**: Checks for both id_ecdsa and id_rsa
 - **Auto-start**: Automatically starts ssh-agent if not running
 - **Keychain fallback**: Uses keychain for non-WSL systems
 ### Docker Integration
 The [bin/dcm](bin/dcm) script offers advanced Docker Compose management:
 - Service dependency tracking
 - Health check polling (HTTP, TCP, Redis, etc.)
 - Parallel builds
 - Logging filtering
 - Service startup orchestration
 ### Gradle Integration
 The [bin/gws](bin/gws) tool provides shortcuts for common Gradle tasks:
 - Build shortcuts: `c` (clean), `b` (build), `t` (test)
 - Combined: `cb` (clean+build), `cbt` (clean+build+test)
 - Skip options: `-nd` (no detekt), `-nt` (no tests)
 - Java-specific: `jar` (shadowJar), `br` (bootRun)
 ## Environment Variables
 ### Core Variables
 - `$LWS` - Root directory of Linux Workspace
 - `$WORKSPACE` - Alias for LWS
 ### Configuration Flags
 - `LWS_DEBUG=1` - Enable debug logging
 - `LWS_FAST=1` - Fast initialization (skip slow tools)
 ### Tool Customization
 - `DC`, `DCF` - Docker Compose customization
 - `EDITOR` - Default text editor
 - `PAGER` - Default pager (less)
 ## Important Commands
 - `reload-workspace` - Reload all configurations
 - `clws` - Change directory to workspace
 - `dcm` - Docker Compose manager
 - `gws` - Gradle wrapper shortcuts
 ## Configuration Strategy
 The project uses an **environment-first** approach:
 1. **Staged initialization**: Tools load based on `LWS_FAST` flag
 2. **Conditional loading**: Tools only initialize if directories exist
 3. **WSL detection**: Special paths and behaviors for Windows Subsystem for Linux
 4. **Path deduplication**: Removes duplicate PATH entries
 5. **EditorConfig standardization**: Consistent coding standards
 ## Use Cases
 1. **Rapid environment setup** for new Linux machines
 2. **Consistent shell configuration** across multiple systems
 3. **Development tool management** (Node, Python, Rust, Go, Java)
 4. **Docker/Kubernetes workflows** with helper utilities
 5. **Git workflow automation**
 6. **System administration** utilities and scripts
 7. **Personal workspace customization** with modular components
 ## Customization
 ### Adding New Modules
 1. Create a new `.sh` file in [rc/](rc/)
 2. Add your configuration or aliases
 3. Reload with `reload-workspace`
 ### Adding New Scripts
 1. Create executable script in [bin/](bin/)
 2. Make it executable: `chmod +x bin/yourscript`
 3. Script is automatically available in PATH
 ### Disabling Modules
 Move unwanted modules from [rc/](rc/) to [rc.available/](rc.available/)
 ## Dependencies
 The workspace intelligently detects and initializes available tools:
 - **Required**: bash, git
 - **Optional**: docker, kubectl, nvm, pyenv, cargo, direnv, etc.
 - **Detection**: Each module checks for tool availability before initialization
 ## WSL Support
 Special handling for Windows Subsystem for Linux:
 - SSH agent integration with Windows
 - Path adjustments for Windows interoperability
 - WSL-specific configurations in [conf/wsl.conf](conf/wsl.conf)
 ## Performance
 - **Fast mode**: Set `LWS_FAST=1` to skip heavy initializations
 - **Lazy loading**: Tools only load when directories exist
 - **Optimized PATH**: Deduplication prevents PATH bloat
 ## Contributing
 This is a personal workspace configuration, but improvements are welcome:
 1. Follow existing naming conventions
 2. Keep scripts modular and self-contained
 3. Test on fresh installations
 4. Document new features in appropriate [doc/](doc/) files
 ## License
 Personal project - use and modify as needed for your own workspace.
 ## Recent Changes
 - Installation script improvements
 - Enhanced `ll` and `la` aliases
 - SSH agent fixes for WSL
 - Fish shell integration
 - Addition of new tools (Claude Code, Gemini CLI)
 ## Support
 For issues or questions, refer to the documentation in [doc/](doc/) or examine the relevant configuration files in [rc/](rc/).