wehub-resource-sync
3e076d4dd9
Deploy Worker / deploy (push) Failing after 1s
Shellcheck / Check shell scripts (push) Failing after 1s
CI / Build Packages (amd64 - appimage) (push) Has been skipped
CI / Build Packages (amd64 - deb) (push) Has been skipped
CI / Build Packages (amd64 - rpm) (push) Has been skipped
CI / Build Packages (arm64 - appimage) (push) Has been skipped
CI / Build Packages (arm64 - deb) (push) Has been skipped
CI / Test Flags Parsing (push) Failing after 1s
BATS Tests / BATS unit tests (push) Failing after 1s
CI / Build Packages (arm64 - rpm) (push) Has been skipped
CI / Test Build Artifacts (amd64) (push) Has been skipped
CI / Test Build Artifacts (arm64) (push) Has been skipped
CI / Update APT Repository (push) Has been cancelled
CI / Mirror Official .deb to Release (push) Has been cancelled
CI / Update DNF Repository (push) Has been cancelled
CI / Update AUR Package (push) Has been cancelled
CI / Create Release (push) Has been cancelled
75 lines
6.5 KiB
Markdown
75 lines
6.5 KiB
Markdown
# Documentation
|
|
|
|
Linux packaging, patching, and operations docs for the [Claude Desktop for Debian](../README.md) project. The README is the storefront; this is the manual.
|
|
|
|
```bash
|
|
# If you're here because something broke:
|
|
claude-desktop-unofficial --doctor
|
|
# Then check troubleshooting.md below.
|
|
```
|
|
|
|
## Installation & building
|
|
|
|
- [**Building from source**](building.md) — `./build.sh`, format flags, how the official `.deb` is pinned and extracted
|
|
- [**Configuration**](configuration.md) — MCP config file locations, env vars, where state lives
|
|
- [**Troubleshooting**](troubleshooting.md) — symptom-keyed fixes, `--doctor` warning index
|
|
|
|
## Project direction
|
|
|
|
- [**Decision log**](decisions.md) — ADR-format record of what we ship and (more importantly) what we won't
|
|
- [**Releasing**](../RELEASING.md) — pre-release checklist, tag recipe, what CI does on tag push
|
|
- [**Changelog**](../CHANGELOG.md) — `v2.0.0` onward, grouped by REPO_VERSION
|
|
|
|
## How the patches work — subsystem deep-dives
|
|
|
|
Hard-won knowledge from debugging real bugs. Consult before working on the related subsystem; add a new entry when you discover something non-obvious that would save the next contributor (human or AI) significant time.
|
|
|
|
- [**Official-deb rebase verification**](learnings/official-deb-rebase-verification.md) — patch-necessity matrix against the official Linux `.deb`, the install-layout facts the v3.0.0 rebase depends on, and the live pre-ship open-items checklist
|
|
- [**Patching minified JavaScript**](learnings/patching-minified-js.md) — anchor selection, the `\w` vs `$` capture trap, beautified false-negatives, idempotency guards; still load-bearing for the two survivor patches
|
|
- [**Cross-build: host vs target**](learnings/cross-build-host-vs-target.md) — tools that run during the build key on `uname -m`, artifacts key on `--arch`; the `Exec format error` class caught twice in the CI cutover
|
|
- [**Packaging permissions**](learnings/packaging-permissions.md) — restrictive-umask traps across deb/rpm/AppImage (`app.asar.unpacked` traversability, `--root-owner-group`, the rpm `%defattr` file-mode trap)
|
|
- [**APT/DNF Worker architecture**](learnings/apt-worker-architecture.md) — Cloudflare Worker + GitHub Releases redirect chain, credential ownership, heartbeat runbook
|
|
- [**Nix packaging**](learnings/nix.md) — the official-deb derivation design contract, the live SRI auto-bump sed anchors, why the resource-path hack must not return, testing without NixOS
|
|
- [**Wayland GlobalShortcuts portal**](learnings/wayland-global-shortcuts-portal.md) — why Quick Entry's hotkey is focus-bound on GNOME Wayland and the `CLAUDE_USE_WAYLAND` tri-state
|
|
- [**Tray rebuild race**](learnings/tray-rebuild-race.md) — KDE SNI re-registration race; validated — the official build converged on the same in-place fix
|
|
- [**Plugin install flow**](learnings/plugin-install.md) — Anthropic & Partners plugin gate logic and DevTools recipes
|
|
- [**Cowork VM daemon**](learnings/cowork-vm-daemon.md) — the 2.x bwrap daemon; superseded on KVM hosts, reference for the 3.1 fallback investigation
|
|
- [**MCP double-spawn**](learnings/mcp-double-spawn.md) — why stdio MCPs spawn twice with chat + Code/Agent panels open
|
|
- [**Test harness — Electron hooks**](learnings/test-harness-electron-hooks.md) — why constructor-level `BrowserWindow` wraps were bypassed by the (now-deleted) frame-fix Proxy; the prototype-hook pattern that remains correct
|
|
- [**Test harness — AX-tree walker**](learnings/test-harness-ax-tree-walker.md) — five non-obvious traps in the v7 fingerprint walker
|
|
- [**Test methodology and coverage**](learnings/test-methodology-and-coverage.md) — how a green run is kept honest: the half-pinned-test failure class (`run`-subshell mutation loss, near-miss anchors, mirror stubs, false-green PASS), host-state isolation, launch-smoke reaping, and the mutation-check review discipline
|
|
- [**Config-wipe recovery**](learnings/config-wipe-guard.md) — the poisoned-cache `claude_desktop_config.json` wipe, the renderer's grouping-state storage chain, the launcher-side backup rotation that recovers it (patch-zero-clean), and why the in-band asar guard is parked
|
|
- [**Quit-cleanup scope fence**](learnings/quit-cleanup-scope-fence.md) — the two systemd-scope namespaces (KDE/GNOME KProcessRunner desktop-id scope vs Electron's own `StartTransientUnit` app-id self-scope), why the app-id is versioned and must be derived at runtime, why the self-scope still can't fence the terminal-launch helpers, and the finding that nothing orphans on clean quit *or* crash — so the #709 MCP-matching slice still has no survivor to reap
|
|
|
|
## Testing
|
|
|
|
- [**Testing overview**](testing/README.md) — what we test and how it's organized
|
|
- [**Test runbook**](testing/runbook.md) — running tests locally
|
|
- [**Test matrix**](testing/matrix.md) — what runs on what distro / format
|
|
- [**Test automation**](testing/automation.md) — CI workflow shape
|
|
- [**Quick-entry closeout**](testing/quick-entry-closeout.md) — the Quick Entry test runner
|
|
|
|
## Operations
|
|
|
|
- [**Issue triage bot**](issue-triage/README.md) — how the GitHub Actions issue-triage workflow works
|
|
- [**Upstream bug reports**](upstream-reports/README.md) — the pending pile: drafts and filing status for bugs that belong upstream (Anthropic or Electron)
|
|
|
|
## Style guides
|
|
|
|
- [**Bash style guide**](styleguides/bash_styleguide.md) — the project's shell-script conventions (forked from YSAP)
|
|
- [**Docs style guide**](styleguides/docs_styleguide.md) — how to write and organize docs (start here if you're adding a page)
|
|
|
|
## Contributing
|
|
|
|
- [**CONTRIBUTING.md**](../CONTRIBUTING.md) — what we accept, what goes upstream, AI-attribution policy
|
|
- [**CLAUDE.md**](../CLAUDE.md) — instructions for AI coding assistants (and a useful project archaeology read for humans)
|
|
- [**AGENTS.md**](../AGENTS.md) — vendor-neutral mirror of `CLAUDE.md` for non-Claude AI tools
|
|
- [**SECURITY.md**](../SECURITY.md) — private vulnerability reporting
|
|
|
|
## Archive
|
|
|
|
Docs whose subject no longer ships, kept with an obsolescence header because the diagnosis work is still worth reading.
|
|
|
|
- [**Linux topbar shim**](archive/linux-topbar-shim.md) — the four topbar gates and the WCO/implicit-drag-region investigation; the shim was deleted in v3.0.0 (official builds render the topbar on Linux), and its three Electron bugs moved to [`upstream-reports/`](upstream-reports/README.md)
|
|
- [**Cowork-Linux handover**](archive/cowork-linux-handover.md) — record of the original patch-based cowork Linux work, superseded by the official KVM path; the bwrap daemon is parked under `scripts/cowork-fallback/`
|