db6685cb55
## Problem
Closing a project tab only hid it in that window. The backend workspace
record kept routing the folder's events, notifications, auto-accept and
pending-request recovery, invisibly, until the palette-only **Stop
Workspace** command was run on the active tab. That command still showed
the V1 message "Stop OpenCode instance? This will stop the server."
although V2 has one shared OpenCode service, and it called
`debug.location.evict`, which (per OpenCode source) rejects pending
permissions, cancels pending Forms, fails plugin RPC and kills terminals
of that directory, even for sessions started elsewhere. OpenCode loads
locations on demand and unloads idle ones itself.
## Change
- **Closing a project tab** (×, Ctrl/Cmd+W) removes that tab's backend
workspace record. CodeNomad stops following it; sessions keep running in
OpenCode and reappear when the project is reopened.
- **Another tab of the same folder** has its own record and is
unaffected.
- **The same record shown in another window**: that window's tab closes
through the existing `workspace.stopped` broadcast, with an info
notification ("closed from another window"); the initiating window shows
nothing.
- **CodeNomad never evicts OpenCode locations**: eviction, its
serialization helpers and `locationOwned` bookkeeping are removed. A
failed launch now always removes its logical record (the retention only
existed to retry a failed eviction).
- **Stop Workspace removed** (command, confirm dialog, i18n keys in all
locales).
- Unchanged: opening an open project still offers a new tab (recent row)
or switching (switch button); temporary projects keep Keep / Discard /
Cancel; window close, app quit, reload, restore and backend shutdown
delete nothing; disconnected-instance dismissal stays local.
- Delete failure: error toast, record kept and reachable from the home
page, no automatic retry.
## Docs
Help in all 10 locales (`projects`, `index`, `desktop`, `server`,
`opencode`, `missions`), `AGENTS.md`, `CONTRIBUTING.md`,
`dev-docs/architecture.md`, `packages/server/README.md` and the
architecture-guide skill now describe the new contract.
## Validation
- UI store tests (`--conditions=browser`): app-tabs,
temporary-instances, workspace-list-reconciliation-fence,
instances-restore-ownership — 30/30.
- Server: manager + shared service 54/54; event ownership and workspace
identity suites pass.
- New real-component browser regression (click ×, Ctrl+W, Cmd+W): 3/3;
project restoration (Electron/Tauri) and new-instance launcher browser
suites pass.
- `npm run test:help` 9/9 (250 pages); UI, server and Electron
typechecks.
6.6 KiB
CodeNomad help
Use this guide to operate the current CodeNomad desktop or browser workspace with your OpenCode service. It focuses on CodeNomad's controls, execution boundaries and recovery—not OpenCode configuration tutorials or a version archive.
Read this first
CodeNomad connects your workspace to one shared OpenCode background service. Sessions and messages belong to OpenCode; tabs, composer drafts and layout belong to the CodeNomad client. Closing a project tab closes that project in CodeNomad, while sessions continue in OpenCode. Reopen the project to find them again. Closing CodeNomad does not stop OpenCode.
- Check the host requirements and OpenCode setup.
- Open a project, then choose the conversation's Agent, Model and Thinking controls.
- Check the affected scope before changing credentials, restarting a service or deleting history. Other clients can use the same native service.
The public help site works without CodeNomad, its backend or a login. Help → CodeNomad Help on desktop and Open help in the command palette open it separately in the current UI language. Language changes do not translate stored conversations.
Settings opens the native Preferences window in a local desktop client; browser and remote clients use embedded settings. Paths such as Settings → Providers identify the same settings section in either surface.
For a standalone browser workspace on a prepared host, the server guide explains this launch and its authentication/TLS requirements:
npx @neuralnomads/codenomad --generate-token --launch
Choose your client
| Capability | Local desktop | Direct browser or remote server window | Remote Control paired device |
|---|---|---|---|
| Projects, conversations, files and history | Backend's folders and native sessions | Connected server's folders and sessions | Host's authorized workspace surfaces |
| Native Preferences and desktop windows | Available | Browser/remote settings stay in the client | Host-only desktop controls unavailable |
| Session browser preview | Native in Electron and Windows Tauri; iframe on other Tauri platforms | Iframe where available | Host-only preview endpoints unavailable |
| Native desktop/browser automation | Owned local windows/previews | Not a substitute for native desktop automation | Host-only automation endpoints unavailable |
| Authentication | Local bootstrap or password session | Server password session | Paired-device credential |
| PWA installation | Use the native app or a browser | Browser-dependent; secure context required | Browser-dependent; pairing still required |
For precise limits, see browser previews and SideCars, Remote Control and mobile/PWA. A remote window does not turn your device's filesystem into the server workspace.
Know what owns the state
| Term | Meaning in CodeNomad |
|---|---|
| Project tab / workspace / instance | A CodeNomad connection to an explicitly opened folder; multiple tabs can use the shared service. |
| Conversation / session | Native OpenCode history and execution associated with its directory. |
| Family | A conversation and its recursive subsessions; relevant to moves, activity, Yolo and Mission controls. |
| Worktree | An owned repository checkout selected for browsing or session placement. Browsing it does not move a conversation. |
| Location | OpenCode's directory-scoped native runtime context; CodeNomad never unloads it when a project closes. |
| CodeNomad backend | The server providing workspace, Git, authentication and client connectivity. Its account and environment determine backend filesystem access. |
| Configuration | CodeNomad settings under the server's config directory; Global/Project OpenCode settings have their own native scope. |
| Window | Its own tabs, navigation, drafts and restored view. Native history is shared, not copied for each window. |
| Desktop data profile | Explicit native/client storage selection; it does not automatically isolate OpenCode sessions or every shared configuration. |
The workspace root limits which folders CodeNomad opens; it is not an agent sandbox. Review security before exposing a host or allowing broad tool access.
Explore by task
| Task | Guide |
|---|---|
| Install or serve the workspace | Install, Server reference, Network and TLS |
| Work across checkouts and conversations | Projects, Conversations, Files |
| Find history or safely clean it up | History |
| Answer native questions and permissions | Permissions |
| Coordinate bounded or daily work | Missions |
| Configure execution and integrations | OpenCode, Providers, Integrations |
| Connect another device | Remote Control, Security, Mobile |
| Adapt the workspace | Settings, Shortcuts, Voice, Extensions |
| Manage the native application | Desktop, Browser previews and SideCars, Updates |
| Diagnose or contribute | Troubleshooting, Support and source builds |
Monitor work without changing it
The Status panel exposes the active session's provider usage and native background Shells. Conversation status and child activity identify working, compacting and input-waiting sessions. Monitoring a background Shell is distinct from sending a composer Shell request or using a separately hosted terminal SideCar.
- Open Status → Background Shells for the selected conversation's Location (or the open workspace when no conversation is selected).
- Inspect command, shell, directory, status, PID and exit code where provided; choose View output for the available native output.
- To dispose of one, use Stop and remove while running, or Remove after exit, and confirm the target.
Removing a running Shell stops that process; closing its output window does not. Refresh/reconnect reads current native state rather than reconstructing missed output events.
Display snapshots refresh after native changes, reconnect and visible demand. They are not guaranteed replay logs. If a result is uncertain, refresh authoritative state before retrying a mutation; do not submit again merely because a notification or event was missed.