Support and source builds

Use the repository for bug reports, current releases and contributions. The troubleshooting guide covers safe recovery before you report an issue.

Report a bug

Open Settings → Info → Diagnostics.
Select Report a bug to open the GitHub issue form.
Review the prefilled version/client information. Add a minimal reproduction, expected behavior and actual result, then submit through GitHub.

The action prefills the CodeNomad and OpenCode versions (including the running OpenCode service when it differs from the installed one), your operating system, the client type (with the browser's user agent in a web browser) and the server's operating system. It does not prefill listener addresses, workspace paths, credentials or conversation text. Opening the form is not submitting an issue.

If you need more diagnostics, Copy to clipboard or Download .txt produces a separate report. That fuller report can contain local paths and network addresses: review and redact it before attaching it. A screenshot or log excerpt can still contain secrets even when the automatic diagnostic report excludes authentication secrets.

If the GitHub form has incompatible fields, CodeNomad opens a plain issue with the same report information. A temporary failure reading the form does not prevent opening it. You can always use the issue list manually.

Community and releases

Resource	Use
CodeNomad repository	Source, project activity and documentation.
Issues	Search existing reports before opening a reproducible bug or feature request.
Pull requests	Review proposed changes or coordinate a contribution.
Latest release	Stable download artifacts.
All releases	Published previews and release notes.
Neural Nomads	Project organization.
MIT license	License terms.

For issues with native OpenCode configuration rather than CodeNomad controls, consult OpenCode's documentation and upstream releases.

Build from source

Use Node.js 24.20.0, as pinned in .node-version, npm, Git and a compatible OpenCode CLI. Run the commands from a development checkout:

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. To use Tauri, first install its platform build prerequisites, including the Rust toolchain, then run:

npm run dev:tauri

Development changes affect the development host, not an independently running OpenCode daemon's installed version. Native packaging needs the appropriate target tools; prefer builds on the target OS.

Build and validate

Command, from the repository root	Purpose
`npm run build`	Build the Electron application resources.
`npm run build:tauri`	Build the Tauri application with its native prerequisites.
`npm run build:ui`	Build the browser UI.
`npm run build --workspace @neuralnomads/codenomad`	Build the standalone server and bundled assets.
`npm run build:linux --workspace @neuralnomads/codenomad-electron-app`	Package the Electron Debian release.
`npm exec --workspace @codenomad/tauri-app -- tauri build --bundles appimage`	Package a Linux Tauri AppImage.
`npm run typecheck`	Check the root's configured TypeScript workspaces.
`npm run test:help`	Validate all public-help locales and links.
`npm run build:help`	Build the standalone public help into `dist/help`.

The help build does not need a running CodeNomad or OpenCode service. See BUILD.md for packaging details and CONTRIBUTING.md for scoped validation and PR conventions; use the scripts actually present in the target package.

Package map and contribution

Package	Responsibility
`packages/server`	Workspace/API/Git controls, OpenCode connection, auth, events and speech.
`packages/ui`	SolidJS workspace, controls, localization and browser help entry point.
`packages/electron-app`	Electron windows, native integration and packaging.
`packages/tauri-app`	Tauri windows, platform integration and packaging.
`packages/remote-tunnel`	Backend-side OpenTunnel transport runtime.

Discuss the scope in the relevant issue before implementing overlapping work.
Branch from dev and keep the change focused.
Run the checks for the affected area, update user help alongside behavior, and target your PR at dev.

Public help sources live in docs/help/<locale>/. Preserve each English heading's explicit ID, level and order across translations; translated headings must not break deep links. The help maintenance contract describes strict completeness checks and the static publishing pipeline.