claude-desktop-asahi
CLAUDE.md1 starsChanged 6 months agoApache-2.0View on GitHub
These documents are the source of truth. If anything in this file conflicts with them, they win. Read them before opening a non-trivial issue or PR. This file is a fast reference for the highest-leverage rules and the project's accumulated archaeology. New policy goes in the style guides or CONTRIBUTING.md. This project repackages Claude Desktop (Electron app) for Debian/Ubuntu Linux, applying necessary patches for Linux compatibility. The docs/learnings/ directory contains hard-won technical knowledge from debugging and fixing issues — things…
- Deletes or force-pushes
- Installs packages
- Commits and pushes
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- implement-issueSkill
- improvement-loopSkill
- lintSkill
- setup-build-toolsSkill
- simplifySkill
- triageSkill
- writing-agentsSkill
- writing-skillsSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
27 rules. About 0 are common, 9 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 46
All shell scripts in this project must follow the Bash Style Guide.
- Very specific: line 49
Use [[ ]] for conditionals, $(...) for command substitution
- Very specific: line 52
Use local in functions, avoid set -e and eval
- Very specific: line 57
Don't
eval: Use arrays for argv composition (cmd "${args[@]}"). - Very specific: line 58
Don't use POSIX
[ ... ]: Always [[ ... ]]. POSIX [ mis-parses unquoted expansions in ways [[ does not. - Very specific: line 59
Don't backtick: Always $(...). Backticks don't nest cleanly and conflict with markdown when patches are pasted into PR comments.
- Very specific: line 69
Disable directives are a last resort: - Only use # shellcheck disable=SCXXXX when:
- Distinctive: line 72
Always add a comment explaining why the disable is needed
- Very specific: line 73
Run
/lintto check manually: - Use this skill to check for issues before pushing - Very specific: line 89
Use gh CLI for all GitHub interactions
- Very specific: line 90
Create branches based on issue numbers: fix/123-description or feature/123-description
- Distinctive: line 92
After creating a PR, add a comment to the related issue with a summary and link to the PR
- Very specific: line 130
Use the actual model name (e.g., Claude Opus 4.5, Claude Sonnet 4)
- Very specific: line 160
Always use regex patterns: when modifying the source JavaScript.
- Very specific: line 199
If build-reference/ is missing or you need to inspect source for a new version, follow these steps to download, extract, and beautify the …
- Distinctive: line 303
When adding support for new distribution formats (e.g., RPM, Flatpak, Snap) or package repositories, follow these guidelines to avoid …
- Distinctive: line 312
Search for existing CI implementations: - Look for "GitHub Actions [format] signing" or similar.
- Very specific: line 318
Multiple jobs writing to the same branch will race: - If APT and DNF repos both push to gh-pages, add:
- Distinctive: line 326
Test CI steps locally first: - Run the signing/packaging commands manually to catch errors before committing.
- Distinctive: line 328
Use a test tag for new infrastructure: - Create a non-release tag to validate the full CI pipeline before merging to main.
- Distinctive: line 330
Verify the end-user experience: - After CI succeeds, actually test the install commands from the README on a clean system.
- Very specific: line 437
Run with logging: ./app.AppImage 2>&1 | tee ~/.cache/claude-desktop-debian/launcher.log
- Very specific: line 468
When upstream Claude Desktop updates, the check-claude-version workflow automatically updates CLAUDE_DESKTOP_VERSION, patches the URLs in …
- Distinctive: line 474
Killing the app: - Must kill all electron child processes, not just the main one:
- Very specific: line 478
SingletonLock: - If app won't start, check for stale lock: ~/.config/Claude/SingletonLock
- Very specific: line 480
Nix hashes: - When Claude Desktop version changes, both the URLs in scripts/setup/detect-host.sh and nix/claude-desktop.nix (version, URLs, …
- Very specific: line 493
Update both amd64 and arm64 URLs in detect_architecture() to match main
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude Desktop Debian - Development Notes
<!--
This file is read by Claude Code. The content below is duplicated in
AGENTS.md (read by other AI tools per the agents.md standard) so that
contributors using either receive the same instructions without needing
to cross-reference. Keep CLAUDE.md and AGENTS.md byte-identical below
the H1 title (the sync-policy comment above is the one place they
intentionally differ) — if you edit one, edit the other.
-->Required reading
These documents are the source of truth. If anything in this file conflicts with them, they win. Read them before opening a non-trivial issue or PR.
CONTRIBUTING.md— what we accept, what goes upstream, subsystem owners, AI-attribution policy.docs/styleguides/bash_styleguide.md— shell-script conventions (forked from YSAP). Tabs, 80 cols,[[ ]], noset -e, noeval.docs/styleguides/docs_styleguide.md— page anatomy, naming, antipatterns for thedocs/tree.docs/index.md— entry point for the rest of the repo docs.SECURITY.md— vulnerability reporting; what's in scope vs. upstream.
This file is a fast reference for the highest-leverage rules and the project's accumulated archaeology. New policy goes in the style guides or CONTRIBUTING.md.
Project Overview
This project repackages Claude Desktop (Electron app) for Debian/Ubuntu Linux, applying necessary patches for Linux compatibility.
Learnings
The docs/learnings/ directory contains hard-won technical knowledge from debugging and fixing issues — things that aren't obvious from reading the code or docs alone. Consult these before working on related areas. Add new entries when you discover something non-obvious that would save future contributors (human or AI) significant time.
nix.md— NixOS packaging, Electron resource path resolution, testing without NixOScowork-vm-daemon.md— Cowork VM daemon lifecycle, respawn logic, crash diagnosisplugin-install.md— Anthropic & Partners plugin install flow, gate logic, backend endpoints, and DevTools recipesapt-worker-architecture.md— APT/DNF binary distribution via Cloudflare Worker + GitHub Releases, redirect chain, credential ownership, heartbeat runbooktray-rebuild-race.md— why destroy + recreate onnativeThemeupdates briefly duplicates the tray icon on KDE Plasma, and the in-placesetImage+setContextMenufast-path that avoids the SNI re-registration racemcp-double-spawn.md— Stdio MCPs spawn 2× when chat and Code/Agent panels are both active, root cause in upstream session managers, MCP-author workaroundlinux-topbar-shim.md— why claude.ai's in-app topbar is missing on Linux, the four gates that hide it, why the upstreamframe:false+ WCO config has unclickable buttons on X11 (Chromium-level implicit drag region), and the resolution: hybrid mode (system frame + UA-spoof shim → stacked layout, full button functionality)test-harness-electron-hooks.md— why constructor-levelBrowserWindowwraps are silently bypassed byframe-fix-wrapper's Proxy, and the prototype-method hook pattern that works (used by the Quick Entry test runners)test-harness-ax-tree-walker.md— five non-obvious traps in the v7 fingerprint walker after the AX-tree migration: AX-enable async lag, navigateTo-to-same-URL no-op, claude.ai's flatdialog>button[]lists, themore options for Xper-row shape, and sidebar virtualization vs the lookup-failure thresholdwayland-global-shortcuts-portal.md— why Quick Entry's hotkey is focus-bound on GNOME Wayland (mutter dropped XWayland global key grabs), the native-Wayland +GlobalShortcutsPortallauncher change (opt-in viaCLAUDE_USE_WAYLAND=1; fixes GNOME ≤49, default GNOME stays on XWayland), the "only the last--enable-featuresswitch wins → merge into one flag" trap, the tri-stateCLAUDE_USE_WAYLANDescape hatch, and the proof that GNOME 50 / xdg-desktop-portal ≥1.20 is still blocked upstream because Electron/Chromium never calls the hostRegistry.Registerapp-id handshake (electron#51875); wlroots (Niri/Sway/Hyprland) lack a portal GlobalShortcuts backend entirelypatching-minified-js.md— general lessons from maintaining a long-lived patch suite against an actively re-minified upstream: anchor selection (literals over identifiers), the\wvs$identifier-capture trap, beautified false-negatives, idempotency guards, multi-site coordination, non-unique anchor disambiguation, and the SHA-256-pinned hypothesis-verification recipe
Code Style
All shell scripts in this project must follow the Bash Style Guide. Key points:
- Tabs for indentation, lines under 80 characters (exception: URLs and regex patterns)
- Use
[[ ]]for conditionals,$(...)for command substitution - Single quotes for literals, double quotes for expansions
- Lowercase variables; UPPERCASE only for constants/exports
- Use
localin functions, avoidset -eandeval
Anti-patterns
- Don't
set -e. It interacts badly with$(...)capture and function return values, and the project has historically debugged enough silent exits to settle the question. Check status explicitly:cmd || handle_err. - Don't
eval. Use arrays for argv composition (cmd "${args[@]}").evaldefeats every parser and is a permanent SC2046 magnet. - Don't use POSIX
[ ... ]. Always[[ ... ]]. POSIX[mis-parses unquoted expansions in ways[[does not. - Don't backtick. Always
$(...). Backticks don't nest cleanly and conflict with markdown when patches are pasted into PR comments. - Don't hardcode the work directory. Scripts that operate during a build use
$work_dir(set bybuild.sh). A hardcoded path silently breaks the AppImage build, which runs in a different layout from the deb/rpm builds. - Don't wrap commands in
if cmd; then true; else false; fi-style scaffolding. Justcmd— the exit code is already there. - Don't append to a baseline file to silence
shellcheck. Fix the underlying issue. If a warning is genuinely a false positive, use a per-line# shellcheck disable=SCXXXXwith a comment explaining why.
Linting
Shell scripts are checked with shellcheck and GitHub Actions workflows with actionlint before pushing. When lint issues are found:
- Fix the code - Correct the underlying issue rather than suppressing the warning
- Disable directives are a last resort - Only use
# shellcheck disable=SCXXXXwhen:- The warning is a false positive
- The pattern is intentional and unavoidable
- Always add a comment explaining why the disable is needed
- Run
/lintto check manually - Use this skill to check for issues before pushing
Docs
- One declarative sentence then a code block or list at the top of every page. No "In this guide we will explore…" preamble. See
docs/styleguides/docs_styleguide.md. - Lowercase kebab-case filenames for everything in
docs/. Order belongs indocs/index.md, not filenames or numeric prefixes. - Real domain nouns over
foo/barin walkthroughs. The project vocabulary ispatches,the launcher,the worker,app.asar,the minified bundle,the asar archive,the doctor surface. - Subsystem deep-dives go under
docs/learnings/. Surfacing knowledge there beats burying it in commit messages or in patch-script comments. Add an entry when you discover something non-obvious that would save the next contributor significant time. - Decisions go in
docs/decisions.md(ADR format). Don't relitigate a settled direction inside a how-to page; link the decision instead. - Troubleshooting headings are the literal symptom, not editorialized prose.
## Black screen on Fedora KDE under Wayland, not## Troubles with Wayland. Search ranks headings. - CHANGELOG follows Keep a Changelog 1.1.0. Bullets grouped under Added / Fixed / Changed / Deprecated / Removed / Security; one bullet per change; PR link for the deep dive; inline BREAKING prefix for breaking changes. See
CHANGELOG.mdfor the current state andRELEASING.mdfor when entries get promoted from[Unreleased].
GitHub Workflow
General Approach
- Use
ghCLI for all GitHub interactions - Create branches based on issue numbers:
fix/123-descriptionorfeature/123-description - Reference issues in commits and PRs with
#123orFixes #123 - After creating a PR, add a comment to the related issue with a summary and link to the PR
Investigating Issues
For older issues, review the state of the code when the issue was raised - it may have already been addressed:
# Get issue creation date
gh issue view 123 --json createdAt
# Find the commit just before the issue was created
git log --oneline --until="2025-08-23T08:48:35Z" -1
# View a file at that point in time
git show <commit>:path/to/file.sh
# Search for relevant changes since the issue was created
git log --oneline --after="2025-08-23" -- path/to/file.sh
# View a specific commit that may have fixed the issue
git show <commit>This helps identify if the issue was already fixed, and allows referencing the specific commit in the response.
Attribution
For PR descriptions, include full attribution:
---
Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <model-name> <noreply@anthropic.com>
<XX>% AI / <YY>% Human
Claude: <what AI did>
Human: <what human did>- Use the actual model name (e.g.,
Claude Opus 4.5,Claude Sonnet 4) - The percentage split should honestly reflect the contribution balance for that specific work
- This provides a trackable record of AI-assisted development over time
For issues and comments, use simplified attribution:
---
Written by Claude <model-name> via [Claude Code](https://claude.ai/code)For commits, include a Co-Authored-By trailer:
Co-Authored-By: Claude <claude@anthropic.com>Contributor Credits
The README Acknowledgments section credits external contributors in chronological order (by merge date or fix date). Update it when:
- Merging an external PR — Add the author to the Acknowledgments list with a link to their GitHub profile and a brief description of their contribution.
- Implementing a fix suggested in an issue — If an issue author (or commenter) provided a concrete fix, workaround, code snippet, or detailed technical analysis that was directly used, credit them too.
Contributors are listed in chronological order: inspirational projects first (k3d3, emsi, leobuskin), then contributors ordered by when their contribution was merged or implemented.
Working with Minified JavaScript
Important Guidelines
- Always use regex patterns when modifying the source JavaScript. Patches live in
scripts/patches/*.sh(one file per subsystem:tray.sh,cowork.sh,claude-code.sh, etc.);build.shis only an orchestrator that sources them. Variable and function names are minified and change between releases. - The beautified code in
build-reference/has different spacing than the actual minified code in the app. Patterns must handle both:- Minified:
oe.nativeTheme.on("updated",()=>{ - Beautified:
oe.nativeTheme.on("updated", () => {
- Minified:
- Use
-Eflag with sed for extended regex support when patterns need grouping or alternation. - Extract variable names dynamically rather than hardcoding them. Shared extraction helpers live in
scripts/patches/_common.sh. Example:# Extract function name from a known pattern TRAY_FUNC=$(grep -oP 'on\("menuBarEnabled",\(\)=>\{\K[$\w]+(?=\(\)\})' app.asar.contents/.vite/build/index.js) - Handle optional whitespace in regex patterns:
# Bad: assumes no spaces sed -i 's/oe.nativeTheme.on("updated",()=>{/...' # Good: handles optional whitespace sed -i -E 's/(oe\.nativeTheme\.on\(\s*"updated"\s*,\s*\(\)\s*=>\s*\{)/...'
Reference Files
build-reference/app-extracted/- Extracted and beautified source for analysisbuild-reference/tray-icons/- Tray icon assets for reference
Frame Fix Wrapper
The app uses a wrapper system to intercept and fix Electron behavior for Linux:
frame-fix-wrapper.js- Interceptsrequire('electron')to patch BrowserWindow defaults (e.g.,frame: truefor proper window decorations on Linux)frame-fix-entry.js- Entry point that loads the wrapper before the main app
These are injected by scripts/patches/app-asar.sh (inside patch_app_asar) and referenced in package.json's main field. The wrapper pattern allows fixing Electron behavior without modifying the minified app code directly.
Setting Up build-reference
If build-reference/ is missing or you need to inspect source for a new version, follow these steps to download, extract, and beautify the source code.
Prerequisites
# Install required tools
sudo apt install p7zip-full wget nodejs npm
# Install asar and prettier globally (or use npx)
npm install -g @electron/asar prettierStep 1: Download the Windows Installer
The Windows installer contains the app.asar which has the full Electron app source.
# Create working directory
mkdir -p build-reference && cd build-reference
# Download URL pattern (update version as needed):
# x64: https://downloads.claude.ai/releases/win32/x64/VERSION/Claude-COMMIT.exe
# arm64: https://downloads.claude.ai/releases/win32/arm64/VERSION/Claude-COMMIT.exe
# Example for version 1.1.381:
wget -O Claude-Setup-x64.exe "https://downloads.claude.ai/releases/win32/x64/1.1.381/Claude-c2a39e9c82f5a4d51f511f53f532afd276312731.exe"Step 2: Extract the Installer
# Extract the exe (it's a 7z archive)
7z x -y Claude-Setup-x64.exe -o"exe-contents"
# Find and extract the nupkg
cd exe-contents
NUPKG=$(find . -name "AnthropicClaude-*.nupkg" | head -1)
7z x -y "$NUPKG" -o"nupkg-contents"
cd ..
# Copy out the important files
cp exe-contents/nupkg-contents/lib/net45/resources/app.asar .
cp -a exe-contents/nupkg-contents/lib/net45/resources/app.asar.unpacked .
# Optional: copy tray icons for reference
mkdir -p tray-icons
cp exe-contents/nupkg-contents/lib/net45/resources/*.png tray-icons/ 2>/dev/null || true
cp exe-contents/nupkg-contents/lib/net45/resources/*.ico tray-icons/ 2>/dev/null || trueStep 3: Extract app.asar
# Extract the asar archive
asar extract app.asar app-extractedStep 4: Beautify the JavaScript Files
The extracted JS files are minified. Use prettier to make them readable:
# Beautify all JS files in the build directory
npx prettier --write "app-extracted/.vite/build/*.js"
# Or beautify specific files
npx prettier --write app-extracted/.vite/build/index.js
npx prettier --write app-extracted/.vite/build/mainWindow.jsStep 5: Clean Up (Optional)
# Remove intermediate files, keep only what's needed for reference
rm -rf exe-contents
rm Claude-Setup-x64.exe
rm -rf app.asar app.asar.unpacked # Keep only app-extractedFinal Structure
build-reference/
├── app-extracted/
│ ├── .vite/
│ │ ├── build/
│ │ │ ├── index.js # Main process (beautified)
│ │ │ ├── mainWindow.js # Main window preload
│ │ │ ├── mainView.js # Main view preload
│ │ │ └── ...
│ │ └── renderer/
│ │ └── ...
│ ├── node_modules/
│ │ └── @ant/claude-native/ # Native bindings (stubs)
│ └── package.json
├── tray-icons/
│ ├── TrayIconTemplate.png # Black icon (for light panels)
│ ├── TrayIconTemplate-Dark.png # White icon (for dark panels)
│ └── ...
└── nupkg-contents/ # Optional: full extracted nupkgAdding New Package Formats or Repositories
When adding support for new distribution formats (e.g., RPM, Flatpak, Snap) or package repositories, follow these guidelines to avoid iterative debugging in CI.
Research Before Implementing
- Understand the target system's constraints - Each package format has specific rules:
- Version string formats (e.g., RPM cannot have hyphens in Version field)
- Required metadata fields
- Signing requirements and tools
- Search for existing CI implementations - Look for "GitHub Actions [format] signing" or similar. Existing workflows reveal required flags, environment setup, and common pitfalls.
- Check tool behavior in non-interactive environments - CI has no TTY. Tools like GPG need flags like
--batchand--yesto work without prompts.
Consider Concurrency
- Multiple jobs writing to the same branch will race - If APT and DNF repos both push to
gh-pages, add:- Job dependencies (
needs: [other-job]), or - Retry loops with
git pull --rebasebefore push
- Job dependencies (
- External processes may also modify branches - GitHub Pages deployment runs automatically and can cause push conflicts.
Test the Full Pipeline
- Test CI steps locally first - Run the signing/packaging commands manually to catch errors before committing.
- Use a test tag for new infrastructure - Create a non-release tag to validate the full CI pipeline before merging to main.
- Verify the end-user experience - After CI succeeds, actually test the install commands from the README on a clean system.
Common CI Pitfalls
| Issue | Solution |
| GPG "cannot open /dev/tty" | Add --batch flag |
| GPG "File exists" error | Add --yes flag to overwrite |
| Push rejected (ref changed) | Add git pull --rebase before push, with retry loop |
| Version format invalid | Research target format's version constraints upfront |
| Signing key not found | Ensure key is imported before signing step, check key ID output |
CI/CD
Triggering Builds
# Trigger CI on a branch
gh workflow run CI --ref branch-name
# Watch the run
gh run watch RUN_ID
# Download artifacts
gh run download RUN_ID -n artifact-nameBuild Artifacts
claude-desktop-VERSION-amd64.deb- Debian package for x86_64claude-desktop-VERSION-amd64.AppImage- AppImage for x86_64claude-desktop-VERSION-arm64.deb- Debian package for ARM64claude-desktop-VERSION-arm64.AppImage- AppImage for ARM64result/- Nix build output (symlink, gitignored)
Distribution
APT and DNF binaries are fronted by a Cloudflare Worker at pkg.claude-desktop-debian.dev. Metadata (InRelease, Packages, KEY.gpg, repodata/*) passes through to the gh-pages branch; binary requests (/pool/.../*.deb, /rpm/*/*.rpm) get 302'd to the corresponding GitHub Release asset. This keeps .deb / .rpm files out of gh-pages entirely, so they never hit GitHub's 100 MB per-file push cap.
Key files:
worker/src/worker.js— Worker sourceworker/wrangler.toml— Worker config (route,custom_domain = true).github/workflows/deploy-worker.yml— deploys on push tomainwhenworker/**changes.github/workflows/apt-repo-heartbeat.yml— daily chain validation, auto-opens tracking issue on failureupdate-apt-repoandupdate-dnf-repojobs in.github/workflows/ci.yml— gate a strip step on Worker liveness, so binaries are removed from the local pool tree before push
Repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID. Token scoped to the "Edit Cloudflare Workers" template.
Full details including the redirect chain, the http-scheme-downgrade gotcha, credential ownership, and heartbeat failure runbook: docs/learnings/apt-worker-architecture.md.
Testing
Local Build
./build.sh --build appimage --clean noNix Build
nix build .#claude-desktop
nix build .#claude-desktop-fhsTesting AppImage
# Run with logging
./test-build/claude-desktop-*.AppImage 2>&1 | tee ~/.cache/claude-desktop-debian/launcher.logDebugging Workflow
Inspecting the Running App's Code
# Find the mounted AppImage path
mount | grep claude
# Example: /tmp/.mount_claudeXXXXXX
# Extract the running app's asar for inspection
npx asar extract /tmp/.mount_claudeXXXXXX/usr/lib/node_modules/electron/dist/resources/app.asar /tmp/claude-inspect
# Search for patterns in the extracted code
grep -n "pattern" /tmp/claude-inspect/.vite/build/index.jsChecking DBus/Tray Status
# List registered tray icons
gdbus call --session --dest=org.kde.StatusNotifierWatcher \
--object-path=/StatusNotifierWatcher \
--method=org.freedesktop.DBus.Properties.Get \
org.kde.StatusNotifierWatcher RegisteredStatusNotifierItems
# Find which process owns a DBus connection
gdbus call --session --dest=org.freedesktop.DBus \
--object-path=/org/freedesktop/DBus \
--method=org.freedesktop.DBus.GetConnectionUnixProcessID ":1.XXXX"Log Locations
- Launcher log:
~/.cache/claude-desktop-debian/launcher.log - App logs:
~/.config/Claude/logs/ - Run with logging:
./app.AppImage 2>&1 | tee ~/.cache/claude-desktop-debian/launcher.log
Useful Locations
- App data:
~/.config/Claude/ - Logs:
~/.config/Claude/logs/ - SingletonLock:
~/.config/Claude/SingletonLock - Launcher log:
~/.cache/claude-desktop-debian/launcher.log
Versioning
Release versions are managed via two GitHub Actions repository variables (not files):
REPO_VERSION- The project's own version (e.g.,1.3.23). Bump this manually viagh variable set REPO_VERSION --body "X.Y.Z"when shipping project changes.CLAUDE_DESKTOP_VERSION- The upstream Claude Desktop version (e.g.,1.1.8629). Updated automatically by thecheck-claude-versionworkflow when a new upstream release is detected.
Tag format
Tags follow the pattern v{REPO_VERSION}+claude{CLAUDE_DESKTOP_VERSION}, e.g., v1.3.23+claude1.1.7714. Pushing a tag triggers the CI release build.
# Check current values
gh variable get REPO_VERSION
gh variable get CLAUDE_DESKTOP_VERSION
# Bump repo version and tag a release
gh variable set REPO_VERSION --body "1.3.24"
git tag "v1.3.24+claude$(gh variable get CLAUDE_DESKTOP_VERSION)"
git push origin "v1.3.24+claude$(gh variable get CLAUDE_DESKTOP_VERSION)"When upstream Claude Desktop updates, the check-claude-version workflow automatically updates CLAUDE_DESKTOP_VERSION, patches the URLs in scripts/setup/detect-host.sh, and creates a new tag — no manual intervention needed.
Common Gotchas
.zsyncfiles - Used for delta updates, can be ignored/deleted- AppImage mount points - Running AppImages mount to
/tmp/.mount_claude*; check withmount | grep claude - Killing the app - Must kill all electron child processes, not just the main one:
pkill -9 -f "mount_claude" - SingletonLock - If app won't start, check for stale lock:
~/.config/Claude/SingletonLock - Node version - Build requires Node.js; the script downloads its own if needed
- Nix hashes - When Claude Desktop version changes, both the URLs in
scripts/setup/detect-host.shandnix/claude-desktop.nix(version, URLs, SRI hashes) must be updated. The CI handles this automatically. - Claude Desktop version - A GitHub Action automatically updates the
CLAUDE_DESKTOP_VERSIONrepo variable and the URLs inscripts/setup/detect-host.shon main when a new version is detected. Before committingscripts/setup/detect-host.sh, ensure your branch has the latest URLs:
Update both amd64 and arm64 URLs in# Check repo variable (source of truth) gh variable get CLAUDE_DESKTOP_VERSION # Check current version in the detect_architecture case statement grep -oP 'x64/\K[0-9]+\.[0-9]+\.[0-9]+' scripts/setup/detect-host.sh | head -1 # If outdated, pull URLs from main branch gh api repos/aaddrick/claude-desktop-debian/contents/scripts/setup/detect-host.sh?ref=main \ --jq '.content' | base64 -d | grep -E "claude_download_url="detect_architecture()to match main
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

