e68ac52413
## Summary Remove the requirement that the invoking agent's conversation must already be active before CodeNomad UI automation can inspect or navigate the application. That restriction prevented agents from using the UI to return to their own conversation after a session or project switch. - Target the inspected native window/run independently of the selected conversation or project, including views with no active session. - Keep the actual selected context in inspection results as descriptive metadata. - Pin actions to the inspected native window/run. Keep accessibility references document-scoped: page replacement, reload and native target changes still require fresh inspection, while conversation selection alone does not. - Keep authenticated backend discovery and browser-preview session attachments intact. - Document the behavior and add CDP/route regressions for navigation, empty views and native target changes. ## Validation - 27 targeted CDP, automation route and plugin tests passed. - `npx tsc -p packages/server/tsconfig.json` and `git diff --check` passed. - Compiled shared server modules installed in the usual Windows Tauri installation. - The actual native automation bridge navigated **CodeNomad → opencode → gaffer → openchamber → CodeNomad** from the same invoking session, successfully inspecting each different active conversation and returning to the original conversation. - Native restart/reconnection, final inspection and screenshot succeeded. The implementation is shared by Electron and Tauri; no host-specific code changes are needed. Installed desktop validation was performed on Windows Tauri. Maintenance note: the touched `packages/server/src/developer-cdp.ts` is approximately 564 lines; this PR does not refactor it solely for length. |
||
|---|---|---|
| .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 - Node.js 18+ — for server mode or building from source
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