vrr/CodeNomad
2
0
Fork 0
mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-08-23 07:13:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
CodeNomad/dev-docs/SUMMARY.md
Pascal André b5f3fc6e82
feat(v2): unify global service and desktop windows 
Use the official host and WSL OpenCode service lifecycle instead of private daemon ownership. Workspace deletion now evicts only the selected location while shared sessions, agents, messages, and executions remain available to other windows.

Add profile-scoped singleton multi-window support for Electron and Tauri, isolate local window UI state in a durable partition graph, and preserve migration, fencing, bounded persistence, and cross-host ownership semantics. New Window and New Instance are exposed together in the native Window menu.

Harden renderer authority, remote profiles, SSE identity, idle attention, git-status concurrency, SideCar sandboxing, shutdown, generated Tauri ACLs, documentation, and CI coverage.

Validated with server, UI, Electron, and Tauri test matrices; TypeScript checks; cargo fmt; production Electron/server/Tauri builds; diff checks; and a packaged Windows smoke covering singleton focus, --new-window, one shared backend, menu placement, and slot hash verification.
2026-08-20 08:41:27 +02:00

5.9 KiB
Raw Permalink Blame History

CodeNomad - Project Summary

Current Status

The MVP and multi-instance milestones are complete. Current architecture and implementation details live in the documents indexed below.

What We've Created

Development documentation for the CodeNomad desktop application.

Directory Structure

packages/server/      Fastify control API and shared OpenCode service
packages/ui/          SolidJS UI and native Promise clients
packages/electron-app Electron host
packages/tauri-app/   Tauri host
dev-docs/             Development documentation

Documentation Overview

1. Architecture (architecture.md)

What it covers:

  • High-level system design
  • Component layers (Main process, Renderer, Communication)
  • State management approach
  • Tab hierarchy (Instance tabs → Session tabs)
  • Data flow for key operations
  • Technology stack decisions
  • Security considerations

Key sections:

  • Component architecture diagram
  • Instance/Session state structures
  • Communication patterns (HTTP, SSE)
  • Error handling strategies
  • Performance considerations

2. User Interface (user-interface.md)

What it covers:

  • Complete UI layout specifications
  • Visual design for every component
  • Interaction patterns
  • Keyboard shortcuts
  • Accessibility requirements
  • Empty states and error states
  • Modal designs

Key sections:

  • Detailed layout wireframes (ASCII art)
  • Component-by-component specifications
  • Message rendering formats
  • Control bar designs
  • Modal/overlay specifications
  • Color schemes and typography

3. Technical Implementation (technical-implementation.md)

What it covers:

  • Technology stack details
  • Project file structure
  • State management patterns
  • Shared OpenCode service and location ownership
  • Native @opencode-ai/client integration
  • /api/events multiplexing
  • IPC communication
  • Error handling strategies
  • Performance optimizations

Key sections:

  • Complete project structure
  • TypeScript interfaces
  • Hardened shared-service proof and location lifecycle
  • Native Promise client management
  • Message rendering implementation
  • Build and packaging config

Key Design Decisions

1. Two-Level Tabs

  • Level 1: Instance tabs (one per project folder)
  • Level 2: Session tabs (multiple per instance)
  • Allows working on multiple projects with multiple conversations each

2. Shared Service Management

  • CodeNomad uses the official host or WSL CLI lifecycle to connect to one externally owned global service
  • Workspace folders become validated native locations
  • UI traffic stays behind the CodeNomad proxy
  • Shutdown clears only CodeNomad's in-memory connection state and never stops the daemon
  • Explicit Stop Workspace evicts its location; tab/window close only detaches local UI

3. One Shared Service, Location-Scoped Clients

  • One proven shared endpoint serves all workspace locations
  • UI clients route through /workspaces/:id/instance/api/*
  • Server-side directory and session ownership prevents cross-contamination

4. SolidJS for Reactivity

  • Fine-grained reactivity for SSE updates
  • No re-render cascades
  • Better performance for real-time updates
  • Smaller bundle size than React

5. No Virtual Scrolling or Performance Optimization in MVP

  • Start with simple list rendering
  • Don't optimize for large sessions initially
  • Focus on functionality, not performance
  • Add optimizations in post-MVP phases if needed
  • Reduces initial complexity and speeds up development

6. Messages and Tool Calls Inline

  • All activity shows in main message stream
  • Tool calls expandable/collapsible
  • File changes visible inline
  • Single timeline view

Implementation Guidelines

Code Standards:

  • TypeScript for everything
  • No any types
  • Descriptive variable names
  • Comments for complex logic
  • Error handling on all async operations
  • Loading states for all network calls

Testing Approach:

  • Manual testing at each step
  • Test on minimum window size (800x600)
  • Test error cases
  • Test edge cases (long text, special chars)
  • Keyboard navigation verification

Useful References

Within This Project:

  • README.md - Project overview and getting started
  • dev-docs/architecture.md - System design
  • dev-docs/user-interface.md - UI specifications
  • dev-docs/technical-implementation.md - Implementation details

External:

Current OpenCode Baseline

  • Experimental protocol client: server and UI use the same reviewed version; the runtime opencode2 CLI is independently updated and checked through service/API compatibility, not an exact version gate
  • Service: one externally owned global endpoint with a CodeNomad-pinned host or WSL identity
  • Workspaces: native locations/directories
  • Database: OpenCode's global default; configured startup environment applies only when CodeNomad starts a missing daemon
  • Desktop: one singleton process/backend per channel/config profile, multiple UUID windows, and isolated stable/dev/non-default native state
  • Restore: V3 per-window envelope over a V2 content-addressed partition graph; OpenCode sessions/messages are shared while tabs/drafts/views are local
  • Events: volatile native stream with authoritative reconnect reconciliation
  • Proxy: explicit method/path allowlist; upstream additions are not automatic
  • Shell mode and instructions: native session APIs, separate from background Shell and PTY management
  • Background Shells: location-scoped native shell.* entries in Status, refreshed on Shell events/reconnect with metadata and ownership-checked removal; output uses native cursor pagination
  • PTYs: separate native interactive terminals, not background-process records
  • Legacy plugin/background processes: packages/opencode-plugin and server plugin/background-process paths remain deleted
  • Git mutations and Yolo: CodeNomad-owned