CodeNomad is built for people who live inside OpenCode for hours on end and need a cockpit, not a kiosk. It delivers a premium, low-latency workspace that favors speed, clarity, and direct control.
Important
This is a fork of the original shantur/CodeNomad repository. This fork includes enhancements from PRs that diverge from the upstream main branch. These changes are included in all builds generated from this repository.
Manage multiple OpenCode sessions side-by-side.
📸 More Screenshots
Global command palette for keyboard-first control.
Rich media previews for images and assets.
Browser support via CodeNomad Server.
Choose the way that fits your workflow:
The best experience. A native application (Electron-based) with global shortcuts, deeper system integration, and a dedicated window.
- Download: Grab the latest installer for macOS, Windows, or Linux from the Releases Page.
- Run: Install and launch like any other app.
We are also working on a lightweight, high-performance version built with Tauri. It is currently in active development.
- Download: Experimental builds are available on the Releases Page.
- Source: Check out
packages/tauri-appif you're interested in contributing.
Run CodeNomad as a local server by building from source. Perfect for remote development (SSH/VPN) or running as a service.
# Clone the repository
git clone https://github.com/bizzkoot/CodeNomad.git
cd CodeNomad
# Install dependencies
npm install --workspaces
# Build and launch the server
npm run build --workspace @neuralnomads/codenomad
npm run start --workspace @neuralnomads/codenomadThis will start the server and you can access it at http://localhost:3000
- Multi-Instance: Juggle several OpenCode sessions side-by-side with tabs.
- Long-Session Native: Scroll through massive transcripts without hitches.
- Command Palette: A single global palette to jump tabs, launch tools, and control everything.
- Deep Task Awareness: Monitor background tasks and child sessions without losing flow.
We've replaced the standard question tool with a native Model Context Protocol (MCP) implementation called ask_user.
| Feature | Legacy question Tool |
New ask_user MCP Tool |
|---|---|---|
| Cost | Consumes premium requests per answer | Zero premium request consumption |
| Architecture | Remote API loop | Local IPC + MCP Server |
| Timeout | Short default timeout | 5-minute timeout (configurable) |
| UX | Standard | Rich Markdown, Minimizable Wizard |
Tip
Adjusting Timeout Duration
You can configure the ask_user timeout in the Advanced Settings menu found on the start screen (before opening a project).
- Launch CodeNomad.
- On the welcome screen, click Advanced Settings.
- Scroll to Timeout Settings and adjust the value (default: 300s).
This change is critical for users on metered plans (like GitHub Copilot), effectively "unlocking" unlimited user interactions without draining quotas.
This fork selectively merges features from upstream while preserving fork-specific architecture.
| Category | Feature | Commit |
|---|---|---|
| 🔧 Server API | GET /api/workspaces/:id/git/file-original endpoint for fetching file HEAD/staged content |
infrastructure preserved |
| 🔌 API Client | fetchGitOriginalContent() method for Monaco diff preparation |
infrastructure preserved |
| 🛡️ Stability | Git store optional chaining safety fix | 755b768 |
| 🛡️ Stability | Permission/Question block null checks | permission-block.tsx, question-block.tsx |
| 🛡️ Stability | "Object has been destroyed" Electron crash fix | 13edfa4 |
| ⚡ Platform | Power save blocker wake lock during busy instances | 3393911 |
| 🎨 UI Polish | Sticky header background for bash tool output | d8b018a |
| 🎨 UI Polish | Diff syntax highlighting for code blocks | a06aa01 |
| 🔧 DevEx | Electron dev startup CLI detection and URL swap fixes | 5f113c3 |
| 📦 Release | Version bump to 0.10.3 | 11deb19 |
These features require architectural alignment with fork patterns and are documented in PR.md:
| Category | Upstream Feature | Status |
|---|---|---|
| 🧭 Right Panel & Session Changes | Changes/Status tabs with session diff hydration | Use existing RightPanel tabs |
| 🧩 Monaco Diff/File Viewers | Monaco-powered changes/files viewers in SourceControlPanel | Infrastructure ready; custom UI needed |
| 🌳 Worktrees & Git UX | Worktree file browser in SourceControlPanel | Infrastructure ready; custom UI needed |
| 🎨 Theme & UI Polish | System/light/dark theme toggle | Fork uses different theme system |
| ⌨️ Prompt & Message UX | Enter-to-submit toggle, message-part delete | Preserved in fork-specific implementation |
Note: The server infrastructure for Monaco diff and worktrees is preserved (API endpoints and client methods). Custom UI implementation can leverage these when architecturally aligned.
- OpenCode CLI: Must be installed and available in your
PATH. - Node.js 18+: Required if running the CLI server or building from source.
This fork includes several major enhancements not available in the upstream repository:
| Feature | Key Capabilities |
|---|---|
| 🎯 Native MCP | • Zero-Cost Interactions: No premium usage for questions • Reliability: 5-minute timeout with auto-retry logic • Rich UI: Minimizable markdown wizard & mobile optimization |
| 📂 Source Control | • Git Integration: Built-in status, diff viewer, and branch management • Smart Previews: View untracked files with binary detection • Actions: Publish branches and delete files directly |
| 🔔 Notifications | • Persistent: Error banner for timed-out questions/tasks • Recovery: One-click retry without losing context • Rich Details: Markdown-rendered failed question panel • State: Notifications persist across restarts |
| 🔍 Chat Search | • Deep Search: Query entire history with debounced input • Visual: Result highlighting and auto-expansion of collapsed blocks |
| 🌳 Folder Tree | • Navigation: VSCode-style file explorer for workspaces • Preview: Instant GitHub-style markdown rendering |
| 📝 Enhanced Input | • Editor: Expandable multi-line chat input • Smart Attachments: Tab-key file selection & auto-collapse |
| 🎨 Polish & Perf | • Visual: Seamless dark mode, improved split-view diffs • Speed: 10x faster dev icon loading via Vite optimization |
Note
These features are not included in upstream and represent divergent functionality from the original CodeNomad repository.
Last updated: 2026-02-15
Since this repository uses GitHub Actions for automated releases, forks may encounter failures in the release-ui and publish-server jobs due to missing secrets (CLOUDFLARE_API_TOKEN, NPM_TOKEN) or version conflicts.
To prevent these failures, the workflows are configured to skip these specific jobs unless running on the upstream repository or if explicitly enabled. The build-and-upload job (which generates the release binaries) will still run and attach artifacts to the GitHub Release on your fork.
If macOS reports that "CodeNomad.app is damaged and can't be opened," Gatekeeper flagged the download because the app is not yet notarized. You can clear the quarantine flag after moving CodeNomad into /Applications:
xattr -l /Applications/CodeNomad.app
xattr -dr com.apple.quarantine /Applications/CodeNomad.appAfter removing the quarantine attribute, launch the app normally. On Intel Macs you may also need to approve CodeNomad from System Settings → Privacy & Security the first time you run it.
On some Wayland compositor + NVIDIA driver setups, WebKitGTK can fail to initialize its DMA-BUF/GBM path and the Tauri build may exit right away.
Try running with one of these environment variables:
# Most reliable workaround (can reduce rendering performance)
WEBKIT_DISABLE_DMABUF_RENDERER=1 codenomad
# Alternative for some Wayland setups
__NV_DISABLE_EXPLICIT_SYNC=1 codenomadIf you're running the Tauri AppImage and want the workaround applied every time, create a tiny wrapper script on your PATH:
#!/bin/bash
export WEBKIT_DISABLE_DMABUF_RENDERER=1
exec ~/.local/share/bauh/appimage/installed/codenomad/CodeNomad-Tauri-0.4.0-linux-x64.AppImage "$@"Upstream tracking: tauri-apps/tauri#10702
CodeNomad is a monorepo split into specialized packages. If you want to contribute or build from source, check out the individual package documentation:
| Package | Description |
|---|---|
| packages/electron-app | The native desktop application shell. Wraps the UI and Server. |
| packages/server | The core logic and CLI. Manages workspaces, proxies OpenCode, and serves the API. |
| packages/ui | The SolidJS-based frontend. Fast, reactive, and beautiful. |
To build the Desktop App from source:
- Clone the repo.
- Run
npm install(requires pnpm or npm 7+ for workspaces). - Run
npm run build --workspace @neuralnomads/codenomad-electron-app.