mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-07-10 00:14:27 +00:00
b142c2a681
## Summary
Add comprehensive architecture and SDK navigation skill to help
contributors navigate the codebase without missing related code.
## What's Included
- **Architecture Overview** — 6 functional areas (UserInterface,
ServerBackend, DesktopClient, SpeechAndAudio, BuildAndPackaging,
CloudflareDeployment), package map, and key entry points
- **UI Conventions** — SolidJS patterns, i18n system (7 locales),
signal-based stores, component styling
- **Server Conventions** — Fastify route patterns, API types,
configuration, testing approach
- **Desktop Conventions** — Electron + Tauri parity rules, native API
abstractions
- **SDK API Reference** — All 10 OpenCode SDK V2 categories used by
CodeNomad with signatures and wrapper locations
- **SDK Critical Behaviors** — Schema gotchas (assistant part metadata,
ignored flag asymmetry), decision matrix, race conditions
- **SDK Integration Patterns** — Client lifecycle, worktree routing,
error handling, optimistic updates
- **Feature Traces** — 5 end-to-end flows with decision branches:
permissions, sessions, speech, background processes, git clone
- **Anti-Patterns** — Common mistakes with file references to correct
implementations
- **Implementation Checklist** — Actionable steps before submitting
changes
## Design Decisions
- All navigation guidance uses standard grep/file search tools (no RPG
MCP server required)
- Split into 8 reference files to stay under 300 lines each
- File references included for every anti-pattern and convention
- Decision branches in feature traces (not just linear flows)
- Weighted quick start by contribution frequency
## Files Added
`
.opencode/skills/codenomad-architecture-guide/
├── SKILL.md
└── references/
├── architecture-overview.md
├── ui-conventions.md
├── server-conventions.md
├── desktop-conventions.md
├── sdk-api-reference.md
├── sdk-critical-behaviors.md
├── sdk-integration-patterns.md
└── feature-traces.md
`
|
||
|---|---|---|
| .github | ||
| .opencode | ||
| dev-docs | ||
| docs | ||
| images | ||
| packages | ||
| scripts | ||
| tasks | ||
| temp | ||
| .gitignore | ||
| AGENTS.md | ||
| BUILD.md | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| PROGRESS.md | ||
| README.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 | AppImage, deb, tar.gz (x64, ARM64) |
💻 CodeNomad Server
Run as a local server and access via browser. Perfect for remote development.
npx @neuralnomads/codenomad --launch
See Server Documentation for flags, TLS, auth, and remote access.
🧪 Dev Releases
Bleeding-edge builds from the dev branch:
npx @neuralnomads/codenomad-dev --launch
SideCars
SideCars let you open local web tools inside CodeNomad as tabs.
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
See full workaround in the original README.
Community
Built with ♥ by Neural Nomads · MIT License