* doctor: detect IBus/GTK misconfigurations that break input (#550)
Adds _doctor_check_im_modules helper covering the four input-method
failure modes from #545:
- ibus-gtk3 package missing while GTK_IM_MODULE=ibus
- GTK immodules cache stale (active module not listed by
gtk-query-immodules-3.0 --update-cache fixes it)
- XWayland session routing IBus through XIM (lossy for some IMEs;
informational note pointing at CLAUDE_USE_WAYLAND=1 for native
Wayland IME)
- CLAUDE_GTK_IM_MODULE override visibility (informational, so
users can verify the resolved value)
Each check is gated so it only fires when relevant — e.g. the
package check is skipped when GTK_IM_MODULE isn't ibus, the cache
check is skipped when gtk-query-immodules-3.0 isn't installed, and
the package check returns silently on distros without dpkg/rpm/pacman
to avoid false negatives.
Adds tests/doctor.bats with 17 cases covering each gating branch and
the _cowork_pkg_hint mapping for ibus-gtk3 (Arch maps to plain ibus
since it bundles the GTK3 immodule).
Hoists _distro_id resolution to the top of run_doctor so the IM
check and the existing Cowork section share one /etc/os-release
read.
Closes#550. Refs #545, #549.
Co-Authored-By: Claude <claude@anthropic.com>
* doctor: simplify IM-check helper and DRY out doctor.bats setup
Mechanical clean-up of the #550 diff after self-review:
scripts/doctor.sh
- tighten the _doctor_check_im_modules docblock: drop the "each
check is gated" paragraph (self-evident in the code) and inline
the XWayland/XIM rationale into the failure-mode bullet
- drop the inline section comments that just restated the next
block's purpose; keep the rc=1/rc=2 comment because the value
distinction is the load-bearing detail
- replace the `local _pkg_rc=0; ... || _pkg_rc=$?; if ((_pkg_rc == 1))`
dance with a `case $?` on the direct call
tests/doctor.bats
- hoist the `command -v gtk-query-immodules-3.0 → not-found` shim
into a `_skip_gtk_query` helper (it was duplicated across 11 of
the 17 cases)
- default `_pkg_installed() { return 2; }` in setup so per-test
stubs only appear when the test cares about rc=0 or rc=1
- drop dead `_skip_gtk_query` calls from cases where the function
returns earlier (no IM selected, package warn fires) so the
shim is only present where it actually changes behaviour
No behaviour change — all 17 doctor.bats cases still pass, plus the
68 launcher-common.bats cases. Shellcheck is unchanged from baseline.
Co-Authored-By: Claude <claude@anthropic.com>
---------
Co-authored-by: Claude <claude@anthropic.com>
* launcher: add CLAUDE_GTK_IM_MODULE opt-in override (#549)
Some users hit broken IBus integration on Linux and have to wrap
every launch with `GTK_IM_MODULE=xim claude-desktop`. Forcing this
for everyone would break CJK input methods, compose keys, and
dead-key sequences (rationale in #545), so this lands as opt-in.
When `CLAUDE_GTK_IM_MODULE` is set non-empty, `setup_electron_env`
exports `GTK_IM_MODULE=$CLAUDE_GTK_IM_MODULE` before the Electron
exec and logs the override (with the prior value) to launcher.log.
Unset/empty leaves `GTK_IM_MODULE` alone — no behavior change for
users not affected by the IBus issue.
Adds a TROUBLESHOOTING.md section documenting symptoms, valid
values, the trade-off note for `xim`, and BATS coverage for the
set / unset / empty / unset-prior cases.
Closes#549. Refs #545.
Co-Authored-By: Claude <claude@anthropic.com>
* launcher: tighten CLAUDE_GTK_IM_MODULE comment and docs (#549)
Trim the in-source comment to what's not implied by the guard, drop
the underscore prefix on the local, and remove a redundant trailing
sentence + duplicated trade-off line from TROUBLESHOOTING.md. No
behavior change; all 68 BATS tests still pass.
Co-Authored-By: Claude <claude@anthropic.com>
---------
Co-authored-by: Claude <claude@anthropic.com>
Adds:
- `*)` case + valid-values warning on both `COWORK_VM_BACKEND` switches in `scripts/doctor.sh`, factored through a shared `_warn_unknown_backend` helper. Switch A explicitly matches the empty and `bwrap` cases as no-ops alongside `kvm|host` so only truly-unknown values trigger the warn. Switch B (user-facing summary) reports cowork_backend as `auto-detect (invalid override '...' — see warning above)` so the doctor is honest about what the daemon actually does (#442 tracks the daemon-side fix).
- `COWORK_VM_BACKEND` env var row + new Cowork Backend section in `docs/CONFIGURATION.md`, placed before Cowork Sandbox Mounts.
- VM connection timeout / virtiofsd PATH / Fedora tmpfs (EXDEV) sections in `docs/TROUBLESHOOTING.md`.
- README acknowledgment for @CyPack.
Closes#293
Co-Authored-By: aaddrick <aaddrick@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: diagnose AppArmor userns block on bwrap probe (#351)
Ubuntu 24.04+ ships apparmor_restrict_unprivileged_userns=1 by
default, which blocks the user namespace bwrap needs to start. The
daemon's probe then fails, auto-detect silently falls through to
KVM, and KVM hangs waiting for a rootfs the user hasn't set up —
leaving Cowork stuck in a retry loop with no clear error.
- Classify the probe failure (classifyBwrapProbeError) so the daemon
can distinguish AppArmor/userns blocks from generic failures and
log a pointer to the TROUBLESHOOTING.md remediation.
- Stop falling through to KVM when bwrap is installed but blocked;
drop to host-direct instead so users see a working (if unsandboxed)
Cowork and the reason bwrap didn't engage. Users who actually want
KVM can still set COWORK_VM_BACKEND=kvm.
- Mirror the probe + diagnosis in `--doctor` so misconfigured systems
get the same actionable output without waiting for a daemon log.
- Document the AppArmor profile workaround in TROUBLESHOOTING.md.
- Credit @hfyeh for the diagnosis and profile snippet.
Co-Authored-By: Claude <claude@anthropic.com>
* refactor: simplify PR #434 per cdd-code-simplifier
Drop redundant `-n` guard around the COWORK_VM_BACKEND case in
`--doctor`: the `${VAR,,}` expansion is already safe on an unset var
(no `set -u` in this script) and the `kvm|host` arms simply don't
match an empty string.
Co-Authored-By: Claude <claude@anthropic.com>
---------
Co-authored-by: Claude <claude@anthropic.com>
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>
