1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
9.7 KiB
Troubleshooting
Recover by checking the owner of the failing operation first: browser, CodeNomad backend, OpenCode service or provider. A lost reply does not prove a mutation failed; reread current state before repeating it.
Desktop launch problems
macOS quarantine
For a release you downloaded from the official repository and verified, macOS can report that the application is damaged because of quarantine/notarization checks.
- Check the download's origin and the installed app path.
- If the app is installed at the following path, remove its quarantine attribute:
xattr -dr com.apple.quarantine /Applications/CodeNomad.app
- Launch again; on Intel Macs also check System Settings → Privacy & Security for the first-launch decision.
This changes the macOS quarantine attribute on that application. It does not repair a corrupted download or make an unknown binary trustworthy.
Linux graphics and FUSE
A Tauri AppImage that immediately exits on Wayland/NVIDIA can be affected by WebKitGTK's DMA-BUF/GBM renderer. Run the downloaded AppImage with the targeted environment override:
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./CodeNomad-Tauri-linux-x64-<version>.AppImage
Electron uses Chromium and is an alternative on the same host. If the AppImage instead cannot mount because FUSE is unavailable, use --appimage-extract-and-run; see Linux installation. These fixes do not require disabling the Electron sandbox.
Git and workspace availability
- Check Git in the backend account's
PATH, not only inside the agent's shell. - Install Git on that host/account if missing, then restart the CodeNomad backend so it inherits the updated environment.
- Reopen/refresh the workspace and check repository status.
Directory-only conversations remain available without Git; worktree and Git controls do not. On Windows, Git installed only inside WSL is not enough for the Windows backend. A known folder without a repository can expose Initialize Git; a missing Git executable is a different condition and must be fixed first. See requirements and Files.
If an owned worktree or conversation placement cannot be verified, open its physical folder explicitly rather than trying arbitrary paths or editing native storage. Refresh after an uncertain move/removal to see which placement actually exists. Force-removing a worktree can destroy uncommitted files; do not use it as a connection repair.
OpenCode runtime and WSL
- Open Preferences → OpenCode and check the OpenCode version card (installed version and running service status), then the selected executable under OpenCode Binary.
- Use the supported installation/update action when the required runtime is missing. Current minimum: 2.1.2; recommended/qualified: 2.1.2.
- If the installed CLI differs from the running service, decide explicitly whether to restart the shared service.
Restart OpenCode service is available under Troubleshooting and requires confirmation. It interrupts active work in every connected client, but retains session history. Configuration reload is a separate action: it keeps the process but rebuilds loaded Locations and cancels pending questions/permissions. Neither is a harmless refresh.
For a WSL executable, confirm the intended distribution and Windows localhost forwarding. Service lifecycle runs inside Linux; CodeNomad must still reach its loopback endpoint from Windows. Never edit the service registration/database or signal guessed Linux process IDs from Windows.
A custom/newer version can be unverified without being incompatible. Read the actual contract error before changing versions. If session environment synchronization fails, fix the execution-host environment/connection: CodeNomad will not send a prompt without that synchronization. See OpenCode.
Login, TLS and direct connectivity
| Symptom | Safe check and recovery |
|---|---|
| Sign in to CodeNomad again | Keep the page open, enter the server username/password and select Sign in. Recovery reconnects in place to keep drafts; it does not replay the failed action. |
| Server unreachable | Verify the backend is running and use its printed address/actual port. An unreachable check alone does not prove your login expired. |
| Provider rejects authentication | Repair the provider's login through its owner; do not change the CodeNomad server password to repair provider OAuth. |
| Certificate name/trust error | Check the actual hostname/IP against certificate SANs and install the intended CA trust or a valid server certificate. Do not disable TLS verification. |
| Direct connection refused | Check effective HTTP/HTTPS binding, firewall and routing. HTTP in desktop or dual-listener mode stays loopback; standalone HTTP-only has different binding behavior. |
After authentication recovery, inspect state before manually retrying a mutation whose reply was uncertain. Runtime passwords must be supplied on every backend start; a password saved through settings persists. See security, TLS/binding rules and server reference.
Remote Control pairing
- On the host, open Settings → Remote Access and check Remote Control is running.
- Create a fresh pairing link and open it on the intended device before it expires.
- If the client shows Pair this device again, pair from the host, then select Check connection on the client.
Pairing links are single-use and short-lived; the direct-access password is not a substitute. Revoked or inactivity-expired device credentials require re-pairing. Closing the last desktop window stops its backend and therefore Remote Control; an enabled service resumes at the next application launch. See Remote Control for unavailable host-only surfaces and revocation.
Provider, plugin and extension state
| Problem | Recovery |
|---|---|
| Wrong provider account/quota | Check the selected native account and Usage. A quota display is not a token/cost total. Refresh after an uncertain account change; selection can affect other clients of that service. |
| Expired externally owned OAuth | Sign in again through OpenCode, Claude Code or the relevant credential owner. CodeNomad does not exchange their refresh tokens. |
| Automatic rotation does not switch | Check opt-in eligibility and whether the current account is actually full. It is a pre-admission policy, not in-flight failover or prompt replay. |
| Plugin state looks stale | Use Refresh plugin controls and inspect the plugin tooltip's scope/target; runtime activation may await native refresh. Do not repeatedly toggle an uncertain write. |
| Mission Control is unavailable | Follow the cause it names. If OpenCode has not loaded the Missions plugin, refresh, then use Reload OpenCode configuration if it persists; if the plugin failed to load, read its error in the Plugins list; if the server could not open its local Missions connection, check the server log, because reloading OpenCode will not help. Missions also run on the standalone server. |
| Installed extension missing | Check its single activation checkbox in panel customization. Installation/replacement leaves it disabled until you explicitly activate and approve required consent. |
| Extension assets denied | Confirm API 2 asset-read consent for the current mounted session. Installing an extension is not permission to read arbitrary files/history. |
See Providers, Integrations and Extensions.
History, pending requests and cleanup
Full-history search is not limited to the transcript rows currently loaded. A display filter hides content without deleting it; use History to distinguish search, compaction, technical cleanup and deletion.
If pending-request recovery is incomplete, CodeNomad retains known queues and answer drafts instead of treating missing coverage as an empty queue. After two consecutive incomplete recoveries it warns once, naming the project, cause, folders and affected sessions; the warning belongs to the Projects and tabs notification category (on screen and in the history by default, see Settings → Notifications). Transient failures are retried by the liveness check. Compaction-related deferral does not mean the request was cancelled. Leave the draft intact, verify the service connection and use the request's current state before answering again.
For cancelled or partial cleanup, read its progress/receipts before starting another deletion. Cancelling does not undo an already dispatched batch. Do not repair history by editing the native database. For Mission uncertainty, use its Check status/refresh recovery rather than creating another run or automatically replaying work; Missions explains restart and lifetime limits.
Logs and safe diagnostics
- Open Instance Info to inspect its status; Show server logs exposes the available output.
- In Preferences → OpenCode, choose the intended Default log level only when more detail is needed. For standalone CodeNomad logging, use the server CLI logging options.
- Open Settings → Info → Diagnostics and use Report a bug, Copy to clipboard or Download .txt.
Logging detail can expose paths, output and application data. Redact credentials, pairing links, network addresses, private paths and conversation content before sharing logs/captures. The full diagnostic report includes paths/addresses; the prefilled bug form deliberately excludes them. See Support.