vrr/CodeNomad
2
0
Fork 0
mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-08-20 22:03:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
CodeNomad/dev-docs/SUMMARY.md
Pascal André 4359b4bfe9
fix(v2): align with current OpenCode client contract 
Pin the server and UI client to the installed beta runtime and reject mismatched CLI versions before shared-service startup. Delegate proven shared-service shutdown to Service.stop while retaining CodeNomad lease, peer, registration, endpoint, and process-identity checks.

Adopt native Forms and the client/solid data reducer for live messages, tools, permissions, and input forms. Propagate internal stream generations into authoritative reconnect reconciliation and replace directory-wide session scans with native project cursor pagination.

Fail worktree deletion when session evacuation fails and deduplicate canonical workspace folders instead of exposing non-isolated duplicate instances. Update migration notes and CI coverage for the reviewed contract.

Validated with server/UI/Electron typechecks, 244 UI partition tests, 122 Electron native tests, 248 server tests plus 3 platform skips (the sole Windows cleanup race passed in isolation), UI/server/Electron builds, Tauri cargo check --locked, and git diff --check.
2026-08-19 01:50:39 +02:00

5.6 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 server discovers or launches one service through its hardened lifecycle; production does not call Service.ensure/Service.stop directly
  • Workspace folders become validated native locations
  • UI traffic stays behind the CodeNomad proxy
  • Shutdown transfers proof to a live peer or stops only the exact proven daemon when no peer remains

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, UI, and the runtime opencode2 CLI use the exact version pinned in the server package; every upgrade reviews release notes, current documentation, installed declarations, and proxy/API parity
  • Service: one shared endpoint managed by CodeNomad's lease-locked process-proof lifecycle
  • Workspaces: native locations/directories
  • Database: V2 always uses ~/.local/share/opencode2/opencode.db, separate from V1
  • Events: volatile native stream with authoritative reconnect reconciliation
  • Proxy: explicit method/path allowlist; upstream additions are not automatic
  • Shell and instructions: native session APIs, separate from PTY management
  • PTYs: location-scoped native entries in Status, refreshed on PTY events/reconnect with metadata, title updates, and ownership-checked removal; current installed declarations have no output/read/stream or separate stop API, so output and distinct stop are unavailable and removal stops a running PTY
  • Legacy plugin/background processes: packages/opencode-plugin and server plugin/background-process paths remain deleted
  • Git mutations and Yolo: CodeNomad-owned