9bf4d351de
# Git Changes PR Review Context Fixes: #310 ## Purpose of this document This document is intended to give a PR reviewer or gatekeeper enough neutral context to review the Git Changes feature series accurately. ## BEFORE/AFTER SNAPSHOT: <img width="835" height="1163" alt="image" src="https://github.com/user-attachments/assets/463d6f8c-1a6b-4cf0-8ab8-44a92c534ca5" /> It distinguishes: 1. the intended scope of the work 2. implementation choices that were deliberate 3. behaviors that were explicitly tested and accepted during development 4. remaining follow-up areas that were not part of the required intent It should not be treated as a request to approve the PR automatically. It exists to reduce false-positive review findings caused by missing context. --- ## High-level scope The work in this series refactors and extends the existing `Git Changes` tab in the right panel. The intended feature scope includes: 1. grouped staged / unstaged change presentation 2. correct section-aware diff loading 3. per-file stage / unstage controls 4. commit message compose box and commit action for staged changes 5. prompt-context insertion from the Git diff viewer 6. auto-refresh behavior that reduces dependence on the manual refresh button This work is intentionally implemented inside the existing Git Changes vertical slice rather than as a new SCM subsystem. --- ## Files and areas intentionally changed ### Server / API surface The following server areas were intentionally extended: 1. `packages/server/src/api-types.ts` 2. `packages/server/src/events/bus.ts` 3. `packages/server/src/server/http-server.ts` 4. `packages/server/src/server/routes/workspaces.ts` 5. `packages/server/src/workspaces/git-status.ts` 6. `packages/server/src/workspaces/git-mutations.ts` 7. `packages/server/src/workspaces/worktree-directory.ts` 8. `packages/server/src/workspaces/instance-events.ts` ### UI surface The following UI areas were intentionally extended: 1. `packages/ui/src/components/file-viewer/monaco-diff-viewer.tsx` 2. `packages/ui/src/components/instance/instance-shell2.tsx` 3. `packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx` 4. `packages/ui/src/components/instance/shell/right-panel/git-changes-model.ts` 5. `packages/ui/src/components/instance/shell/right-panel/tabs/GitChangesTab.tsx` 6. `packages/ui/src/components/instance/shell/right-panel/types.ts` 7. `packages/ui/src/components/instance/shell/storage.ts` 8. `packages/ui/src/components/prompt-input.tsx` 9. `packages/ui/src/components/prompt-input/types.ts` 10. `packages/ui/src/components/session/session-view.tsx` 11. `packages/ui/src/lib/api-client.ts` 12. `packages/ui/src/lib/i18n/messages/*/instance.ts` 13. `packages/ui/src/styles/panels/right-panel.css` --- ## Intentional product and architecture decisions The following outcomes were deliberate and should not be flagged as issues merely because they exist. ### Git status / diff architecture 1. The UI does not rely only on the proxied OpenCode `file.status()` payload. 2. CodeNomad adds server-backed worktree Git status and diff endpoints to expose staged / unstaged semantics correctly. 3. Server-backed worktree mutation endpoints were added for: - stage - unstage - commit 4. The existing event bus / SSE channel is reused for Git invalidation, instead of adding a bespoke invalidation route. ### Git Changes UI structure 1. The file list is grouped into: - `Staged Changes` - `Changes` 2. Both sections are collapsible. 3. Section open state is persisted. 4. The same file may appear in both sections when Git state genuinely requires that. 5. Rows are filename-first, with parent path as secondary text. 6. Rows are intentionally compact compared to the original flat list. ### Diff behavior 1. Diff loading is section-aware. 2. Deleted files are supported in grouped mode. 3. Binary files are treated as non-line-oriented in the diff viewer. 4. Binary diffs suppress line-based prompt-context affordances. ### Stage / unstage / commit workflow 1. Stage and unstage are per-file row actions. 2. Bulk stage-all / unstage-all was intentionally not added. 3. The commit compose box is intentionally rendered inside the `Staged Changes` section. 4. The commit button is intentionally overlaid inside the commit input area. 5. The current commit compose flow is minimal by design: - no push - no amend flow - no branch management ### Prompt-context insertion 1. Prompt insertion is intentionally an HTML comment marker, not a full diff payload. 2. The expected inserted form is: `<!-- Git change context: <path> lines X-Y -->` 3. The trigger UI is intentionally a seam/gutter action in the Monaco diff viewer, not a toolbar button. ### Row action reveal behavior 1. Stage / unstage row actions are intentionally hover-revealed on hover-capable layouts. 2. The row action reveal intentionally uses: - delayed hide - slight stats fade/shift - compact idle width 3. On non-hover layouts, the action remains visible for reliability. ### Auto-refresh behavior The accepted refresh model is intentionally hybrid: 1. refresh on Git Changes tab activation 2. 20-second polling only while the Git Changes tab is active 3. immediate invalidation from completed raw tool events for: - `write` - `edit` - `apply_patch` This hybrid model is intentional. Polling remains as a fallback even after tool-event invalidation. --- ## Behaviors explicitly tested during development The following behaviors were explicitly exercised during development and used to guide fixes. ### Grouped staged / unstaged behavior 1. files appear in the correct staged / unstaged sections 2. section collapse / expand works 3. collapse state persists 4. line counts are section-specific ### Diff behavior 1. staged diff loads differently from unstaged diff 2. deleted-file handling was verified and corrected 3. binary-file rendering was corrected to avoid line-oriented behavior 4. untracked binary files no longer report fake text line counts ### Mutation behavior 1. per-file stage works from `Changes` 2. per-file unstage works from `Staged Changes` 3. stage / unstage selection remapping was exercised and corrected 4. unborn-repo unstage behavior was explicitly hardened ### Prompt-context behavior 1. selected line / range insertion was tested 2. button placement in the Monaco seam/gutter was iterated and verified ### Auto-refresh behavior 1. tab-activation refresh was tested 2. 20-second active-tab polling was tested 3. raw completed tool invalidation was tested in the running UI for: - `write` - `edit` - `apply_patch` 4. stale async overwrite and stale selection restoration bugs were found and fixed through review/testing --- ## Review findings that were investigated and are no longer intended blocker topics The following areas were previously raised by strict reviews and then either fixed or determined to be acceptable within scope. ### Fixed in the current series 1. duplicate stage / unstage firing 2. stale diff response overwriting newer selection 3. passive refresh restoring a stale selection 4. instance-wide invalidation overreach 5. selected diff staying stale after tool invalidation 6. worktree-switch status races 7. unhandled rejection risk from async invalidation publication 8. queued invalidation intent being lost during in-flight refresh 9. `git-diff` path traversal / absolute path boundary issue ### Investigated and considered non-blocking within current intent 1. split add/delete presentation for tracked rename behavior - this was compared against VS Code behavior during manual testing - no stage/unstage corruption was observed in the tested flow - this is currently treated as a representation tradeoff, not a proven blocker --- ## Remaining non-blocker follow-up areas The following are still reasonable follow-up topics, but they were not part of the required blocker-fix scope. 1. normalize directory-to-worktree matching more aggressively on Windows so tool invalidation works more reliably from nested directories or path-format variations 2. improve keyboard discoverability of hover-revealed stage / unstage actions 3. reserve textarea space for the overlaid commit button if the overlay tradeoff is reconsidered 4. reduce size/complexity in: - `RightPanel.tsx` - `right-panel.css` 5. tighten raw SSE tool-event parsing into a more explicit helper if that event bridge grows further These follow-ups should not be interpreted as evidence that the core implementation is incomplete unless a reviewer finds a new concrete failure. --- ## Suggested review focus If a gatekeeper or reviewer is evaluating this PR, the most useful focus areas are: 1. whether staged / unstaged behavior is correct for normal Git workflows 2. whether the new server worktree Git endpoints remain narrowly scoped 3. whether auto-refresh remains bounded to the active Git Changes context 4. whether the explicit fixes for stale async behavior and invalidation races are sufficient 5. whether any unintentional server boundary broadening or state corruption remains Less useful review topics, unless tied to a concrete failure, are: 1. preference disagreements with accepted prompt insertion format 2. preference disagreements with the overlaid commit button placement 3. preference disagreements with keeping polling fallback alongside tool invalidation 4. objections to server-backed Git endpoints purely because they add surface area --- ## Summary This series intentionally evolves the existing Git Changes tab into a more complete source-control workflow for: 1. grouped staged / unstaged inspection 2. section-aware diffs 3. per-file staging and unstaging 4. commit composition for staged changes 5. prompt-context insertion from Git diffs 6. bounded auto-refresh for both passive viewing and agent-driven file mutations The intended review standard is to find concrete correctness, layering, or maintenance problems that remain after this series — not to re-argue the already accepted product choices listed above. --------- Co-authored-by: Shantur Rathore <i@shantur.com>
CodeNomad Server
CodeNomad Server is the high-performance engine behind the CodeNomad cockpit. It transforms your machine into a robust development host, managing the lifecycle of multiple OpenCode instances and providing the low-latency data streams that long-haul builders demand. It bridges your local filesystem with the UI, ensuring that whether you are on localhost or a remote tunnel, you have the speed, clarity, and control of a native workspace.
Features & Capabilities
🌍 Deployment Freedom
- Remote Access: Host CodeNomad on a powerful workstation and access it from your lightweight laptop.
- Code Anywhere: Tunnel in via VPN or SSH to code securely from coffee shops or while traveling.
- Multi-Device: The responsive web client works on tablets and iPads, turning any screen into a dev terminal.
- Always-On: Run as a background service so your sessions are always ready when you connect.
⚡️ Workspace Power
- Multi-Instance: Juggle multiple OpenCode sessions side-by-side with per-instance tabs.
- Long-Context Native: Scroll through massive transcripts without hitches.
- Deep Task Awareness: Monitor background tasks and child sessions without losing your flow.
- Command Palette: A single, global palette to jump tabs, launch tools, and fire shortcuts.
Prerequisites
- OpenCode:
opencodemust be installed and configured on your system. - Node.js 18+ and npm (for running or building from source).
- A workspace folder on disk you want to serve.
- Optional: a Chromium-based browser if you want
--launchto open the UI automatically.
Usage
Run via npx (Recommended)
You can run CodeNomad directly without installing it:
npx @neuralnomads/codenomad --launch
To list all CLI options:
npx @neuralnomads/codenomad --help
On startup, CodeNomad prints two URLs:
Local Connection URL : ...(used by desktop shells)Remote Connection URL : ...(used by browsers/other machines when remote access is enabled)
Install Globally
Or install it globally to use the codenomad command:
npm install -g @neuralnomads/codenomad
codenomad --launch
Install Locally (per-project)
If you prefer to install CodeNomad into a project and run the local binary:
npm install @neuralnomads/codenomad
npx codenomad --launch
(npx codenomad ... will use ./node_modules/.bin/codenomad when present.)
Common Flags
You can configure the server using flags or environment variables:
| Flag | Env Variable | Description |
|---|---|---|
--https <enabled> |
CLI_HTTPS |
Enable HTTPS listener (default true) |
--http <enabled> |
CLI_HTTP |
Enable HTTP listener (default false) |
--https-port <number> |
CLI_HTTPS_PORT |
HTTPS port (default 9898, use 0 for auto) |
--http-port <number> |
CLI_HTTP_PORT |
HTTP port (default 9899, use 0 for auto) |
--tls-key <path> |
CLI_TLS_KEY |
TLS private key (PEM). Requires --tls-cert. |
--tls-cert <path> |
CLI_TLS_CERT |
TLS certificate (PEM). Requires --tls-key. |
--tls-ca <path> |
CLI_TLS_CA |
Optional CA chain/bundle (PEM) |
--tlsSANs <list> |
CLI_TLS_SANS |
Additional TLS SANs (comma-separated) |
--host <addr> |
CLI_HOST |
Interface to bind (default 127.0.0.1) |
--workspace-root <path> |
CLI_WORKSPACE_ROOT |
Restricts the root path where new workspaces can be opened. Git worktrees are created in .codenomad/worktrees inside the project folder. |
--unrestricted-root |
CLI_UNRESTRICTED_ROOT |
Allow full-filesystem browsing |
--config <path> |
CLI_CONFIG |
Config file location |
--launch |
CLI_LAUNCH |
Open the UI in a Chromium-based browser |
--log-level <level> |
CLI_LOG_LEVEL |
Logging level (trace, debug, info, warn, error) |
--log-destination <path> |
CLI_LOG_DESTINATION |
Log destination file (defaults to stdout) |
--username <username> |
CODENOMAD_SERVER_USERNAME |
Username for CodeNomad's internal auth (default codenomad) |
--password <password> |
CODENOMAD_SERVER_PASSWORD |
Password for CodeNomad's internal auth |
--generate-token |
CODENOMAD_GENERATE_TOKEN |
Emit a one-time local bootstrap token for desktop flows |
--dangerously-skip-auth |
CODENOMAD_SKIP_AUTH |
Disable CodeNomad's internal auth (use only behind a trusted perimeter) |
--ui-dir <path> |
CLI_UI_DIR |
Directory containing the built UI bundle |
--ui-dev-server <url> |
CLI_UI_DEV_SERVER |
Proxy UI requests to a running dev server (requires --https=false --http=true) |
--ui-no-update |
CLI_UI_NO_UPDATE |
Disable remote UI updates |
--ui-auto-update <enabled> |
CLI_UI_AUTO_UPDATE |
Enable remote UI updates (true |
--ui-manifest-url <url> |
CLI_UI_MANIFEST_URL |
Remote UI manifest URL |
Dev Releases (Advanced)
If you want the latest bleeding-edge builds (published as GitHub pre-releases), use the dev package:
npx @neuralnomads/codenomad-dev --launch
These environment variables control how CodeNomad checks for dev updates:
| Env Variable | Description |
|---|---|
CODENOMAD_UPDATE_CHANNEL |
Update channel (use dev to enable dev build update checks) |
CODENOMAD_GITHUB_REPO |
GitHub repo used for dev release checks (default NeuralNomadsAI/CodeNomad) |
HTTP vs HTTPS
- Default:
--https=true --http=false(HTTPS only). - To run plain HTTP only (useful for development):
codenomad --https=false --http=true
- To run both HTTPS (for remote) and HTTP loopback (for desktop):
codenomad --https=true --http=true
Remote Access Binding Rules
- When remote access is enabled (bind host is non-loopback, e.g.
--host 0.0.0.0):- HTTP listens on
127.0.0.1only. - HTTPS listens on
--host(LAN/all interfaces).
- HTTP listens on
- When remote access is disabled (bind host is loopback, e.g.
--host 127.0.0.1):- Both HTTP and HTTPS listen on
127.0.0.1.
- Both HTTP and HTTPS listen on
Self-Signed Certificates
If --https=true and you do not provide --tls-key/--tls-cert, CodeNomad generates a local certificate automatically under your config directory:
~/.config/codenomad/tls/ca-cert.pem~/.config/codenomad/tls/server-cert.pem
Certificates are valid for about 30 days and rotate automatically on startup when needed. You can add extra SANs via:
codenomad --tlsSANs "localhost,127.0.0.1,my-hostname,192.168.1.10"
Authentication
- Default behavior: CodeNomad requires a login (username/password) and stores a session cookie in the browser.
--dangerously-skip-auth/CODENOMAD_SKIP_AUTH=truedisables the login prompt and treats all requests as authenticated. Use this only when access is already protected by another layer (SSO proxy, VPN, Coder workspace auth, etc.). If you bind to0.0.0.0while skipping auth, anyone who can reach the port can access the API.
Progressive Web App (PWA)
When running as a server CodeNomad can also be installed as a PWA from any supported browser, giving you a native app experience just like the Electron installation but executing on the remote server instead.
- Open the CodeNomad UI in a Chromium-based browser (Chrome, Edge, Brave, etc.).
- Click the install icon in the address bar, or use the browser menu → "Install CodeNomad".
- The app will open in a standalone window and appear in your OS app list.
TLS requirement Browsers require a secure (
https://) connection for PWA installation. If you host CodeNomad on a remote machine, use HTTPS. Self-signed certificates generally won't work unless they are explicitly trusted by the device/browser (e.g., via a custom CA).
Data Storage
- Config:
~/.config/codenomad/config.json - Instance Data:
~/.config/codenomad/instances(chat history, etc.)