linux-workspace/CLAUDE.md

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

# 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:

source /path/to/linux-workspace/bashrc

Project Structure

Root Files

• bashrc - Main bootstrap file that initializes the entire workspace
• fishrc - Fish shell configuration entry point
• functions.sh - Core utility functions used throughout the system
• install.sh - Installation script for automated setup
• .editorconfig - EditorConfig formatting standards

Key Directories

bin/ - Utility Scripts & Tools (45+ scripts)

Collection of executable shell and Python scripts for various tasks:

Docker & Containers:

• dcm - Advanced Docker Compose manager with dependency and health check features
• docker-bridge, docker-noroot - Docker helpers

Development Tools:

• gws - Gradle wrapper shortcuts for Kotlin development
• git-dif1, git-swl, git-reset-master - Git workflow utilities

System Utilities:

• network-bandwidth, myip, weather - System info
• lock-screen, suspend.sh, battery - System control
• cs.sh, cheatsheet - Cheatsheet lookup tools

Cloud & Infrastructure:

• aws-login - AWS authentication helper
• vpn-home.sh - VPN configuration

Remote Tools:

• xmosh, xcat, xvim - Remote execution helpers

rc/ - Shell Configuration Modules (23 files)

Modular initialization scripts loaded during shell startup:

Core Setup:

• 01-init.fish - Fish shell initialization
• 01-path.sh - PATH initialization
• 02-aliases.sh - Common command aliases
• env.sh - Environment variables (PAGER, EDITOR, MANPAGER)
• bash-prompt.sh - Colored bash prompt

Language/Framework Initialization:

• nvm.sh - Node Version Manager
• pyenv.sh - Python environment manager
• cargo.sh - Rust Cargo
• dotnet.sh - .NET runtime
• sdkman.sh - SDKMAN Java/Kotlin tooling
• linuxbrew.sh - Homebrew for Linux

Development Tools:

• ssh-agent.sh - SSH agent with WSL support
• git-prompt.sh - Git prompt decoration
• direnv.sh - Directory environment switching
• docker.sh - Docker initialization
• kubernetes.sh - kubectl/k8s setup
• claude-code.sh - Claude Code integration

Other Tools:

• gocryptfs.sh - Encrypted filesystem
• thefuck.sh - Command correction
• enhancd.sh - Directory navigation enhancement

install/ - Installation Scripts (24 files)

Automated setup scripts for various tools:

Development:

• git-prompt.sh, awscli.sh
• docker-ce.sh, docker-compose-2.sh
• go-tools.sh, rust.sh
• npm.sh, uv.sh

Services:

• k3s.sh - Lightweight Kubernetes
• lazygit.sh - Git UI
• syncthing.sh - File synchronization

Applications:

• packages.sh - Debian packages
• sublime.sh, vivaldi.sh
• pwsh.sh - PowerShell

scripts/ - Helper Scripts (16 files)

Administrative and one-off scripts:

• git-config.sh - Git user/email configuration
• bash-template.sh - Script template
• gnome-configuration.sh - GNOME settings automation
• gradle-init-kotlin.sh - Gradle Kotlin project setup
• update-desktop-apps.sh - Application updates

doc/ - Documentation (21 files)

Reference guides and cheatsheets:

• bash.md - Bash scripting guide
• git.md - Git workflows
• vim.md - Vim editor tips
• cheatsheet.md - General commands
• fzf.md - Fuzzy finder
• kotlin-coding-guideline.md - Kotlin style guide
• gnome.md - GNOME customization

conf/ - Configuration Files

• gnome-shortcuts.conf - Keyboard shortcuts
• gradle.properties - Gradle build config
• wsl.conf - WSL settings
• wg-home.conf - WireGuard VPN
• packages.txt - Recommended Debian packages
• applications/ - Application configs
• dircolors/ - Directory coloring schemes
• vim/ - Vim configurations

src/ - Source Projects

• battery/ - Python project for reading notebook battery information

Key Features

Bootstrap System

• Single-entry point: bashrc sources 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 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:

• 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 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 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 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/
2. Add your configuration or aliases
3. Reload with reload-workspace

Adding New Scripts

1. Create executable script in bin/
2. Make it executable: chmod +x bin/yourscript
3. Script is automatically available in PATH

Disabling Modules

Move unwanted modules from rc/ to 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

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/ 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/ or examine the relevant configuration files in rc/.