Roxy

An open-source AI coding agent for engineers — built as a cross-platform desktop app.

Download: https://roxy.gg

Roxy is an Electron application written in TypeScript with a React renderer. It ships a full agent harness in the main process: a provider-agnostic tool-calling loop, per-model tuned system prompts, Plan/Build agents and subagents, disk-backed context management, and integrations for MCP servers, language-server diagnostics, and SKILL.md skills.

Tech stack

Layer	Choice
Desktop	Electron 33
Build tool	electron-vite (Vite 5)
UI	React 18 + TypeScript
Styling	Tailwind CSS v4
Tool-calling	Vercel AI SDK (Anthropic + Google)
Integrations	Model Context Protocol SDK
Storage	better-sqlite3
Packaging	electron-builder
Formatting	Prettier

Project structure

roxy/
├── build/                  # Packaging resources (icons, entitlements)
├── resources/              # Static assets bundled with the app
│   └── prompts/            # Tuned per-model + agent system prompts (inlined at build via ?raw)
├── src/
│   ├── main/               # Electron main process (Node.js)
│   │   ├── index.ts        # App lifecycle, window creation, service startup
│   │   ├── harness/        # The agent loop: agent.ts (loop + tool schemas), tools.ts (dispatch)
│   │   ├── services/       # llm.ts, aisdk.ts, mcp.ts, lsp.ts, skills.ts, browser.ts, automation.ts, …
│   │   ├── db/             # better-sqlite3 store: schema, migrations, repo
│   │   └── ipc/            # ipcMain handlers wiring the renderer to the harness/services
│   ├── preload/            # Secure bridge between main and renderer (window.api)
│   ├── renderer/           # React app (Chromium): routes, components, store
│   └── shared/             # Pure, cross-process modules: tools, agents, prompt/prompt-text,
│                           #   providers, context, tool-history, mcp, lsp, skills, web, types
├── test/                   # smoke.ts (Electron) + shared.ts (pure Node) validation suites
├── electron.vite.config.ts # Main / preload / renderer build config
└── electron-builder.yml    # Distribution config

Getting started

Native dependency builds require Python 3.11 (electron-builder's node-gyp 9 still uses distutils) and a platform C/C++ toolchain: Visual Studio C++ Build Tools on Windows, Xcode Command Line Tools on macOS, or build-essential on Debian/Ubuntu. If multiple Python versions are installed, set npm_config_python to the Python 3.11 executable before installing. On Debian/Ubuntu, also install the input-hook development libraries:

sudo apt-get install libx11-dev libxtst-dev libxrandr-dev libxt-dev

# Install dependencies
npm install

# Run in development (hot reload)
npm run dev

Useful scripts

Script	Description
npm run dev	Start the app with hot reload
npm run build	Type-check and build for production
npm run typecheck	Type-check main, preload, and renderer
npm run smoke	Run the shared (Node) + app (Electron) suites
npm run format	Format the codebase with Prettier
npm run build:win	Build a Windows installer
npm run build:mac	Build a macOS app
npm run build:linux	Build Linux packages (AppImage, deb)

Architecture notes

• Context isolation is enabled and nodeIntegration is off. The renderer talks to the main process only through the typed window.api bridge defined in src/preload.
• IPC handlers live in src/main/ipc. Add a new renderer-facing capability by registering an ipcMain.handle(...) there and exposing a matching method in the preload bridge.

Agent harness

The main process runs a single provider-agnostic agent loop; the renderer only streams events.

• Tool loop — src/main/harness/agent.ts owns the turn loop, the tool JSON-schemas (BASE_SCHEMAS), context trimming, and subagent dispatch. tools.ts is the authoritative runTool dispatcher. The user-facing catalog in src/shared/tools.ts mirrors it (the "Skills & Tools" page) and is guarded against drift by the shared smoke suite.
• Providers — the hand-rolled OpenAI/Copilot SSE path (with Copilot's short-lived-token refresh) lives in services/llm.ts; Anthropic + Google route through the Vercel AI SDK in services/aisdk.ts so every family gets tool-calling.
• Prompts & agents — tuned per-model prompts are selected in src/shared/prompt.ts and inlined from resources/prompts/*.txt via ?raw in prompt-text.ts. Plan/Build agents + subagents are defined in src/shared/agents.ts; an agent's tools allowlist and promptFile are what make Plan genuinely read-only.
• Context management — overflow is measured against the model's real limit (src/shared/context.ts); large tool outputs spill to disk with a preview pointer (); older turns are summarized by .

Remote Workspace

Take a running session to your phone. Remote Workspace (bottom-left CUSTOMIZE group in the sidebar) mints a room on roxy.gg, shows a QR + safe URL + PIN, and keeps the desktop as the authoritative host while a phone drives it as a thin client — your code and files never leave the machine; only the chat transcript and streamed agent events are relayed.

• Host service — main/services/remote.ts mints via POST https://roxy.gg/api/remote/sessions, holds the host token, and keeps a host WebSocket alive (auto-reconnect w/ backoff). On a guest hello it sends a transcript snapshot; on a guest prompt it persists the message and runs the turn, fanning every LlmEvent to the phone and the local renderer. Stop sharing revokes the room (host-token DELETE).
• One loop, no drift — both the local llm:start IPC path and a remote prompt call the shared main/services/session-turn.ts runSessionTurn, so a phone prompt behaves identically to a local one.
• IPC — remote:start | remote:stop | remote:status + a remote:state push (src/shared/ipc.ts), handlers in src/main/ipc, bridge in src/preload, types in src/shared/api.ts. The QR popup is renderer/src/components/RemoteWorkspaceDialog.tsx (offline QR via qrcode.react — nothing leaves the machine).
• Security — no login: a short-lived HMAC guest token rides in the URL fragment and the phone must also enter the PIN shown on the desktop. The room (and its tokens) is revoked on Stop, on too many wrong PINs, at the TTL, or shortly after the desktop disconnects. See the relay + protocol details in the roxy.gg README.

Translations

Roxy ships in English, 简体中文, हिन्दी, Español, العربية, Français, Português, Русский, Deutsch, and 日本語. Native speakers can help make the interface clearer and more natural. Issues and pull-request descriptions are welcome in any of these languages.

• English source strings live in src/renderer/src/locales/default.json.
• Translation catalogs live in src/renderer/src/locales.
• See the localization guide before editing UI copy or adding a language.
• Run npm run i18n to validate catalog structure, placeholders, and inline markup.

License

MIT © Roxy.

Roxy is a fork of opencode (also MIT) and retains opencode's copyright alongside Roxy's own. See LICENSE and resources/prompts/ATTRIBUTION.txt for details.