docs: restructure README into focused docs

Move build instructions, configuration, troubleshooting, and
uninstall guides to dedicated files under docs/. Replace hosted
screenshot URLs with repo-local images.

Co-Authored-By: Claude <claude@anthropic.com>
This commit is contained in:
aaddrick
2026-02-16 19:45:40 -05:00
parent 7464a11a80
commit 6a74c4fafe
6 changed files with 287 additions and 244 deletions

249
README.md
View File

@@ -24,11 +24,9 @@ This project provides build scripts to run Claude Desktop natively on Linux syst
### Screenshots
![Claude Desktop running on Linux](https://github.com/user-attachments/assets/93080028-6f71-48bd-8e59-5149d148cd45)
![Claude Desktop running on Linux](https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot1.png)
![Global hotkey popup](https://github.com/user-attachments/assets/1deb4604-4c06-4e4b-b63f-7f6ef9ef28c1)
![System tray menu on KDE](https://github.com/user-attachments/assets/ba209824-8afb-437c-a944-b53fd9ecd559)
![Global hotkey popup](https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot2.png)
## Installation
@@ -84,257 +82,20 @@ Download the latest `.deb`, `.rpm`, or `.AppImage` from the [Releases page](http
### Building from Source
#### Prerequisites
- Linux distribution (Debian/Ubuntu, Fedora/RHEL, or other)
- Git
- Basic build tools (automatically installed by the script)
#### Build Instructions
```bash
# Clone the repository
git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian
# Build with auto-detected format (based on your distro)
./build.sh
# Or specify a format explicitly:
./build.sh --build deb # Debian/Ubuntu .deb package
./build.sh --build rpm # Fedora/RHEL .rpm package
./build.sh --build appimage # Distribution-agnostic AppImage
# Build with custom options
./build.sh --build deb --clean no # Keep intermediate files
# Build using a locally downloaded installer
# (useful when the bundled download URL is outdated)
./build.sh --exe /path/to/Claude-Setup.exe
```
The build script automatically detects your distribution and selects the appropriate package format:
| Distribution | Default Format | Package Manager |
|--------------|----------------|-----------------|
| Debian, Ubuntu, Mint | `.deb` | apt |
| Fedora, RHEL, CentOS | `.rpm` | dnf |
| Arch Linux | `.AppImage` (via AUR) | yay/paru |
| Other | `.AppImage` | - |
#### Installing the Built Package
**For .deb packages (Debian/Ubuntu):**
```bash
sudo apt install ./claude-desktop_VERSION_ARCHITECTURE.deb
# Or: sudo dpkg -i ./claude-desktop_VERSION_ARCHITECTURE.deb
# If you encounter dependency issues:
sudo apt --fix-broken install
```
**For .rpm packages (Fedora/RHEL):**
```bash
sudo dnf install ./claude-desktop-VERSION-1.ARCH.rpm
# Or: sudo rpm -i ./claude-desktop-VERSION-1.ARCH.rpm
```
**For AppImages:**
```bash
# Make executable
chmod +x ./claude-desktop-*.AppImage
# Run directly
./claude-desktop-*.AppImage
# Or integrate with your system using Gear Lever
```
**Note:** AppImage login requires proper desktop integration. Use [Gear Lever](https://flathub.org/apps/it.mijorus.gearlever) or manually install the provided `.desktop` file to `~/.local/share/applications/`.
**Automatic Updates:** AppImages downloaded from GitHub releases include embedded update information and work seamlessly with Gear Lever for automatic updates. Locally-built AppImages can be manually configured for updates in Gear Lever.
See [docs/BUILDING.md](docs/BUILDING.md) for detailed build instructions.
## Configuration
### MCP Configuration
Model Context Protocol settings are stored in:
```
~/.config/Claude/claude_desktop_config.json
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_USE_WAYLAND` | unset | Set to `1` to use native Wayland instead of XWayland. Note: Global hotkeys won't work in native Wayland mode. |
**Wayland Note:** By default, Claude Desktop uses X11 mode (via XWayland) on Wayland sessions to ensure global hotkeys work. If you prefer native Wayland and don't need global hotkeys:
```bash
# One-time launch
CLAUDE_USE_WAYLAND=1 claude-desktop
# Or add to your environment permanently
export CLAUDE_USE_WAYLAND=1
```
### Application Logs
Runtime logs are available at:
```
~/.cache/claude-desktop-debian/launcher.log
```
## Uninstallation
**For APT repository installations (Debian/Ubuntu):**
```bash
# Remove package
sudo apt remove claude-desktop
# Remove the repository and GPG key
sudo rm /etc/apt/sources.list.d/claude-desktop.list
sudo rm /usr/share/keyrings/claude-desktop.gpg
```
**For DNF repository installations (Fedora/RHEL):**
```bash
# Remove package
sudo dnf remove claude-desktop
# Remove the repository
sudo rm /etc/yum.repos.d/claude-desktop.repo
```
**For AUR installations (Arch Linux):**
```bash
# Using yay
yay -R claude-desktop-appimage
# Or using paru
paru -R claude-desktop-appimage
# Or using pacman directly
sudo pacman -R claude-desktop-appimage
```
**For .deb packages (manual install):**
```bash
# Remove package
sudo apt remove claude-desktop
# Or: sudo dpkg -r claude-desktop
# Remove package and configuration
sudo dpkg -P claude-desktop
```
**For .rpm packages:**
```bash
# Remove package
sudo dnf remove claude-desktop
# Or: sudo rpm -e claude-desktop
```
**For AppImages:**
1. Delete the `.AppImage` file
2. Remove the `.desktop` file from `~/.local/share/applications/`
3. If using Gear Lever, use its uninstall option
**Remove user configuration (both formats):**
```bash
rm -rf ~/.config/Claude
```
For additional configuration options including environment variables and Wayland support, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
## Troubleshooting
### Window Scaling Issues
If the window doesn't scale correctly on first launch:
1. Right-click the Claude Desktop tray icon
2. Select "Quit" (do not force quit)
3. Restart the application
This allows the application to save display settings properly.
### Global Hotkey Not Working (Wayland)
If the global hotkey (Ctrl+Alt+Space) doesn't work, ensure you're not running in native Wayland mode:
1. Check your logs at `~/.cache/claude-desktop-debian/launcher.log`
2. Look for "Using X11 backend via XWayland" - this means hotkeys should work
3. If you see "Using native Wayland backend", unset `CLAUDE_USE_WAYLAND` or ensure it's not set to `1`
**Note:** Native Wayland mode doesn't support global hotkeys due to Electron/Chromium limitations with XDG GlobalShortcuts Portal.
### AppImage Sandbox Warning
AppImages run with `--no-sandbox` due to electron's chrome-sandbox requiring root privileges for unprivileged namespace creation. This is a known limitation of AppImage format with Electron applications.
For enhanced security, consider:
- Using the .deb package instead
- Running the AppImage within a separate sandbox (e.g., bubblewrap)
- Using Gear Lever's integrated AppImage management for better isolation
### Authentication Errors (401)
If you encounter recurring "API Error: 401" messages after periods of inactivity, the cached OAuth token may need to be cleared. This is an upstream application issue reported in [#156](https://github.com/aaddrick/claude-desktop-debian/issues/156).
To fix manually (credit: [MrEdwards007](https://github.com/MrEdwards007)):
1. Close Claude Desktop completely
2. Edit `~/.config/Claude/config.json`
3. Remove the line containing `"oauth:tokenCache"` (and any trailing comma if needed)
4. Save the file and restart Claude Desktop
5. Log in again when prompted
A scripted solution is also available at the bottom of [this comment](https://github.com/aaddrick/claude-desktop-debian/issues/156#issuecomment-2682547498).
## Technical Details
### How It Works
Claude Desktop is an Electron application distributed for Windows. This project:
1. Downloads the official Windows installer
2. Extracts application resources
3. Replaces Windows-specific native modules with Linux-compatible implementations
4. Repackages as one of:
- **Debian package (.deb)**: For Debian, Ubuntu, and derivatives
- **RPM package (.rpm)**: For Fedora, RHEL, CentOS, and derivatives
- **AppImage**: Portable, distribution-agnostic executable
### Build Process
The build script (`build.sh`) handles:
- Dependency checking and installation
- Resource extraction from Windows installer
- Icon processing for Linux desktop standards
- Native module replacement
- Package generation based on selected format
### Automated Version Detection
A GitHub Actions workflow runs daily to check for new Claude Desktop releases:
1. Uses Playwright to resolve Anthropic's Cloudflare-protected download redirects
2. Compares resolved URLs with those in `build.sh`
3. If a new version is detected:
- Updates `build.sh` with new download URLs
- Creates a new release tag
- Triggers automated builds for both architectures
This ensures the repository stays up-to-date with official releases automatically.
### Manual Updates
If you need to build with a specific version before the automation catches it:
1. **Use a local installer**: Download the latest installer from [claude.ai/download](https://claude.ai/download) and build with:
```bash
./build.sh --exe /path/to/Claude-Setup.exe
```
2. **Update the URL**: Modify the `CLAUDE_DOWNLOAD_URL` variables in `build.sh`.
For troubleshooting common issues, uninstallation instructions, and log locations, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
## Acknowledgments

122
docs/BUILDING.md Normal file
View File

@@ -0,0 +1,122 @@
[< Back to README](../README.md)
# Building from Source
## Prerequisites
- Linux distribution (Debian/Ubuntu, Fedora/RHEL, or other)
- Git
- Basic build tools (automatically installed by the script)
## Build Instructions
```bash
# Clone the repository
git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian
# Build with auto-detected format (based on your distro)
./build.sh
# Or specify a format explicitly:
./build.sh --build deb # Debian/Ubuntu .deb package
./build.sh --build rpm # Fedora/RHEL .rpm package
./build.sh --build appimage # Distribution-agnostic AppImage
# Build with custom options
./build.sh --build deb --clean no # Keep intermediate files
# Build using a locally downloaded installer
# (useful when the bundled download URL is outdated)
./build.sh --exe /path/to/Claude-Setup.exe
```
The build script automatically detects your distribution and selects the appropriate package format:
| Distribution | Default Format | Package Manager |
|--------------|----------------|-----------------|
| Debian, Ubuntu, Mint | `.deb` | apt |
| Fedora, RHEL, CentOS | `.rpm` | dnf |
| Arch Linux | `.AppImage` (via AUR) | yay/paru |
| Other | `.AppImage` | - |
## Installing the Built Package
### For .deb packages (Debian/Ubuntu)
```bash
sudo apt install ./claude-desktop_VERSION_ARCHITECTURE.deb
# Or: sudo dpkg -i ./claude-desktop_VERSION_ARCHITECTURE.deb
# If you encounter dependency issues:
sudo apt --fix-broken install
```
### For .rpm packages (Fedora/RHEL)
```bash
sudo dnf install ./claude-desktop-VERSION-1.ARCH.rpm
# Or: sudo rpm -i ./claude-desktop-VERSION-1.ARCH.rpm
```
### For AppImages
```bash
# Make executable
chmod +x ./claude-desktop-*.AppImage
# Run directly
./claude-desktop-*.AppImage
# Or integrate with your system using Gear Lever
```
**Note:** AppImage login requires proper desktop integration. Use [Gear Lever](https://flathub.org/apps/it.mijorus.gearlever) or manually install the provided `.desktop` file to `~/.local/share/applications/`.
**Automatic Updates:** AppImages downloaded from GitHub releases include embedded update information and work seamlessly with Gear Lever for automatic updates. Locally-built AppImages can be manually configured for updates in Gear Lever.
## Technical Details
### How It Works
Claude Desktop is an Electron application distributed for Windows. This project:
1. Downloads the official Windows installer
2. Extracts application resources
3. Replaces Windows-specific native modules with Linux-compatible implementations
4. Repackages as one of:
- **Debian package (.deb)**: For Debian, Ubuntu, and derivatives
- **RPM package (.rpm)**: For Fedora, RHEL, CentOS, and derivatives
- **AppImage**: Portable, distribution-agnostic executable
### Build Process
The build script (`build.sh`) handles:
- Dependency checking and installation
- Resource extraction from Windows installer
- Icon processing for Linux desktop standards
- Native module replacement
- Package generation based on selected format
### Automated Version Detection
A GitHub Actions workflow runs daily to check for new Claude Desktop releases:
1. Uses Playwright to resolve Anthropic's Cloudflare-protected download redirects
2. Compares resolved URLs with those in `build.sh`
3. If a new version is detected:
- Updates `build.sh` with new download URLs
- Creates a new release tag
- Triggers automated builds for both architectures
This ensures the repository stays up-to-date with official releases automatically.
### Manual Updates
If you need to build with a specific version before the automation catches it:
1. **Use a local installer**: Download the latest installer from [claude.ai/download](https://claude.ai/download) and build with:
```bash
./build.sh --exe /path/to/Claude-Setup.exe
```
2. **Update the URL**: Modify the `CLAUDE_DOWNLOAD_URL` variables in `build.sh`.

37
docs/CONFIGURATION.md Normal file
View File

@@ -0,0 +1,37 @@
[< Back to README](../README.md)
# Configuration
## MCP Configuration
Model Context Protocol settings are stored in:
```
~/.config/Claude/claude_desktop_config.json
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_USE_WAYLAND` | unset | Set to `1` to use native Wayland instead of XWayland. Note: Global hotkeys won't work in native Wayland mode. |
### Wayland Support
By default, Claude Desktop uses X11 mode (via XWayland) on Wayland sessions to ensure global hotkeys work. If you prefer native Wayland and don't need global hotkeys:
```bash
# One-time launch
CLAUDE_USE_WAYLAND=1 claude-desktop
# Or add to your environment permanently
export CLAUDE_USE_WAYLAND=1
```
**Important:** Native Wayland mode doesn't support global hotkeys due to Electron/Chromium limitations with XDG GlobalShortcuts Portal. If global hotkeys (Ctrl+Alt+Space) are important to your workflow, keep the default X11 mode.
## Application Logs
Runtime logs are available at:
```
~/.cache/claude-desktop-debian/launcher.log
```

123
docs/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,123 @@
[< Back to README](../README.md)
# Troubleshooting
## Application Logs
Runtime logs are available at:
```
~/.cache/claude-desktop-debian/launcher.log
```
## Common Issues
### Window Scaling Issues
If the window doesn't scale correctly on first launch:
1. Right-click the Claude Desktop tray icon
2. Select "Quit" (do not force quit)
3. Restart the application
This allows the application to save display settings properly.
### Global Hotkey Not Working (Wayland)
If the global hotkey (Ctrl+Alt+Space) doesn't work, ensure you're not running in native Wayland mode:
1. Check your logs at `~/.cache/claude-desktop-debian/launcher.log`
2. Look for "Using X11 backend via XWayland" - this means hotkeys should work
3. If you see "Using native Wayland backend", unset `CLAUDE_USE_WAYLAND` or ensure it's not set to `1`
**Note:** Native Wayland mode doesn't support global hotkeys due to Electron/Chromium limitations with XDG GlobalShortcuts Portal.
See [CONFIGURATION.md](CONFIGURATION.md) for more details on the `CLAUDE_USE_WAYLAND` environment variable.
### AppImage Sandbox Warning
AppImages run with `--no-sandbox` due to electron's chrome-sandbox requiring root privileges for unprivileged namespace creation. This is a known limitation of AppImage format with Electron applications.
For enhanced security, consider:
- Using the .deb package instead
- Running the AppImage within a separate sandbox (e.g., bubblewrap)
- Using Gear Lever's integrated AppImage management for better isolation
### Authentication Errors (401)
If you encounter recurring "API Error: 401" messages after periods of inactivity, the cached OAuth token may need to be cleared. This is an upstream application issue reported in [#156](https://github.com/aaddrick/claude-desktop-debian/issues/156).
To fix manually (credit: [MrEdwards007](https://github.com/MrEdwards007)):
1. Close Claude Desktop completely
2. Edit `~/.config/Claude/config.json`
3. Remove the line containing `"oauth:tokenCache"` (and any trailing comma if needed)
4. Save the file and restart Claude Desktop
5. Log in again when prompted
A scripted solution is also available at the bottom of [this comment](https://github.com/aaddrick/claude-desktop-debian/issues/156#issuecomment-2682547498).
## Uninstallation
### For APT repository installations (Debian/Ubuntu)
```bash
# Remove package
sudo apt remove claude-desktop
# Remove the repository and GPG key
sudo rm /etc/apt/sources.list.d/claude-desktop.list
sudo rm /usr/share/keyrings/claude-desktop.gpg
```
### For DNF repository installations (Fedora/RHEL)
```bash
# Remove package
sudo dnf remove claude-desktop
# Remove the repository
sudo rm /etc/yum.repos.d/claude-desktop.repo
```
### For AUR installations (Arch Linux)
```bash
# Using yay
yay -R claude-desktop-appimage
# Or using paru
paru -R claude-desktop-appimage
# Or using pacman directly
sudo pacman -R claude-desktop-appimage
```
### For .deb packages (manual install)
```bash
# Remove package
sudo apt remove claude-desktop
# Or: sudo dpkg -r claude-desktop
# Remove package and configuration
sudo dpkg -P claude-desktop
```
### For .rpm packages
```bash
# Remove package
sudo dnf remove claude-desktop
# Or: sudo rpm -e claude-desktop
```
### For AppImages
1. Delete the `.AppImage` file
2. Remove the `.desktop` file from `~/.local/share/applications/`
3. If using Gear Lever, use its uninstall option
### Remove user configuration (all formats)
```bash
rm -rf ~/.config/Claude
```

Binary file not shown.

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB