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.
7.7 KiB
Projects and worktrees
A project tab connects CodeNomad to a folder on the backend computer. Opening a tab, browsing a checkout and moving a conversation family are different operations.
Open a project
- Click New instance (
+) to open the home page. - Choose Browse Folders, select the backend folder and open it; or choose an entry under Recent Folders.
- For a repository copy, choose Clone Git Repo, enter Repository URL and Destination folder, then Clone.
Browsing a remote server means browsing that server's filesystem, not your phone or laptop. Opening a project does not create a separate OpenCode daemon for each tab. Conversations are native OpenCode sessions; their lifetime is not the tab's lifetime.
Cloning writes a repository to the destination. Remove the destination folder first if it already exists. is destructive: enable it only when everything already there can be deleted. Use a fresh destination if unsure. A failed clone is not a reason to delete an existing project; inspect the reported destination and error before retrying.
Recent entries are shortcuts. Rename workspace changes its displayed name; Remove from recent removes the shortcut, not its files or conversations. Clicking an already-open recent project opens a new tab; its Open button (Switch to open project) selects the existing tab instead.
Use the new-instance launcher
- Long-press or right-click
+; with keyboard focus there, use Alt+Down, Shift+F10 or the Menu key. - Search recent projects, or select Browse…, Temporary or Clone….
A normal click still opens the full home page. The launcher is a shortcut, not the management surface: rename/remove recent projects and manage server bookmarks on the home page. Escape dismisses the launcher and returns focus to +.
Close a project tab
- Use the tab's close button or Close Tab in the command palette (
Ctrl/Cmd+Win the renderer). - Closing the tab closes that project in CodeNomad: it stops following its events and requests. Sessions continue running in OpenCode.
- Reopen the folder through Browse or Recents to find those conversations again.
| Action | Scope and effect | What it does not do |
|---|---|---|
| Close Tab | Removes that tab's CodeNomad project connection; another tab opened separately on the same folder is unaffected | Does not delete project files or native history, stop sessions or unload OpenCode's Location |
| Stop session | The selected conversation's execution | Does not close the project or delete its history |
If another window displays the same project connection, its tab closes too and that window shows a notification. The initiating window shows none. Closing is immediate; if the backend cannot close the project, an error appears and Switch to open project on the home page still reaches it. There is no automatic retry. Unsent drafts from the closed tab are not retained in startup restoration.
Closing a whole window, quitting or reloading does not close its project connections; normal startup restoration still applies. Stop relevant runs explicitly if you need to verify execution ended. CodeNomad never unloads native Locations; shared-service maintenance is described in OpenCode setup.
Temporary workspaces
- Choose Temporary in the launcher or New temporary instance on the home page.
- Work in the empty CodeNomad-managed folder; Git is not initialized automatically.
- On closing the tab, choose Keep, Discard or Cancel. The tab menu also offers Keep as project.
| Choice | Effect | Recovery |
|---|---|---|
| Keep | Closes the project in CodeNomad, retains the folder and conversations, removes its temporary status and adds a recent project | Reopen from Recents; the folder is not moved |
| Discard | Deletes the temporary workspace's conversations and files | No undo; save anything needed elsewhere first |
| Cancel | Leaves the temporary workspace open | Continue working or decide later |
An untouched temporary tab, with no conversation, file or unsent draft, is discarded quietly on close. Open temporary tabs participate in normal startup restoration, but the home page has no separate list for resuming closed temporary folders.
Discard refuses while a conversation is running or the folder is open in another tab/window. Stop the run and close the other views first. A failed discard remains temporary: resolve the reported problem and retry rather than manually deleting a parent directory.
Select or create a worktree
- Open a parent conversation and use its composer worktree selector. On narrow layouts it is an arrow-only control.
- Select an existing discovered worktree, or choose + Create worktree.
- For creation, enter Name and choose Create and use worktree.
CodeNomad discovers worktrees through OpenCode and verifies that they belong to the opened repository. A new branch name starts at the selected checkout's HEAD. An existing branch name uses that branch's current revision; Git can refuse a branch already checked out elsewhere. Worktrees use the default .codenomad/worktrees location. Uncommitted changes remain in the original checkout; creation does not copy them into the new worktree.
The composer selector moves the parent conversation and its recursive descendants as a verified family. A subsession cannot independently change this selector. Active sessions block the operation: let the family finish or stop its execution first. Wait for a move to settle before requesting another; on error, inspect the refreshed conversation/worktree state before retrying.
By contrast, Worktree to browse in Files changes only which checkout the panel reads. It does not move a conversation, switch a branch or change where its next shell command runs.
Remove a worktree
- In the composer worktree list, use Delete worktree for a removable branch worktree.
- Review the target folder. Leave Force delete (discard local changes) off unless local changes may be lost.
- Confirm deletion and check the resulting inventory.
Deletion removes the worktree's local folder. Git's main checkout is not a removable target. CodeNomad moves affected conversation families back to the root checkout and verifies their placement before removing the worktree; active sessions can block removal. Deletion is not an archive or a backup of uncommitted files.
If Git refuses modified/untracked files, preserve or clean those files before retrying. Force deletion explicitly discards them. For a locked directory, close terminals, editors, watchers and background processes using it. For a missing record, refresh worktrees and inspect the path before trying again. The error dialog offers Copy sanitized when sharing diagnostics; review even sanitized text first.
Initialize Git or work without it
- For an ordinary folder with Git available, open Files → Changes or Commits.
- Choose Initialize Git. It acts immediately, without an extra confirmation.
- Wait for project metadata and conversations to refresh; use Refresh if Git was initialized outside CodeNomad.
Initialization creates the repository in the explicitly opened folder, not its parent. It does not make a commit. On failure, inspect the message and refresh before retrying: an uncertain reply is not automatically replayed.
If the backend cannot run Git, conversations and bounded file browsing remain available for the explicitly opened folder in directory-only mode. Worktree operations and Git initialization require Git on that backend. See installation and Files.