LaxyFile Configuration Guide

This comprehensive guide covers all aspects of configuring LaxyFile to match your workflow and preferences.

Table of Contents

1. Configuration Overview
2. Basic Settings
3. Theme Configuration
4. AI Assistant Setup
5. Keyboard Shortcuts
6. Performance Tuning
7. Plugin Configuration
8. Advanced Settings
9. Import/Export Settings

Configuration Overview

LaxyFile stores configuration in platform-specific locations:

• Linux: ~/.config/laxyfile/
• macOS: ~/Library/Application Support/LaxyFile/
• Windows: %APPDATA%\LaxyFile\

Configuration Files Structure

~/.config/laxyfile/
├── config.yaml          # Main configuration
├── themes/              # Custom themes
│   ├── my-theme.json
│   └── work-theme.json
├── plugins/             # Plugin configurations
│   ├── git-integration.yaml
│   └── image-tools.yaml
├── shortcuts.yaml       # Keyboard shortcuts
├── ai-cache/           # AI response cache
├── logs/               # Application logs
└── backups/            # Configuration backups

Configuration Hierarchy

LaxyFile loads configuration in this order (later overrides earlier):

1. Default settings (built into application)
2. System-wide config (/etc/laxyfile/config.yaml)
3. User config (~/.config/laxyfile/config.yaml)
4. Environment variables (LAXYFILE_*)
5. Command-line arguments (--config-option=value)

Basic Settings

Main Configuration File

The main configuration file (config.yaml) uses YAML format:

# ~/.config/laxyfile/config.yaml

# Application settings
app:
  version: "2.0.0"
  first_run: false
  check_updates: true
  telemetry: false

# User interface settings
ui:
  theme: "catppuccin"
  font_family: "SF Pro Display"
  font_size: 12
  show_hidden_files: false
  show_file_extensions: true
  dual_pane_mode: false
  sidebar_width: 200
  preview_panel: true
  status_bar: true
  toolbar: true
  animations: true
  animation_speed: "normal" # slow, normal, fast
  icon_size: "medium" # small, medium, large
  file_list_style: "detailed" # compact, detailed, grid

# File operations
file_operations:
  confirm_delete: true
  confirm_overwrite: true
  use_trash: true
  show_progress: true
  verify_copies: true
  default_permissions: "644"
  preserve_timestamps: true
  follow_symlinks: false

# Search settings
search:
  case_sensitive: false
  use_regex: false
  search_content: true
  max_results: 1000
  index_hidden_files: false
  exclude_patterns:
    - "*.tmp"
    - "*.log"
    - ".git/*"
    - "node_modules/*"

# Network settings
network:
  timeout: 30
  retry_attempts: 3
  proxy_url: ""
  user_agent: "LaxyFile/2.0"

Environment Variables

Override settings with environment variables:

# Theme selection
export LAXYFILE_THEME="dracula"

# AI provider
export LAXYFILE_AI_PROVIDER="openrouter"
export LAXYFILE_AI_API_KEY="your-api-key"

# Performance settings
export LAXYFILE_CACHE_SIZE="2000"
export LAXYFILE_MAX_WORKERS="8"

# Debug settings
export LAXYFILE_DEBUG="true"
export LAXYFILE_LOG_LEVEL="DEBUG"

Command-Line Configuration

Override settings via command-line arguments:

# Start with specific theme
laxyfile --theme=nord

# Disable AI features
laxyfile --no-ai

# Custom config file
laxyfile --config=/path/to/custom/config.yaml

# Debug mode
laxyfile --debug --log-level=DEBUG

# Safe mode (minimal features)
laxyfile --safe-mode

Theme Configuration

Built-in Themes

LaxyFile includes several SuperFile-inspired themes:

ui:
  theme: "catppuccin" # Options:
  # - catppuccin      # Soothing pastels
  # - dracula         # Dark with purple accents
  # - nord            # Arctic blues
  # - gruvbox         # Retro warm colors
  # - tokyo-night     # Neon darkness
  # - one-dark        # Atom-inspired
  # - solarized-dark  # High contrast dark
  # - solarized-light # High contrast light

Custom Theme Creation

Create custom themes in ~/.config/laxyfile/themes/:

{
  "name": "My Custom Theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A custom theme for LaxyFile",

  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa",
    "selection": "#313244",
    "border": "#45475a",
    "error": "#f38ba8",
    "warning": "#f9e2af",
    "success": "#a6e3a1",
    "info": "#74c7ec",

    "file_panel": {
      "background": "#1e1e2e",
      "text": "#cdd6f4",
      "selected_bg": "#313244",
      "selected_text": "#cdd6f4",
      "header_bg": "#181825",
      "header_text": "#bac2de"
    },

    "sidebar": {
      "background": "#181825",
      "text": "#bac2de",
      "selected_bg": "#313244",
      "selected_text": "#cdd6f4"
    },

    "status_bar": {
      "background": "#181825",
      "text": "#bac2de"
    },

    "preview_panel": {
      "background": "#1e1e2e",
      "text": "#cdd6f4",
      "border": "#45475a"
    }
  },

  "fonts": {
    "ui": {
      "family": "SF Pro Display",
      "size": 12,
      "weight": "normal"
    },
    "monospace": {
      "family": "JetBrains Mono",
      "size": 11,
      "weight": "normal"
    }
  },

  "icons": {
    "style": "nerd-fonts",  # nerd-fonts, unicode, ascii
    "color_coding": true,
    "custom_mappings": {
      ".py": "🐍",
      ".js": "📜",
      ".md": "📝"
    }
  },

  "animations": {
    "enabled": true,
    "duration": 200,
    "easing": "ease-in-out"
  }
}

Theme Inheritance

Create themes that inherit from existing ones:

{
  "name": "Dark Catppuccin Variant",
  "inherits": "catppuccin",
  "colors": {
    "background": "#11111b",
    "file_panel": {
      "background": "#11111b"
    }
  }
}

Dynamic Theme Switching

Configure automatic theme switching:

ui:
  theme: "auto" # Automatically switch based on system
  theme_schedule:
    enabled: true
    light_theme: "solarized-light"
    dark_theme: "catppuccin"
    switch_time:
      to_light: "07:00"
      to_dark: "19:00"

  # Or use system theme detection
  follow_system_theme: true

AI Assistant Setup

Provider Configuration

Configure your preferred AI provider:

ai:
  enabled: true
  provider: "openrouter" # openrouter, ollama, gpt4all, custom

  # OpenRouter configuration
  openrouter:
    api_key: "your-api-key-here"
    base_url: "https://openrouter.ai/api/v1"
    model: "anthropic/claude-3-haiku"
    max_tokens: 4000
    temperature: 0.1
    timeout: 30

  # Ollama configuration (local)
  ollama:
    base_url: "http://localhost:11434"
    model: "llama2"
    timeout: 60

  # GPT4All configuration (local)
  gpt4all:
    model_path: "~/.cache/gpt4all/orca-mini-3b.q4_0.bin"
    n_threads: 4

  # Custom provider
  custom:
    api_key: "your-key"
    base_url: "https://your-api.com/v1"
    model: "your-model"
    headers:
      "Custom-Header": "value"

AI Feature Configuration

Control which AI features are enabled:

ai:
  features:
    file_analysis: true
    content_search: true
    organization_suggestions: true
    security_analysis: true
    duplicate_detection: true
    smart_rename: true
    workflow_automation: true

  # Performance settings
  performance:
    cache_responses: true
    cache_ttl: 3600 # 1 hour
    max_concurrent_requests: 5
    background_processing: true

  # Privacy settings
  privacy:
    send_file_content: true
    send_metadata_only: false
    local_processing_preferred: false
    data_retention_days: 30

AI Model Selection

Choose models based on your needs:

ai:
  models:
    # Fast, cost-effective for basic tasks
    quick_analysis: "anthropic/claude-3-haiku"

    # Balanced performance and capability
    general_purpose: "anthropic/claude-3-sonnet"

    # Most capable for complex tasks
    advanced_analysis: "anthropic/claude-3-opus"

    # Local models for privacy
    local_fallback: "ollama/llama2"

  # Auto-select model based on task complexity
  auto_model_selection: true

  # Fallback chain if primary model fails
  fallback_models:
    - "anthropic/claude-3-haiku"
    - "ollama/llama2"

Keyboard Shortcuts

Default Shortcut Schemes

LaxyFile supports multiple shortcut schemes:

shortcuts:
  scheme: "default" # Options:
  # - default      # Standard file manager shortcuts
  # - vim          # Vim-like navigation
  # - superfile    # SuperFile-compatible
  # - custom       # User-defined shortcuts

Custom Shortcut Configuration

Define custom shortcuts in shortcuts.yaml:

# ~/.config/laxyfile/shortcuts.yaml

# Navigation shortcuts
navigation:
  go_up: "Ctrl+Up"
  go_home: "Ctrl+H"
  go_root: "Ctrl+R"
  go_back: "Alt+Left"
  go_forward: "Alt+Right"
  go_to_path: "Ctrl+L"

# File operations
file_operations:
  copy: "Ctrl+C"
  cut: "Ctrl+X"
  paste: "Ctrl+V"
  delete: "Delete"
  rename: "F2"
  properties: "Alt+Enter"
  new_folder: "Ctrl+Shift+N"
  new_file: "Ctrl+N"

# Selection
selection:
  select_all: "Ctrl+A"
  deselect_all: "Ctrl+D"
  invert_selection: "Ctrl+I"
  select_by_pattern: "Ctrl+Shift+S"

# View options
view:
  refresh: "F5"
  toggle_preview: "F3"
  toggle_sidebar: "F9"
  toggle_dual_pane: "F6"
  list_view: "Ctrl+1"
  icon_view: "Ctrl+2"
  tree_view: "Ctrl+3"

# Search
search:
  quick_search: "Ctrl+F"
  advanced_search: "Ctrl+Shift+F"
  ai_search: "Ctrl+Alt+F"

# AI assistant
ai:
  open_chat: "F1"
  quick_query: "Ctrl+Shift+A"
  analyze_file: "Ctrl+I"
  organize_files: "Ctrl+O"

# Application
application:
  settings: "Ctrl+,"
  help: "F1"
  exit: "Ctrl+Q"

# Custom shortcuts
custom:
  my_workflow: "Ctrl+Shift+W"
  favorite_folder: "Ctrl+Shift+F"

Shortcut Conflicts

LaxyFile automatically detects and resolves shortcut conflicts:

shortcuts:
  conflict_resolution: "warn" # Options:
  # - ignore    # Allow conflicts
  # - warn      # Show warning but allow
  # - prevent   # Prevent conflicting shortcuts
  # - auto      # Automatically resolve conflicts

  # Show shortcut hints in UI
  show_hints: true
  hint_delay: 1000 # milliseconds

Context-Sensitive Shortcuts

Define shortcuts that work only in specific contexts:

shortcuts:
  contexts:
    file_panel:
      space: "select_toggle"
      enter: "open_file"
      backspace: "go_up"

    preview_panel:
      space: "scroll_down"
      shift_space: "scroll_up"

    search_mode:
      escape: "exit_search"
      enter: "search_execute"

    ai_chat:
      ctrl_enter: "send_message"
      escape: "close_chat"

Performance Tuning

General Performance Settings

performance:
  # Cache settings
  cache_size: 1000 # Number of items to cache
  cache_ttl: 3600 # Cache time-to-live (seconds)
  memory_limit_mb: 500 # Maximum memory usage

  # File operations
  max_concurrent_operations: 8 # Parallel file operations
  chunk_size_kb: 64 # File copy chunk size
  use_sendfile: true # Use system sendfile() if available

  # UI performance
  lazy_loading: true # Load files as needed
  virtual_scrolling: true # Efficient large list handling
  max_files_display: 1000 # Limit initial file display

  # Background processing
  background_processing: true # Non-blocking operations
  worker_threads: 4 # Background worker threads

  # Network optimization
  network_timeout: 30 # Network operation timeout
  connection_pooling: true # Reuse network connections

  # AI performance
  ai_cache_size: 2000 # AI response cache size
  ai_background_analysis: true # Analyze files in background

Memory Management

performance:
  memory:
    # Garbage collection
    gc_enabled: true
    gc_threshold: 100 # MB before triggering GC
    gc_interval: 300 # Seconds between GC runs

    # Cache management
    cache_cleanup_interval: 600 # Seconds between cache cleanup
    max_cache_age: 3600 # Maximum cache entry age

    # Memory monitoring
    memory_monitoring: true
    memory_warning_threshold: 80 # Percent of limit
    memory_critical_threshold: 95 # Percent of limit

Disk I/O Optimization

performance:
  disk_io:
    # Read optimization
    read_ahead_kb: 128 # Read-ahead buffer size
    use_mmap: true # Memory-mapped file access

    # Write optimization
    write_buffer_kb: 64 # Write buffer size
    sync_writes: false # Synchronous writes

    # Directory scanning
    scan_batch_size: 100 # Files per batch
    scan_delay_ms: 10 # Delay between batches

    # File watching
    watch_enabled: true # Monitor file changes
    watch_recursive: true # Watch subdirectories
    watch_debounce_ms: 100 # Debounce file events

Platform-Specific Optimizations

performance:
  platform:
    # Windows-specific
    windows:
      use_long_paths: true # Support paths > 260 chars
      file_attributes_cache: true

    # macOS-specific
    macos:
      use_spotlight: true # Use Spotlight for search
      fsevents_latency: 0.1 # File system event latency

    # Linux-specific
    linux:
      use_inotify: true # Use inotify for file watching
      sendfile_threshold: 64 # KB threshold for sendfile

Plugin Configuration

Plugin Management

plugins:
  enabled: true
  auto_update: false
  update_check_interval: 86400 # 24 hours

  # Plugin directories
  directories:
    - "~/.config/laxyfile/plugins"
    - "/usr/share/laxyfile/plugins"

  # Security settings
  security:
    allow_unsigned: false
    verify_checksums: true
    sandbox_plugins: true

Individual Plugin Configuration

Configure specific plugins:

# ~/.config/laxyfile/plugins/git-integration.yaml
git_integration:
  enabled: true
  show_status_icons: true
  auto_fetch: false
  fetch_interval: 300 # seconds

  # Git commands
  commands:
    status: "git status --porcelain"
    add: "git add"
    commit: "git commit -m"

  # UI integration
  ui:
    show_branch: true
    show_dirty_indicator: true
    status_colors:
      modified: "#f9e2af"
      added: "#a6e3a1"
      deleted: "#f38ba8"
      untracked: "#74c7ec"

# ~/.config/laxyfile/plugins/image-tools.yaml
image_tools:
  enabled: true

  # Thumbnail generation
  thumbnails:
    enabled: true
    size: 128
    quality: 85
    cache_dir: "~/.cache/laxyfile/thumbnails"

  # Image formats
  supported_formats:
    - "jpg"
    - "jpeg"
    - "png"
    - "gif"
    - "webp"
    - "bmp"
    - "tiff"

  # External tools
  tools:
    image_viewer: "feh"
    image_editor: "gimp"
    batch_converter: "imagemagick"

Advanced Settings

Logging Configuration

logging:
  enabled: true
  level: "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL

  # Log files
  files:
    main: "~/.config/laxyfile/logs/laxyfile.log"
    ai: "~/.config/laxyfile/logs/ai.log"
    performance: "~/.config/laxyfile/logs/performance.log"

  # Log rotation
  rotation:
    max_size_mb: 10
    backup_count: 5

  # Log format
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  date_format: "%Y-%m-%d %H:%M:%S"

  # Console logging
  console:
    enabled: false
    level: "WARNING"

Security Settings

security:
  # File access
  file_access:
    restrict_to_home: false
    allow_system_files: true
    follow_symlinks: false

  # Network security
  network:
    verify_ssl: true
    allow_insecure_connections: false
    trusted_hosts:
      - "api.openrouter.ai"
      - "localhost"

  # AI security
  ai:
    sanitize_inputs: true
    filter_sensitive_data: true
    log_ai_requests: false

  # Plugin security
  plugins:
    verify_signatures: true
    sandbox_enabled: true
    allowed_permissions:
      - "file_read"
      - "file_write"
      - "network_access"

Experimental Features

experimental:
  # Enable experimental features
  enabled: false

  # Feature flags
  features:
    new_ui_engine: false
    advanced_ai_models: false
    cloud_sync: false
    collaborative_editing: false

  # Beta testing
  beta_testing:
    enabled: false
    feedback_url: "https://feedback.laxyfile.com"
    crash_reporting: false

Import/Export Settings

Exporting Configuration

Export your settings for backup or sharing:

# Export all settings
laxyfile --export-config=my-config.yaml

# Export specific sections
laxyfile --export-config=themes.yaml --section=ui.themes
laxyfile --export-config=shortcuts.yaml --section=shortcuts

# Export with encryption
laxyfile --export-config=secure-config.yaml --encrypt

Importing Configuration

Import settings from backup or another user:

# Import all settings
laxyfile --import-config=my-config.yaml

# Import specific sections
laxyfile --import-config=themes.yaml --section=ui.themes

# Import with merge (don't overwrite existing)
laxyfile --import-config=config.yaml --merge

# Import from other file managers
laxyfile --import-from=ranger --config-path=~/.config/ranger/rc.conf

Migration Between Versions

LaxyFile automatically migrates configuration between versions:

migration:
  auto_migrate: true
  backup_before_migration: true
  backup_directory: "~/.config/laxyfile/backups"

  # Version-specific migrations
  migrations:
    "1.0_to_2.0":
      - "rename_theme_files"
      - "update_shortcut_format"
      - "migrate_ai_settings"

Configuration Validation

Validate your configuration files:

# Validate main config
laxyfile --validate-config

# Validate specific file
laxyfile --validate-config=~/.config/laxyfile/themes/my-theme.json

# Check for common issues
laxyfile --config-doctor

Configuration Examples

Minimal Configuration

# Minimal config for basic usage
ui:
  theme: "catppuccin"
  show_hidden_files: false

ai:
  enabled: false

performance:
  cache_size: 500

Power User Configuration

# Advanced configuration for power users
ui:
  theme: "tokyo-night"
  dual_pane_mode: true
  animations: true
  font_family: "JetBrains Mono"

ai:
  enabled: true
  provider: "openrouter"
  openrouter:
    model: "anthropic/claude-3-opus"
  features:
    file_analysis: true
    organization_suggestions: true
    security_analysis: true

performance:
  cache_size: 2000
  max_concurrent_operations: 16
  background_processing: true
  lazy_loading: true

shortcuts:
  scheme: "vim"

plugins:
  enabled: true
  directories:
    - "~/.config/laxyfile/plugins"
    - "~/dev/laxyfile-plugins"

Development Configuration

# Configuration for LaxyFile development
app:
  debug: true
  telemetry: false

logging:
  enabled: true
  level: "DEBUG"
  console:
    enabled: true
    level: "DEBUG"

experimental:
  enabled: true
  features:
    new_ui_engine: true
    advanced_ai_models: true

performance:
  memory_monitoring: true

security:
  plugins:
    sandbox_enabled: false # For plugin development

Troubleshooting Configuration

Common Configuration Issues

1. Invalid YAML Syntax:

   # Validate YAML syntax
   python -c "import yaml; yaml.safe_load(open('config.yaml'))"
   

2. Permission Issues:

   # Fix config directory permissions
   chmod 755 ~/.config/laxyfile
   chmod 644 ~/.config/laxyfile/config.yaml
   

3. Missing Dependencies:

   # Check for missing dependencies
   laxyfile --check-deps
   

Configuration Reset

Reset configuration to defaults:

# Reset all settings
laxyfile --reset-config

# Reset specific sections
laxyfile --reset-config --section=ui
laxyfile --reset-config --section=shortcuts

# Interactive reset
laxyfile --reset-config --interactive

Configuration Backup

Automatic configuration backup:

backup:
  enabled: true
  interval: 86400 # 24 hours
  max_backups: 10
  backup_directory: "~/.config/laxyfile/backups"

  # What to backup
  include:
    - "config.yaml"
    - "shortcuts.yaml"
    - "themes/"
    - "plugins/"

This configuration guide covers all aspects of customizing LaxyFile. For specific use cases or advanced configurations, consult the API documentation or ask in our community forum.