agentleFS
pjordanandrsnpjordanandrsn/claude-desktop-asahi/AGENTS.md

claude-desktop-asahi

AGENTS.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
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository9 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.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
  1. Distinctive:

    All shell scripts in this project must follow the Bash Style Guide.

    line 45
  2. Very specific:

    Use [[ ]] for conditionals, $(...) for command substitution

    line 48
  3. Very specific:

    Use local in functions, avoid set -e and eval

    line 51
  4. Very specific:

    Don't eval: Use arrays for argv composition (cmd "${args[@]}").

    line 56
  5. Very specific:

    Don't use POSIX [ ... ]: Always [[ ... ]]. POSIX [ mis-parses unquoted expansions in ways [[ does not.

    line 57
  6. Very specific:

    Don't backtick: Always $(...). Backticks don't nest cleanly and conflict with markdown when patches are pasted into PR comments.

    line 58
  7. Very specific:

    Disable directives are a last resort: - Only use # shellcheck disable=SCXXXX when:

    line 68
  8. Distinctive:

    Always add a comment explaining why the disable is needed

    line 71
  9. Very specific:

    Run /lint to check manually: - Use this skill to check for issues before pushing

    line 72
  10. Very specific:

    Use gh CLI for all GitHub interactions

    line 88
  11. Very specific:

    Create branches based on issue numbers: fix/123-description or feature/123-description

    line 89
  12. Distinctive:

    After creating a PR, add a comment to the related issue with a summary and link to the PR

    line 91
  13. Very specific:

    Use the actual model name (e.g., Claude Opus 4.5, Claude Sonnet 4)

    line 129
  14. Very specific:

    Always use regex patterns: when modifying the source JavaScript.

    line 159
  15. Very specific:

    If build-reference/ is missing or you need to inspect source for a new version, follow these steps to download, extract, and beautify the …

    line 198
  16. Distinctive:

    When adding support for new distribution formats (e.g., RPM, Flatpak, Snap) or package repositories, follow these guidelines to avoid …

    line 302
  17. Distinctive:

    Search for existing CI implementations: - Look for "GitHub Actions [format] signing" or similar.

    line 311
  18. Very specific:

    Multiple jobs writing to the same branch will race: - If APT and DNF repos both push to gh-pages, add:

    line 317
  19. Distinctive:

    Test CI steps locally first: - Run the signing/packaging commands manually to catch errors before committing.

    line 325
  20. Distinctive:

    Use a test tag for new infrastructure: - Create a non-release tag to validate the full CI pipeline before merging to main.

    line 327
  21. Distinctive:

    Verify the end-user experience: - After CI succeeds, actually test the install commands from the README on a clean system.

    line 329
  22. Very specific:

    Run with logging: ./app.AppImage 2>&1 | tee ~/.cache/claude-desktop-debian/launcher.log

    line 436
  23. Very specific:

    When upstream Claude Desktop updates, the check-claude-version workflow automatically updates CLAUDE_DESKTOP_VERSION, patches the URLs in …

    line 467
  24. Distinctive:

    Killing the app: - Must kill all electron child processes, not just the main one:

    line 473
  25. Very specific:

    SingletonLock: - If app won't start, check for stale lock: ~/.config/Claude/SingletonLock

    line 477
  26. Very specific:

    Nix hashes: - When Claude Desktop version changes, both the URLs in scripts/setup/detect-host.sh and nix/claude-desktop.nix (version, URLs, …

    line 479
  27. Very specific:

    Update both amd64 and arm64 URLs in detect_architecture() to match main

    line 492

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

<!-- This file is read by AI tools that support the agents.md vendor-neutral standard. The content below is duplicated in CLAUDE.md (read by Claude Code) 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, [[ ]], no set -e, no eval.
  • docs/styleguides/docs_styleguide.md — page anatomy, naming, antipatterns for the docs/ 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 NixOS
  • cowork-vm-daemon.md — Cowork VM daemon lifecycle, respawn logic, crash diagnosis
  • plugin-install.md — Anthropic & Partners plugin install flow, gate logic, backend endpoints, and DevTools recipes
  • apt-worker-architecture.md — APT/DNF binary distribution via Cloudflare Worker + GitHub Releases, redirect chain, credential ownership, heartbeat runbook
  • tray-rebuild-race.md — why destroy + recreate on nativeTheme updates briefly duplicates the tray icon on KDE Plasma, and the in-place setImage + setContextMenu fast-path that avoids the SNI re-registration race
  • mcp-double-spawn.md — Stdio MCPs spawn 2× when chat and Code/Agent panels are both active, root cause in upstream session managers, MCP-author workaround
  • linux-topbar-shim.md — why claude.ai's in-app topbar is missing on Linux, the four gates that hide it, why the upstream frame: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-level BrowserWindow wraps are silently bypassed by frame-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 flat dialog>button[] lists, the more options for X per-row shape, and sidebar virtualization vs the lookup-failure threshold
  • patching-minified-js.md — general lessons from maintaining a long-lived patch suite against an actively re-minified upstream: anchor selection (literals over identifiers), the \w vs $ 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 local in functions, avoid set -e and eval

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[@]}"). eval defeats 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 by build.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. Just cmd — 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=SCXXXX with a comment explaining why.

Linting

Shell scripts are checked with shellcheck and GitHub Actions workflows with actionlint before pushing. When lint issues are found:

  1. Fix the code - Correct the underlying issue rather than suppressing the warning
  2. Disable directives are a last resort - Only use # shellcheck disable=SCXXXX when:
    • The warning is a false positive
    • The pattern is intentional and unavoidable
    • Always add a comment explaining why the disable is needed
  3. Run /lint to 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 in docs/index.md, not filenames or numeric prefixes.
  • Real domain nouns over foo/bar in walkthroughs. The project vocabulary is patches, 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.md for the current state and RELEASING.md for when entries get promoted from [Unreleased].

GitHub Workflow

General Approach

  • Use gh CLI for all GitHub interactions
  • Create branches based on issue numbers: fix/123-description or feature/123-description
  • Reference issues in commits and PRs with #123 or Fixes #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:

  1. 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.
  2. 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

  1. 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.sh is only an orchestrator that sources them. Variable and function names are minified and change between releases.
  2. 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", () => {
  3. Use -E flag with sed for extended regex support when patterns need grouping or alternation.
  4. 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)
  5. 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 analysis
  • build-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 - Intercepts require('electron') to patch BrowserWindow defaults (e.g., frame: true for 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 prettier

Step 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 || true

Step 3: Extract app.asar

# Extract the asar archive
asar extract app.asar app-extracted

Step 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.js

Step 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-extracted

Final 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 nupkg

Adding 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

  1. 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
  2. Search for existing CI implementations - Look for "GitHub Actions [format] signing" or similar. Existing workflows reveal required flags, environment setup, and common pitfalls.
  3. Check tool behavior in non-interactive environments - CI has no TTY. Tools like GPG need flags like --batch and --yes to work without prompts.

Consider Concurrency

  1. 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 --rebase before push
  2. External processes may also modify branches - GitHub Pages deployment runs automatically and can cause push conflicts.

Test the Full Pipeline

  1. Test CI steps locally first - Run the signing/packaging commands manually to catch errors before committing.
  2. Use a test tag for new infrastructure - Create a non-release tag to validate the full CI pipeline before merging to main.
  3. Verify the end-user experience - After CI succeeds, actually test the install commands from the README on a clean system.

Common CI Pitfalls

IssueSolution
GPG "cannot open /dev/tty"Add --batch flag
GPG "File exists" errorAdd --yes flag to overwrite
Push rejected (ref changed)Add git pull --rebase before push, with retry loop
Version format invalidResearch target format's version constraints upfront
Signing key not foundEnsure 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-name

Build Artifacts

  • claude-desktop-VERSION-amd64.deb - Debian package for x86_64
  • claude-desktop-VERSION-amd64.AppImage - AppImage for x86_64
  • claude-desktop-VERSION-arm64.deb - Debian package for ARM64
  • claude-desktop-VERSION-arm64.AppImage - AppImage for ARM64
  • result/ - 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 source
  • worker/wrangler.toml — Worker config (route, custom_domain = true)
  • .github/workflows/deploy-worker.yml — deploys on push to main when worker/** changes
  • .github/workflows/apt-repo-heartbeat.yml — daily chain validation, auto-opens tracking issue on failure
  • update-apt-repo and update-dnf-repo jobs 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 no

Nix Build

nix build .#claude-desktop
nix build .#claude-desktop-fhs

Testing AppImage

# Run with logging
./test-build/claude-desktop-*.AppImage 2>&1 | tee ~/.cache/claude-desktop-debian/launcher.log

Debugging 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.js

Checking 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 via gh 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 the check-claude-version workflow 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

  • .zsync files - Used for delta updates, can be ignored/deleted
  • AppImage mount points - Running AppImages mount to /tmp/.mount_claude*; check with mount | 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.sh and nix/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_VERSION repo variable and the URLs in scripts/setup/detect-host.sh on main when a new version is detected. Before committing scripts/setup/detect-host.sh, ensure your branch has the latest URLs:
    # 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="
    Update both amd64 and arm64 URLs in detect_architecture() to match main

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.