mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-09-12 03:36:03 +00:00
ea37f97bea
## Summary Restore selective deletion of completed assistant tool/reasoning content after OpenCode removed `session.messageUpdate`, without forking OpenCode or opening a generic RPC proxy. The original draft's unconditional `maintenance_required` stub is replaced by a working **experimental, explicit opt-in** plugin path for the audited `0.0.0-beta-19419` runtime. The default remains read-only. Unknown runtimes/storage and active native execution fail closed. Nothing is installed or enabled on app startup. ## Implementation - Keep individual/message/group/session cleanup entry points. Send selected technical indices and a canonical SHA-256 revision, never arbitrary replacement content, SQL, database filenames or caller-selected locations. - Use an ownership-checked CodeNomad broker with a fixed RPC ID/method/location and worktree-deletion fence. Keep the removed PATCH and generic RPC routes blocked. - Bind the plugin's explicitly configured database connection to the actual daemon DB with a fresh `ctx.storage` challenge. Inside a synchronous SQLite write transaction, recheck directory/project/workspace ownership, native durable execution claim, staged revert/compaction state, event ownership and retained payloads. - Rely on the audited native **write-ahead execution claim before runner history reads**, not an `idle` check, plugin mutex or `BEGIN IMMEDIATE` alone. Never set or release the native claim ourselves. - CAS only the completed assistant's content array. Preserve IDs, ordering, text, snapshots, usage and metadata. Commit a content-free idempotency receipt atomically with the change; identical retries cannot delete a second shifted block. - Emit the custom invalidation after commit. Re-read via the native API, invalidate the SDK transcript and pending rotations, and fence late reads against newer invalidations. Add a public-API TUI cache companion and reconnect handling. - Correct native Windows path encoding; support more than 4,096 selected parts within explicit request/message budgets. - Provide an independently packable plugin with main and `./tui` entrypoints, deployment/safety docs, and a Windows/Linux/macOS native package CI matrix. Plugin installation remains manual and separately approved. ## Validation performed locally | Check | Result | |---|---| | Server/plugin/SQLite/broker/proxy tests | 72 passed | | UI actions, events, SDK projection and stale-read tests | 60 passed | | Plugin/SQLite/TUI-companion tests under Node 22 | 30 passed | | Server and UI TypeScript checks | Passed | | Production UI build | Passed; existing large-chunk warnings | | Official Windows x64 beta-19419 executable | Passed on a private daemon and generated DB | | Independently packed and installed plugin | Same native test passed, outside the checkout | The native integration test uses the real beta-19271 network client against the official beta-19419 runtime, with a local synthetic provider and no credentials. It verifies actual preview/prune RPC, refusal while a primary generation holds the native claim, both prompt/transaction orderings, idempotent retry, two event subscribers, native re-reading, the subsequent primary model payload, fork isolation, pre-compaction history without summary changes, and persistence after server restart. The new three-OS native CI matrix must pass on this head before merge. No CI result is inferred from the local Windows run. ## Boundaries and remaining validation - This is a reviewable opt-in implementation, **not general availability across OpenCode versions/providers/platforms**. Exact runtime gating is intentional; don't widen it without re-auditing/testing. - Interactive official TUI, two native CodeNomad windows/scroll behavior, WSL, provider-specific continuation state and budget/token estimates are not claimed as validated. TUI companion tests use its cache contract, not an interactive terminal. Two HTTP subscribers are not two GUI windows. - Existing bulk cleanup is per-message and reports failure counts; dedicated installation/capability and bulk progress/cancel UI are not added here. - Existing summaries/native checkpoints, fork copies and already assembled/sent requests are not retroactively scrubbed. Historical usage remains historical usage; mock token values are not a token-savings measurement. - This changes persisted V2 content, not only visibility. It frees reusable SQLite pages but does **not** promise a smaller physical file. No VACUUM, V1 cleanup, durable-event rewriting, automatic backup restoration or universal repair is included. - No active user DB was changed, no shared-daemon plugin installed, no shared OpenCode service stopped/upgraded, and no native desktop executable/profile rebuilt or replaced. Tests use isolated synthetic data only. ## Documentation - [Request flow and validation](dev-docs/SESSION_PRUNING_RPC.md) - [Audited safety boundary](dev-docs/SESSION_PRUNING_SAFETY.md) - [Explicit deployment and recovery](dev-docs/SESSION_PRUNING_DEPLOYMENT.md) References: anomalyco/opencode#44984, anomalyco/opencode#48043, anomalyco/opencode#48090 and the maintainer's plugin/RPC direction. No upstream API or distribution fork is introduced. |
||
|---|---|---|
| .github | ||
| .opencode | ||
| dev-docs | ||
| docs | ||
| images | ||
| packages | ||
| scripts | ||
| temp | ||
| .gitignore | ||
| 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