93a31f9822
Some checks failed
Release Binaries / release (push) Has been cancelled
## Highlights - **CodeNomad now runs on OpenCode V2**: Projects share the native OpenCode service, so desktop windows and terminal clients can work with the same session history. Closing CodeNomad leaves the shared service running. - **Long conversations stay usable**: Transcript memory is bounded, full-history search finds content beyond the loaded messages, and the timeline lets you jump across an entire conversation with contextual previews. - **Move work between Git worktrees**: Create and select native worktrees, move a session family together, and retain the right project and branch context as you switch tasks. - **Ask a quick side question with `/btw`**: Get a separate, temporary answer without interrupting the main session. - **A more consistent workspace**: New light/dark palettes, clearer conversation surfaces, responsive session actions, persistent search/command windows, and View-menu panel toggles make the interface easier to adapt. - **Better attachments and visual feedback**: Device picking, drag-and-drop, and clipboard attachments share one workflow; project files remain available through `@` references. Images returned by MCP and other tools now render directly in chat. ## Upgrading from 0.19.x - **OpenCode V2 is required.** The technical minimum is **2.0.7**, which supplies the native step-start timestamp used by the current event reducer. **2.0.16** is the recommended and qualified runtime for this release. V1 runtimes and the former V2 beta protocol are not supported. - **Install and manage OpenCode from startup or Preferences.** CodeNomad prefers an executable on PATH and can install into a shared user npm location using bundled Node/npm. Terminal clients can use the same installation. - **Runtime installation and service restart are separate actions.** Updating the CLI does not silently restart an already-running OpenCode service. Compatible shared npm installations on OpenCode 2.0.15+ use native upgrade for version changes, including live Windows executable handling. - **Upgrade remote CodeNomad servers to 0.20.0 for the new UI.** The published UI manifest now requires server 0.20.0 instead of advertising compatibility with the V1-based 0.19.x server. - **Git enables the complete project/worktree experience.** If the backend cannot find Git, directory-scoped conversations remain available while Git-dependent functionality is unavailable. ## Sessions, history, and worktrees - Full-history search, counts, selective cleanup, and global timeline navigation work independently of the currently loaded transcript. Search includes edit diffs stored in tool metadata. - Large transcripts load bounded windows while preserving access to complete content. Timeline markers retain tool identities, and hover/focus previews show bounded Markdown excerpts. - Session search uses flat results with optional subsessions; normal browsing retains the parent/child hierarchy. Fork actions are available after both user and assistant messages. - Native worktree creation, discovery, and family moves use repository ownership checks. Removing a worktree verifies and evacuates affected sessions before deleting it. - Worktree selectors open without waiting for a fresh Git scan, and saved conversations restore before secondary Git panels and catalogs finish loading. - Stop and double Escape no longer accidentally restart a parent session. Automatic empty-session cleanup verifies native content before removing anything. - Active-session model choices survive prompt admission, catalog refreshes, and delayed responses instead of switching back unexpectedly. ## Composer, tools, and plugins - Attach local-device files with the native picker, paste, or drag-and-drop, and reference project files separately through `@`. Attachment reads follow the active draft and session rather than spilling into a newly selected conversation. - MCP and specialized tool results can display returned images without inserting image bytes into copied text, search, or speech. - Global and Project plugin activation switches are separate, making the scope of each change explicit. Plugin details are available from the name tooltip. - Native Forms support provider authentication and interactive requests. Permission rejection feedback survives refreshes, and native background Shells remain separate from interactive terminals. - Profile environment variables are refreshed before each prompt, custom command, or session shell request, including removal of previously configured values. - Browser previews and desktop automation give agents a visible inspection-and-fix workflow with session/window targeting. Automation tools are available without a Developer Mode toggle. ## Desktop continuity and interface - Electron and Tauri support multiple UUID-backed windows with independent tabs, drafts, attachments, selection, and view state over one shared backend. Window restoration uses partitioned storage rather than one monolithic snapshot. - Startup prioritizes the active project and conversation, including interrupted hydration and slow filesystem/Git discovery. Preferences retain their own geometry, zoom, and navigation. - Browser authentication can recover in place after a server restart while preserving drafts, without replaying failed actions. - Light/dark palette selections are independent of appearance mode. Settings, message cards, the composer, and panels use more consistent surfaces and controls. - Search and command windows stay open during outside interactions. The native View menu exposes panel and timeline toggles. - Thinking, tool visibility, token sections, and compact headers are clearer. System context updates are hidden by default; collapse preferences also apply to single-step reasoning. - User-supplied HTML displays as literal source rather than being interpreted as chat markup. - Turkish localization joins the existing languages, with updated coverage for V2 features. ## Reliability and distribution - Reconnection reconciles native session and pending-request state, while slow event routing no longer blocks the shared stream or other recipients. - Windows Tauri fixes address window-state capture deadlocks, input reentrancy, and native focus/menu responsiveness. Desktop startup avoids interactive shell prompts that could block launch. - Bundled Node is updated to 24.20.0 LTS, and desktop resources include the Node/npm tools needed for first-run runtime setup. - OpenCode setup keeps executable selection, runtime status, installation/update, and service actions together in Preferences. Diagnostics include clearer cross-platform server information. - Provider usage fixes include credit-based z.ai coding-plan quotas and refreshed session usage on native step/usage events. ## Thanks for contributions Thanks to [@pascalandr](https://github.com/pascalandr), [@markerikson](https://github.com/markerikson), [@fitzgpt](https://github.com/fitzgpt), [@Kondziosz](https://github.com/Kondziosz), [@shantur](https://github.com/shantur), and [@bluelovers](https://github.com/bluelovers). GitHub will append the complete merged pull request and contributor list to the generated release notes. **Full Changelog**: https://github.com/NeuralNomadsAI/CodeNomad/compare/v0.19.0...v0.20.0 |
||
|---|---|---|
| .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 transforms OpenCode from a terminal tool into a premium desktop workspace — built for developers who live inside AI coding sessions for hours and need control, speed, and clarity.
OpenCode gives you the engine. CodeNomad gives you the cockpit.
Features
- 🚀 Multi-Instance Workspace
- 🌐 Remote Access
- 🧠 Session Management
- 🎙️ Voice Input & Speech
- 🌳 Git Worktrees
- 💬 Rich Message Experience
- 🧩 SideCars
- ⌨️ Command Palette
- 📁 File System Browser
- 🔐 Authentication & Security
- 🔔 Notifications
- 🎨 Theming
- 🌍 Internationalization
Getting Started
🖥️ Desktop App
Available as both Electron and Tauri builds — choose based on your preference.
Download the latest installer for your platform from Releases.
| Platform | Formats |
|---|---|
| macOS | DMG, ZIP (Universal: Intel + Apple Silicon) |
| Windows | NSIS Installer, ZIP (x64, ARM64) |
| Linux | Tauri deb, Electron portable tar.gz (x64) |
The Tauri deb is currently built and installation-tested on Ubuntu 24.04. Compatibility with older Debian-based distributions is not yet guaranteed.
💻 CodeNomad Server
Run as a local server and access via browser. Perfect for remote development.
npx @neuralnomads/codenomad --password <your-password> --launch
Authentication required: The server requires a password on first run. You can pass it via
--password, theCODENOMAD_SERVER_PASSWORDenvironment variable, or create anauth.jsonfile (see Server Documentation).
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
SideCars
SideCars let you open local web tools inside CodeNomad as tabs.
Previews use token-scoped URLs inside opaque-origin sandboxes. Loopback HTTP native previews receive a dedicated .preview.localhost origin so root routes, POSTs, and live reload behave normally; HTTPS, LAN, and web hosts use the capability path. Element comments use a source-checked message bridge.
Configuration
- Name: Display name used in CodeNomad
- Port: Local HTTP or HTTPS service running on
127.0.0.1:<port> - Base path: Mounted under
/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 8000:3000 -v "${HOME}:${HOME}:cached" -e HOME=${HOME} gitpod/openvscode-server --server-base-path /sidecars/vscode
Add SideCar as:
- Name:
VSCode - Port:
http://127.0.0.1:8000 - Base path:
/sidecars/vscode - Prefix mode:
Preserve prefix
Terminal (ttyd)
Run with:
ttyd --writable zsh
Add SideCar as:
- Name:
Terminal - Port:
http://127.0.0.1:7681 - Base path:
/sidecars/terminal - Prefix mode:
Strip prefix
Requirements
- OpenCode CLI — must be installed and in your
PATH - 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 18+ — for server mode or building from source
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 (experimental) |
Quick Start
git clone https://github.com/NeuralNomadsAI/CodeNomad.git
cd CodeNomad
npm install
npm run dev
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
See full workaround in the original README.
Community
Built with ♥ by Neural Nomads · MIT License