a8545a3dd6
Some checks failed
Release Binaries / release (push) Has been cancelled
## Highlights - **A unified Files workspace**: Browse Workspace, Changes and Commits in one panel, open central file/diff previews, edit text with Save or Ctrl/Cmd+S, and inspect historical image changes without checking out another revision. - **Better mobile and narrow-window layouts**: Conversation controls stay compact, the composer follows the visible conversation height, and desktop minimum sizes respect application zoom. Mobile browser-preview templates now use native touch emulation when available. - **Questions and permissions above the composer**: Answer native requests in a dedicated dock without losing your draft. Completed questions retain selected-option descriptions and free text, and permission decisions remain available as durable receipts. - **Native skills and web search**: Attach Location skills through `@`, view structured search results and provider-consent requests, and configure global or project web-search defaults in Preferences. - **Provider account controls**: Select, rename and remove native provider accounts, with optional Codex account rotation based on fresh quotas. Usage stays stable across catalog refreshes and repeated connection events. - **Fewer responsiveness stalls**: Event routing no longer waits behind worktree discovery, compaction-related discovery is deferred safely, and supported pending-request recovery avoids loading historical Locations. ## Files and conversation workflow - Workspace, staged/unstaged Changes and paginated Commits share file-row preview controls. Selecting a row no longer opens a preview implicitly. - Stage or unstage files with explicit actions or drag-and-drop; commit actions remain at the top of the staged section. - Workspace text and Markdown source stay editable in the central reader. Unsaved drafts survive closing or switching readers, and saving checks for external changes before overwriting. - Git image previews use the actual compared revisions rather than substituting the current file. Historical diffs remain read-only. - File trees, Git status and history serve cached snapshots and revalidate lazily; Monaco tokenizers ship locally for offline highlighting. - Question and permission queues retain stable selection and request drafts across refreshes and session navigation. Multiple requests use bounded previous/next navigation. - Full-history search fills result pages correctly and avoids redundant counting work. - Enter in a composer picker no longer accidentally submits a draft; model favorites mode persists independently of the active model. - Preview and persistent utility windows expose a close action in their existing toolbar. ## Providers, skills and native tools - Preferences separates model providers and web-search providers, including a global search default and project override. - Search results and provider-consent Forms use dedicated native presentation, with raw output retained for unrecognized responses. - `@` skill selection attaches removable badges and sends explicit native skill IDs with the prompt. - Code Mode output displays native tool-call metadata alongside the existing image/output surface. - Native provider account ordering determines the active account; environment-based connections remain read-only. - Codex quota reads follow the selected native account. Optional account rotation is opt-in, checked before prompt/command admission, and never replays a failed prompt. - Usage panels preserve quota values during provider catalog refreshes and duplicate connection notifications, and explain feature-local runtime limitations. ## Mobile, desktop and reliability - Composer context selectors and actions stay on one row; narrow conversation headers use their overflow menu and hide the timeline below 420 CSS pixels without changing the saved preference. - Manually resized composer heights are stored proportionally and adapt to visible-viewport changes, including the mobile keyboard. Long drafts remain scrollable. - Electron and Tauri desktop minimum sizes follow application zoom. Native mobile browser previews automatically apply touch emulation; iframe fallback changes dimensions only. - Tauri on macOS avoids startup geometry-event feedback; Electron avoids accessing destroyed windows during close. - OpenCode installation shows sustained progress and can recover interrupted Windows installations. - Local TLS certificates use positive serial numbers, with repair of affected local certificates. - Server information distinguishes the server platform from the client environment. - Event ownership checks use registered worktrees without joining slow discovery scans. Pending queues remain intact on incomplete coverage or recovery errors. - Missing-session errors remain identifiable for orphaned subsessions, and parent-session creation is fenced against invalid lifecycle transitions. ## Runtime and upgrading - **OpenCode 2.0.22 is the recommended and qualified runtime for this release.** The technical minimum remains **2.0.7**; feature-local API requirements do not raise the global minimum. - Codex quota reads require the native credential API introduced in **2.0.20**. Older services show feature-local unavailability rather than blocking the application. - Loaded-only pending-request recovery uses a connection-negotiated capability qualified with **2.0.22**. Older services retain their discovery behavior; updating CodeNomad alone does not give them this recovery optimization. - **Upgrade remote CodeNomad servers to 0.20.1 for the published UI.** Its manifest requires the matching backend for the new routes. - Installing or updating the OpenCode CLI does not silently restart an already-running shared service. Restart remains an explicit action. **Full Changelog**: https://github.com/NeuralNomadsAI/CodeNomad/compare/v0.20.0...v0.20.1 |
||
|---|---|---|
| .github | ||
| .opencode | ||
| dev-docs | ||
| docs | ||
| images | ||
| packages | ||
| scripts | ||
| temp | ||
| .gitignore | ||
| .node-version | ||
| AGENTS.md | ||
| BUILD.md | ||
| CONTRIBUTING.md | ||
| DESKTOP_V2_COMPARISON.md | ||
| LICENSE | ||
| MIGRATION_V2.md | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| THIRD_PARTY_NOTICES.md | ||
CodeNomad
The AI Coding Cockpit for OpenCode
CodeNomad is a desktop and browser workspace for OpenCode V2 — built for developers who work across projects, long conversations, and Git worktrees. It connects to OpenCode's shared background service, keeping your sessions accessible from CodeNomad and compatible terminal clients.
OpenCode gives you the engine. CodeNomad gives you the cockpit.
The 0.20 interface, rendered with demonstration data. Download the latest stable release.
Features
- 🚀 Projects and desktop windows — Keep multiple projects open, with per-window tabs, drafts, attachments, and view restoration.
- 🧠 Sessions and full-history navigation — Browse nested sessions, fork conversations, search beyond loaded messages, and jump through long histories with a timeline and previews.
- 🌳 Git worktrees — Create and select worktrees, move a session with its subsessions, and review Git changes without leaving the workspace.
- 💬 Rich conversations — Markdown, code, diffs, tool-result images, configurable reasoning/tool visibility, and
/btwfor a temporary side question. - 📎 Files and attachments — Pick, paste, or drop device files; use
@references for project files and browse your workspace from the file panel. - 🌐 Remote access — Connect to a CodeNomad server from a desktop client or browser, with password authentication and HTTPS support.
- 🧩 Tools and previews — Monitor native background shells, manage MCP connections and Global/Project plugin activation, and open web tools as SideCars.
- 🔎 Agent-driven browser previews — Let your agent open and inspect a visible web preview in Electron or Windows Tauri, without a Developer Mode switch.
- 🎙️ Voice input and speech — Dictate prompts and listen to responses.
- ⌨️ A workspace you can adapt — Command palette, notifications, customizable panels, independent light/dark palettes, and multiple interface languages.
Getting Started
🖥️ Desktop App
Available as both Electron and Tauri builds — choose based on your preference.
Download the archive or package for your platform from Releases.
| Platform | Electron | Tauri |
|---|---|---|
| macOS | ZIP, separate Intel and Apple Silicon builds | ZIP, separate Intel and Apple Silicon builds |
| Windows | ZIP (x64) | ZIP containing the Windows installer (x64) |
| Linux | Portable tar.gz (x64) | deb (x64) |
The Tauri deb is currently built and installation-tested on Ubuntu 24.04. Compatibility with older Debian-based distributions is not yet guaranteed.
Desktop builds bundle Node.js and npm; you do not need to install Node.js separately. On first launch, select an existing compatible OpenCode executable or install OpenCode through the setup screen. You can manage the executable, updates, and service later in Preferences → OpenCode.
Open a project folder, connect your model provider, and start a session. Git must be available to the CodeNomad backend for repository and worktree features; see Requirements.
💻 CodeNomad Server
Run on your development machine and access it through a browser. Install Node.js/npm and OpenCode V2 on that host first; Node.js 24 LTS is the recommended runtime (see Requirements).
npx @neuralnomads/codenomad --password "your-password" --launch
The server binds to 127.0.0.1 by default. For remote access, add --host 0.0.0.0 and connect to the printed HTTPS address; see Server Documentation for binding and TLS configuration.
Authentication: Supply
--passwordorCODENOMAD_SERVER_PASSWORDon each start, or use the UI's persistent password setup.auth.jsonis managed by CodeNomad; see Authentication.
Self-signed certificate: On first launch with HTTPS enabled (the default), your browser will show a "Your connection is not private" warning. This is expected — the server generates a local self-signed certificate automatically. Click Advanced → Proceed to localhost to continue. For local-only use without the warning, run with
--https=false --http=true.
See Server Documentation for flags, TLS, auth, and remote access.
🧪 Dev Releases
Bleeding-edge builds from the dev branch:
npx @neuralnomads/codenomad-dev --password "your-password" --launch
OpenCode V2 and upgrading from 0.19.x
CodeNomad 0.20.0 requires OpenCode V2: 2.0.7 minimum, with 2.0.21 recommended and qualified for this release. OpenCode V1 and the former V2 beta protocol are not supported. The current requirements are maintained in runtime-support.ts.
- One shared OpenCode service owns sessions and messages. Closing a CodeNomad tab, window, or backend leaves that service running. Desktop tabs, drafts, and layout are restored separately for each window.
- Use an existing CLI or install from CodeNomad. Executables on
PATHare preferred; the setup screen also supports a selected executable and a shared user npm installation. The former private CodeNomad OpenCode installation is no longer used. - Updating the CLI and restarting its service are separate actions. Use the explicit service controls in Preferences when you want the running daemon to use an updated executable.
- Remote users should upgrade their CodeNomad server too. The 0.20 UI requires CodeNomad server 0.20.0 or later.
For a manual CLI installation, follow the OpenCode V2 installation guide. The npm package is @opencode/cli and the command is opencode.
SideCars
SideCars let you open web tools running on the CodeNomad server host inside CodeNomad as tabs. Start the service separately, then add it in Preferences → SideCars.
Session web previews are also available from the conversation toolbar. Agent-driven native browser automation is supported in Electron and Windows Tauri; other Tauri platforms use an iframe preview. See Browser Automation for platform details.
Configuration
- Name: Display name used in CodeNomad
- Port: Numeric port of the service on the server host, at
127.0.0.1:<port> - Protocol: Select HTTP or HTTPS to match the service
- Base path: Derived from the name and displayed as
/sidecars/:id - Prefix mode:
- Preserve prefix forwards the full
/sidecars/:id/...path upstream - Strip prefix removes
/sidecars/:idbefore forwarding the request upstream
- Preserve prefix forwards the full
VSCode (OpenVSCode Server)
Run with Docker:
docker run -it --init -p 127.0.0.1:8000:3000 -v "${HOME}:${HOME}:cached" -e HOME=${HOME} gitpod/openvscode-server --server-base-path /sidecars/vscode
Add SideCar as:
- Name:
VSCode - Port:
8000 - Protocol:
HTTP - Base path:
/sidecars/vscode - Prefix mode:
Preserve prefix
Terminal (ttyd)
Run with:
ttyd --writable zsh
Add SideCar as:
- Name:
Terminal - Port:
7681 - Protocol:
HTTP - Base path:
/sidecars/terminal - Prefix mode:
Strip prefix
Requirements
- OpenCode V2 — 2.0.7 minimum; 2.0.21 recommended for CodeNomad 0.20.0. Install/select it through desktop setup or provide a compatible CLI on the server host.
- Git — a prerequisite for full functionality (repository identity, Git operations and worktrees). Git must be executable in the CodeNomad backend's
PATH; it is not bundled with the desktop installers. - Node.js and npm — required for the standalone npm server and source builds, bundled with desktop releases. Use Node.js 24 LTS; development and release builds use the version in
.node-version(currently 24.20.0).
On Windows, install Git for Windows with the option to use Git from the command line and third-party software. A per-user installation is sufficient and does not require administrator rights; install into a user-writable directory and make Git available in the user PATH. On macOS or Linux, follow the platform installation instructions. Fully quit and restart CodeNomad after installation so its backend inherits the updated PATH. For a remote server, install Git on the server host for the account running CodeNomad and restart that server process, not just the browser. A Git installation available only inside WSL does not satisfy the Windows backend's requirement.
Without Git, CodeNomad tolerates a degraded, directory-only mode. You can open a folder and talk to your agent, including asking it to help install Git. The backend supplies the agent with Git availability and backend platform context before prompts and custom commands; there is no blocking Git installation screen. Git operations and worktree management require Git. Session access is restricted to the explicitly opened physical folder; open another checkout separately to access its conversations. The agent's shell and the CodeNomad backend can run on different hosts, so installation help must target the backend account and environment. Git availability is rechecked on subsequent sends and the agent context is removed once it is available.
Development
CodeNomad is a monorepo built with:
| Package | Description |
|---|---|
| packages/server | Core logic & CLI — workspaces, OpenCode proxy, API, auth, speech |
| packages/ui | SolidJS frontend — reactive, fast, beautiful |
| packages/electron-app | Desktop shell — process management, IPC, native dialogs |
| packages/tauri-app | Tauri desktop shell — native windows, integration, and packaging |
Quick Start
git clone --branch dev https://github.com/NeuralNomadsAI/CodeNomad.git
cd CodeNomad
npm ci --workspaces --include=optional
npm run dev
npm run dev starts the Electron development host. Use Node.js from .node-version, Git, and a compatible OpenCode V2 CLI. For Tauri, install the platform build prerequisites and run npm run dev:tauri. See CONTRIBUTING.md for the development and PR workflow.
Troubleshooting
macOS: "CodeNomad.app is damaged and can't be opened"
Gatekeeper flag due to missing notarization. Clear the quarantine attribute:
xattr -dr com.apple.quarantine /Applications/CodeNomad.app
On Intel Macs, also check System Settings → Privacy & Security on first launch.
Linux (Wayland + NVIDIA): Tauri App closes immediately
WebKitGTK DMA-BUF/GBM issue. Run with:
WEBKIT_DISABLE_DMABUF_RENDERER=1 codenomad-tauri
This applies to the Tauri WebKitGTK build. Electron uses Chromium and can be used as an alternative on the same machine.
Community
Built with ♥ by Neural Nomads · MIT License