CodeNomad 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 | Iframe while the host allows web previews (the default) |
| 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 | Native/client storage chosen in Settings; 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.