CodeNomad/README.md

CodeNomad

A cross-platform desktop application for interacting with OpenCode servers, built with Electron and SolidJS.

Overview

CodeNomad provides a multi-instance, multi-session interface for working with AI-powered coding assistants. It manages OpenCode server processes, handles real-time message streaming, and provides an intuitive UI for coding with AI.

🎯 MVP Focus: This project prioritizes functionality over performance. Performance optimization is intentionally deferred to post-MVP phases. See docs/MVP-PRINCIPLES.md for details.

Features

Core Capabilities

• Multi-Instance Management: Work on multiple projects simultaneously
• Session Persistence: Resume conversations across app restarts
• Real-time Streaming: Live message updates via Server-Sent Events
• Tool Execution Visibility: See bash commands, file edits, and other tool calls
• Agent & Model Switching: Easily switch between different AI agents and models
• Markdown Rendering: Beautiful code highlighting and formatting

Advanced Features (Planned)

• Virtual scrolling for large conversations
• Full-text search across sessions
• Workspace management
• Custom themes
• Plugin system

Architecture

See docs/architecture.md for detailed architecture documentation.

High-Level Overview

Electron App
├── Main Process (Node.js)
│   ├── Window management
│   ├── OpenCode server spawning
│   └── IPC communication
├── Renderer Process (SolidJS)
│   ├── UI components
│   ├── State management (stores)
│   └── SDK client communication
└── Multiple OpenCode Servers
    └── One per instance/project folder

Prerequisites

• Node.js 18+
• Bun package manager
• OpenCode CLI installed and in PATH

Installation

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Build distributable binaries
bun run build:mac      # macOS (Universal)
bun run build:win      # Windows (x64)
bun run build:linux    # Linux (x64)
bun run build:all      # All platforms

# See BUILD.md for more build options

Development

Project Structure

packages/opencode-client/
├── docs/              # Documentation
├── tasks/             # Task management
│   ├── todo/          # Pending tasks
│   └── done/          # Completed tasks
├── electron/          # Electron main process
│   ├── main/          # Main process code
│   ├── preload/       # Preload scripts
│   └── resources/     # App icons, etc.
└── src/               # Renderer (UI) code
    ├── components/    # UI components
    ├── stores/        # State management
    ├── lib/           # Utilities
    ├── hooks/         # SolidJS hooks
    └── types/         # TypeScript types

Tech Stack

• Electron - Desktop wrapper
• SolidJS - Reactive UI framework
• TypeScript - Type safety
• Vite - Build tool
• TailwindCSS - Styling
• Kobalte - Accessible UI primitives
• OpenCode SDK - API client

Scripts

bun run dev          # Start dev server with hot reload
bun run build        # Build for production
bun run typecheck    # Run TypeScript type checking
bun run preview      # Preview production build

Usage

Starting an Instance

1. Launch the app
2. Click "Select Folder" or press Cmd/Ctrl+N
3. Choose a project folder
4. Wait for OpenCode server to start
5. Select an existing session or create new one

Working with Sessions

• Switch sessions: Click session tab at bottom
• Create session: Click "+" button or Cmd/Ctrl+T
• Change agent: Use agent dropdown
• Change model: Use model dropdown

Sending Messages

• Type in the input box at bottom
• Press Enter for new line (Cmd+Enter on macOS, Ctrl+Enter on Windows/Linux)
• Use / for commands
• Use @ to mention files

Documentation

• Architecture - System design and structure
• User Interface - UI specifications
• Technical Implementation - Implementation details
• Build Roadmap - Development plan and phases
• Tasks - Task breakdown and tracking

Build Phases

The project is built in phases:

1. Phase 1: Foundation (Tasks 001-005)
2. Phase 2: Core Chat (Tasks 006-010)
3. Phase 3: Essential Features (Tasks 011-015)
4. Phase 4: Multi-Instance (Tasks 016-020)
5. Phase 5: Advanced Input (Tasks 021-025)
6. Phase 6: Polish & UX (Tasks 026-030)
7. Phase 7: System Integration (Tasks 031-035)
8. Phase 8: Advanced Features (Tasks 036-040)

See docs/build-roadmap.md for detailed phase information.

Contributing

Getting Started

1. Read the documentation in docs/
2. Check tasks/todo/ for available tasks
3. Pick a task and create a feature branch
4. Follow the task steps
5. Submit PR when complete

Code Style

• Use TypeScript for all code
• Follow existing patterns and conventions
• Write clear, descriptive commit messages
• Add comments for complex logic
• Keep components small and focused

Testing

• Test manually at minimum window size (800x600)
• Test on multiple platforms (macOS, Windows, Linux)
• Verify keyboard navigation works
• Check accessibility with screen readers

Troubleshooting

Server Won't Start

• Verify opencode is in PATH: which opencode
• Check folder permissions
• Review server logs in Logs tab
• Try restarting the instance

Connection Issues

• Check if server is running: ps aux | grep opencode
• Verify port is correct in instance metadata
• Check for firewall blocking localhost
• Try killing and restarting server

Performance Issues

• Check number of messages in session
• Monitor memory usage in Activity Monitor
• Consider enabling virtual scrolling (Phase 8)
• Close unused instances

License

[License TBD]

Credits

Built with ❤️ for the OpenCode project.