diff --git a/README.md b/README.md index 44429b9e..07b22538 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,63 @@ # CodeNomad -## A fast, multi-instance desktop client for running OpenCode sessions the way long-haul builders actually work. -## What is CodeNomad? +## A fast, multi-instance workspace for running OpenCode sessions. -CodeNomad is built for people who live inside OpenCode for hours on end and need a cockpit, not a kiosk. When terminals get unwieldy and web clients feel laggy, CodeNomad delivers a desktop-native workspace that favors speed, clarity, and direct control. It runs on macOS, Windows, and Linux using Electron + SolidJS, with prebuilt binaries so you can get started immediately. +CodeNomad is built for people who live inside OpenCode for hours on end and need a cockpit, not a kiosk. It delivers a premium, low-latency workspace that favors speed, clarity, and direct control. ![Multi-instance workspace](docs/screenshots/newSession.png) - ![Command palette overlay](docs/screenshots/command-palette.png) +
+๐Ÿ“ธ More Screenshots + +_More screenshots coming soon..._ + +
+ +## Getting Started + +Choose the way that fits your workflow: + +### ๐Ÿ–ฅ๏ธ Desktop App (Recommended) +The best experience. A native application with global shortcuts, deeper system integration, and a dedicated window. + +- **Download**: Grab the latest installer for macOS, Windows, or Linux from the [Releases Page](https://github.com/shantur/CodeNomad/releases). +- **Run**: Install and launch like any other app. + +### ๐Ÿ’ป CodeNomad Server +Run CodeNomad as a local server and access it via your web browser. Perfect for remote development (SSH/VPN) or running as a service. + +```bash +npx @neuralnomads/codenomad --launch +``` + +This command starts the server and opens the web client in your default browser. + ## Highlights -- **Long-session native** โ€“ scroll through massive transcripts without hitches and keep full context visible. -- **Multiple instances, one window** โ€“ juggle several OpenCode instances side-by-side with per-instance tabs. -- **Deep task awareness** โ€“ jump into sub/child sessions (Tasks tool) instantly, monitor their status, and answer directly without losing your flow. -- **Keyboard first** โ€“ the full UI is optimized for shortcuts so you can stay mouse-free when you want to. -- **Command palette superpowers** โ€“ summon a single, global palette to jump tabs, launch tools, tweak preferences, or fire shortcuts. Every action is categorized, fuzzy searchable, and previewed so you can chain moves together in seconds. It keeps your workflow predictable and fast whether you are juggling one session or ten. -- **Developer-friendly rendering** โ€“ syntax highlighting, inline diffs, and thoughtful presentation keep the signal high. +- **Multi-Instance**: Juggle several OpenCode sessions side-by-side with tabs. +- **Long-Session Native**: Scroll through massive transcripts without hitches. +- **Command Palette**: A single global palette to jump tabs, launch tools, and control everything. +- **Deep Task Awareness**: Monitor background tasks and child sessions without losing flow. ## Requirements -- [OpenCode CLI](https://opencode.ai) installed and available in your `PATH`, or point CodeNomad to a local binary through Advanced Settings. +- **[OpenCode CLI](https://opencode.ai)**: Must be installed and available in your `PATH`. +- **Node.js 18+**: Required if running the CLI server or building from source. -## Repository Layout +## Architecture & Development -CodeNomad now ships as a small workspace with two packages: +CodeNomad is a monorepo split into specialized packages. If you want to contribute or build from source, check out the individual package documentation: -- `packages/ui` โ€” SolidJS renderer, Tailwind styles, and standalone Vite configuration for building the UI bundle independently. -- `packages/electron-app` โ€” Electron main/preload processes plus packaging scripts. It consumes the UI package during development/build via `electron-vite`. +| Package | Description | +|---------|-------------| +| **[packages/electron-app](packages/electron-app/README.md)** | The native desktop application shell. Wraps the UI and Server. | +| **[packages/server](packages/server/README.md)** | The core logic and CLI. Manages workspaces, proxies OpenCode, and serves the API. | +| **[packages/ui](packages/ui/README.md)** | The SolidJS-based frontend. Fast, reactive, and beautiful. | -Use `npm run dev --workspace @neuralnomads/codenomad-electron-app` for the Electron shell and `npm run dev --workspace @codenomad/ui` for UI-only work. Working with the workspace requires Node.js 18+ with npm 7 or newer so the workspace protocol is available. - -## Downloads - -Grab the latest build for macOS, Windows, and Linux from the [GitHub Releases page](https://github.com/shantur/CodeNomad/releases). - -## Quick Start - -1. Install the OpenCode CLI and confirm it is reachable via your terminal. -2. Download the CodeNomad build for your platform and launch the app. -3. Connect to one or more OpenCode instances, set keyboard shortcuts in preferences, and start a session. -4. Use tabs to swap between instances, the task sidebar to dive into child sessions, and the prompt input to keep shipping. - -## CLI Server Flags - -The bundled CLI server (`@neuralnomads/codenomad`) controls which folders the UI can browse when you pick a workspace: - -- `--workspace-root ` (default: current working directory) scopes browsing to a safe subtree. The UI can only see folders beneath this root. -- `--unrestricted-root` explicitly allows full-machine browsing for the current process. In this mode the UI starts from the host home directory, adds a "parent" option so you can reach `/` on macOS/Linux, and lists drives/UNC paths on Windows. The flag is runtime-onlyโ€”restart the CLI without it to go back to restricted mode. -- `--ui-dev-server ` proxies UI asset requests to a running Vite dev server while the CLI continues to expose its REST APIs and workspace proxies from the same port. Point this at `http://localhost:3000` when developing the renderer to keep hot reloads without sacrificing the single entry point. - -Use unrestricted mode only when you trust the host; the CLI will skip directories it cannot read and never persists the opt-in. - -### Single Port Proxying - -Every OpenCode instance now tunnels through the CLI port. Each workspace descriptor publishes a stable `proxyPath` (e.g., `/workspaces//instance`), and the CLI exposes `GET/POST/...` + SSE at `http(s)://:${proxyPath}`. That means the UI, Electron shell, and browser clients only need firewall access to the CLI; instance ports stay private on `127.0.0.1`. In development, the `--ui-dev-server` flag still routes UI traffic through the CLI proxy so all instance calls share the same origin. +### Quick Build +To build the Desktop App from source: +1. Clone the repo. +2. Run `npm install` (requires pnpm or npm 7+ for workspaces). +3. Run `npm run build --workspace @neuralnomads/codenomad-electron-app`. diff --git a/packages/electron-app/README.md b/packages/electron-app/README.md new file mode 100644 index 00000000..6e9a6809 --- /dev/null +++ b/packages/electron-app/README.md @@ -0,0 +1,40 @@ +# CodeNomad App + +This package contains the native desktop application shell for CodeNomad, built with [Electron](https://www.electronjs.org/). + +## Overview + +The Electron app wraps the CodeNomad UI and Server into a standalone executable. It provides deeper system integration, such as: +- Native window management +- Global keyboard shortcuts +- Application menu integration + +## Development + +To run the Electron app in development mode: + +```bash +npm run dev +``` + +This will start the renderer (UI) and the main process with hot reloading. + +## Building + +To build the application for your current platform: + +```bash +npm run build +``` + +To build for specific platforms (requires appropriate build tools): + +- **macOS**: `npm run build:mac` +- **Windows**: `npm run build:win` +- **Linux**: `npm run build:linux` + +## Structure + +- `electron/main`: Main process code (window creation, IPC). +- `electron/preload`: Preload scripts for secure bridge between main and renderer. +- `electron/resources`: Static assets like icons. diff --git a/packages/server/README.md b/packages/server/README.md new file mode 100644 index 00000000..0649aa22 --- /dev/null +++ b/packages/server/README.md @@ -0,0 +1,58 @@ +# 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**: `opencode` must 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 `--launch` to open the UI automatically. + +## Usage + +### Run via npx (Recommended) +You can run CodeNomad directly without installing it: + +```sh +npx @neuralnomads/codenomad --launch +``` + +### Install Globally +Or install it globally to use the `codenomad` command: + +```sh +npm install -g @neuralnomads/codenomad +codenomad --launch +``` + +### Common Flags +You can configure the server using flags or environment variables: + +| Flag | Env Variable | Description | +|------|--------------|-------------| +| `--port ` | `CLI_PORT` | HTTP port (default 9898) | +| `--host ` | `CLI_HOST` | Interface to bind (default 127.0.0.1) | +| `--workspace-root ` | `CLI_WORKSPACE_ROOT` | Default root for new workspaces | +| `--unrestricted-root` | `CLI_UNRESTRICTED_ROOT` | Allow full-filesystem browsing | +| `--config ` | `CLI_CONFIG` | Config file location | +| `--launch` | `CLI_LAUNCH` | Open the UI in a Chromium-based browser | +| `--log-level ` | `CLI_LOG_LEVEL` | Logging level (trace, debug, info, warn, error) | + +### Data Storage +- **Config**: `~/.config/codenomad/config.json` +- **Instance Data**: `~/.config/codenomad/instances` (chat history, etc.) +