Skip to content

Add comprehensive WSL/Linux installation guide#1010

Closed
atabisz wants to merge 1 commit intodanielmiessler:mainfrom
atabisz:docs/wsl-installation-guide
Closed

Add comprehensive WSL/Linux installation guide#1010
atabisz wants to merge 1 commit intodanielmiessler:mainfrom
atabisz:docs/wsl-installation-guide

Conversation

@atabisz
Copy link
Copy Markdown

@atabisz atabisz commented Mar 31, 2026

Summary

Adds detailed WSL/Linux installation documentation to address common issues encountered during installation on WSL environments.

Changes

  • Prerequisites section: Added unzip installation (required for Bun)
  • Bun installation steps: Complete installation and PATH configuration
  • Hook fixes:
    • Execute permissions for hook files
    • Absolute path configuration for all 25 hooks
    • Environment variable expansion workaround for WSL
  • Bash shell support: PAI alias configuration for bash users (installer assumes zsh)
  • Optional user files: Instructions to eliminate startup warnings
  • Troubleshooting section: Comprehensive debugging steps for common WSL issues
    • Hook permission verification
    • Environment variable checking
    • Direct hook testing
    • GUI installer library dependencies
    • Identity placeholder configuration

Issues Addressed

  • Missing execute permissions on hook files in WSL
  • Environment variables (${HOME}, ${PAI_DIR}) not expanding in WSL hook execution contexts
  • Bash vs zsh shell differences (installer assumes zsh)
  • Missing dependencies for Bun installation
  • Hook error messages on startup
  • Identity placeholder configuration when installer is incomplete

Testing

Tested on WSL2 (Ubuntu) with bash shell. All hooks now execute successfully without errors.


Added detailed WSL/Linux installation notes including:
- Prerequisites (unzip for Bun installation)
- Bun runtime installation steps
- Hook permissions and path fixes for bash users
- Absolute path configuration for environment variable issues
- Optional user file creation to eliminate warnings
- Comprehensive troubleshooting section

Fixes common issues:
- Missing execute permissions on hook files
- Environment variables not expanding in WSL hook contexts
- Bash vs zsh shell differences
- Identity placeholder configuration
- GUI installer library dependencies
@atabisz atabisz closed this by deleting the head repository Apr 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant