# Overview

> What Build exposes as a desktop IDE, primary entry points (sessions, harness picker, Auto Build), BYOC/BYOK assumptions, and the shortest path from install to first agent turn.

- Repository: Parcha-ai/build
- GitHub: https://github.com/Parcha-ai/build
- Human docs: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b
- Complete Markdown: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `src/main/index.ts`
- `src/renderer/App.tsx`
- `src/shared/types/index.ts`
- `CLAUDE.md`

---

---
title: "Overview"
description: "What Build exposes as a desktop IDE, primary entry points (sessions, harness picker, Auto Build), BYOC/BYOK assumptions, and the shortest path from install to first agent turn."
---

Build (`productName`: **Build**, npm package `build`, current version **0.5.27**) is an Electron 38 desktop IDE that orchestrates external coding-agent harnesses (Claude Code, Cursor Agent, Codex, Gemini CLI, OpenCode, and custom proxy models) inside one window. The main process (`src/main/`) owns services, IPC, and subprocess spawning; the React renderer (`src/renderer/`) drives chat, sessions, terminal, browser preview, git, and settings through `window.electronAPI` exposed from `preload.ts` with `contextIsolation: true`.

## Desktop surfaces

| Surface | Location | Role |
|---------|----------|------|
| Session sidebar | `Sidebar` + `session.store` | List, create, switch, and star sessions bound to `repoPath` / `worktreePath` |
| Chat + input | `ChatContainer` / `InputArea` | Send prompts, stream harness output, permission/plan dialogs |
| Model / harness picker | `InputArea` two-level menu | Select `auto` (Auto Build) or a prefixed model id per harness |
| Terminal | `TerminalContainer` | PTY via `node-pty`; mirrors agent shell activity |
| Browser preview | `BrowserPreview` | In-window `webview`, CDP proxy, DOM inspector |
| Git | `GitExplorer` | Status, diff, commit, push/pull per session worktree |
| Monaco editor | `EditorPanel` | Multi-tab file editing with `monaco-asset://` protocol |
| Settings | `SettingsDialog` | API keys, Auto Build tiers, QMD, MCP, extensions |
| Status bar | `StatusBar` | Clock, session state, packaged **version** string |
| Onboarding | `ApiKeyOnboarding` | Provider CLI scan + optional Anthropic API key |

`MainContent` composes chat with optional terminal, browser, git, plan, extensions, command center, and agent view panels. With no active session, `EmptyState` prompts sidebar selection or **⌘N** for a new session.

## Process model

```mermaid
flowchart TB
  subgraph renderer["Renderer (React + Zustand)"]
    App["App.tsx"]
    Stores["session / ui / auth stores"]
    UI["Sidebar · Chat · Terminal · Browser · Git"]
    App --> Stores --> UI
  end

  subgraph bridge["IPC bridge"]
    Preload["preload.ts → electronAPI"]
    Channels["shared/constants/channels.ts"]
    Preload --> Channels
  end

  subgraph main["Main process (Node)"]
    Index["index.ts"]
    IPC["ipc/*.ipc.ts handlers"]
    Svc["services/*.service.ts"]
    Index --> IPC --> Svc
  end

  subgraph external["External (BYOC)"]
    Harnesses["Claude / Codex / Cursor / Gemini / OpenCode CLIs"]
    Providers["Anthropic · OpenAI · Google · proxies"]
    Harnesses --> Providers
  end

  UI <-->|invoke + events| Preload
  Preload <-->|ipcMain| IPC
  Svc --> Harnesses
```

On `app.ready`, `index.ts` runs `migrateFromGrepBuild()`, `registerIPCHandlers()` (auth, session, git, terminal, claude, settings, browser, SSH, QMD, MCP, codex, queue, and others), starts `cdpProxyService`, and opens the primary `BrowserWindow`. Packaged macOS builds append logs to `userData/main.log`; dev builds set `GREP_DEV_USER_DATA` so settings and sessions do not overwrite production data.

## Sessions

A **session** is the unit of work: one project folder (or remote target) with its own branch/worktree, chat transcript, model selection, and optional SSH or OpenClaw gateway config.

<ParamField body="id" type="string" required>Stable session identifier</ParamField>
<ParamField body="repoPath" type="string" required>User-selected project root</ParamField>
<ParamField body="worktreePath" type="string" required>Git worktree used for edits and terminal cwd</ParamField>
<ParamField body="status" type="SessionStatus" required>Lifecycle: `creating` → `starting` → `setup` → `running` (or `stopping` / `stopped` / `error`)</ParamField>
<ParamField body="model" type="string">Per-session model id (e.g. `claude-sonnet-4-6`, `codex:gpt-5.4`, `auto`)</ParamField>

Sessions persist in electron-store (`claudette-sessions`; dev may use a copied file under `/tmp/grep-build-dev`). After auth/dev gate, `ElectronApp` calls `loadSessions()`, subscribes to IPC session/claude/codex streams, and may `checkAndAutoResume()` interrupted work.

Session kinds implied by `Session` fields:

- **Local dev** — `isDevMode: true`, no Docker container
- **Docker** — `containerId` allocated with port map (`web`, `api`, `debug`)
- **SSH remote** — `sshConfig` with host, key, `remoteWorkdir`, optional worktree script
- **OpenClaw** — `openclawConfig.gatewayUrl` + bearer token

Forks, teleports, and conversation forks are tracked via `parentSessionId`, `forkName`, `teleportedFrom`, and related fields.

## Harness picker

Build does not embed model weights; it **drives installed harness CLIs** and maps UI model strings to harness ids:

| Harness id | Model id prefix | UI group label (picker) |
|------------|-----------------|-------------------------|
| `claude` | (none) | Claude |
| `codex` | `codex:` | Codex |
| `cursor` | `cursor:` | Cursor |
| `gemini` | `gemini:` | Gemini CLI |
| `opencode` | `opencode:` | DeepSeek (OpenCode BYO endpoint) |
| `custom` | `custom:` | Custom (settings `customModels` proxy) |

`harnessFromModel()` in `session.store.ts` performs prefix resolution. Permission modes differ for Codex vs Claude harnesses (`getSupportedPermissionModes`).

The picker is a **two-level menu**: harness list (left) → models for that harness (right), plus **Recent** quick picks in `localStorage` (`grep-recent-models`). Hot-swapping mid-session updates `selectedModel[sessionId]` without clearing files or branch context.

Default Anthropic-facing models are listed in `claude.service.ts` (`getModels`), including Sonnet/Opus/Haiku ids and Codex-prefixed entries; Foundry and `customModels` append at runtime.

## Auto Build

Selecting model id **`auto`** enables **Auto Build**: tiered routing across `plan`, `build`, `verify`, and `refine` (`TaskTier` in shared types). The router produces a `RoutingDecision` (tier, domain, `resolvedModel`, `resolvedHarness`, confidence, `method: 'heuristic' | 'controller'`, optional `orchestration` / `missionControl`).

<Info>
Auto Build’s meta-harness controller (`flue-meta-router.service.ts`) returns routing decisions only; it does not execute shell, read, or write in the sandbox—execution delegates to the resolved harness.
</Info>

Configure fixed tier → harness/model mappings under Settings → **Auto Build** (`autoRouterConfig` on `AppSettings`: `planModel`, `buildModel`, `verifyModel`, `refineModel`, categories, `costAware`, workflow/speed/verification policies). While `auto` is active, `AutoRouteBadge` and chat copy surface the resolved scope (e.g. `plan:frontend`).

## BYOC / BYOK assumptions

<Check>
**Bring your own credentials.** API keys and CLI logins are stored locally (electron-store / secure key IPC), not on a Build-hosted inference proxy for normal chat turns.
</Check>

| Expectation | Behavior in repo |
|-------------|------------------|
| No Build account for local folders | README: open a project folder without signing in |
| Anthropic key | `claudette-settings` → `anthropicApiKey`; onboarding can set via `settings.setApiKey` |
| Other providers | `googleApiKey`, `foundryApiKey`, `cursorApiKey`, OpenAI/Codex via CLI login, `customModels` for OpenAI-compatible proxies |
| Harness presence | Onboarding runs `auth.checkProviders()` for Claude, Codex, Cursor, Gemini, OpenCode install/login state |
| Optional analytics | `posthogApiKey` / `posthogHost` in settings; PostHog client only active when env/key configured |
| GitHub OAuth | `LoginScreen` + `auth.store` exist; current `checkAuth()` sets `isDevMode: true` and skips the gate so local workflow proceeds immediately |

Provider calls are issued from the main process to **your** CLIs and provider endpoints. Voice (ElevenLabs / OpenAI Realtime) and QMD embeddings are likewise opt-in with separate keys.

## Renderer bootstrap

`App.tsx` root routing:

1. Non-Electron → `PreviewMode` (UI only, no IPC)
2. `?mode=browser` → `BrowserOnlyApp` (command-center browser pop-out)
3. Else → `ElectronApp`

`ElectronApp` initialization sequence:

1. `initializeTTSListeners()` / audio settings
2. `auth.checkAuth()` (dev gate)
3. `checkApiKey()` → open `ApiKeyOnboarding` if missing and not `onboardingSkipped`
4. `loadSessions()` + IPC subscriptions when `user || isDevMode`

## Shortest path: install → first agent turn

<Steps>
<Step title="Install Build">
<Tabs>
<Tab title="macOS release">
Download the signed `.dmg` from [GitHub Releases](https://github.com/Parcha-ai/build/releases) and move **Build** to Applications.
</Tab>
<Tab title="From source">
```bash
git clone https://github.com/Parcha-ai/build.git
cd build
npm install
./scripts/dev.sh
```
Note the printed **DEV INSTANCE** name (e.g. `bouncy-penguin`) in the terminal; dev uses port **9001** and `GREP_DEV_USER_DATA=/tmp/grep-build-dev`.
</Tab>
</Tabs>
</Step>

<Step title="Open a project">
Launch Build. Create or select a session (**⌘N** or sidebar) and choose a local folder (`repoPath`). Wait for `status: running` (and setup script completion for container/SSH sessions).
</Step>

<Step title="Configure credentials">
Complete **ApiKeyOnboarding** (Anthropic API key and/or install+log in harness CLIs), or open Settings → providers. Skip is allowed if at least one harness is already logged in via CLI.
</Step>

<Step title="Pick harness or Auto Build">
In the chat input model menu, choose **Auto Build** (`auto`) or a specific harness model (e.g. `claude-sonnet-4-6`, `codex:gpt-5.4`). Set permission mode if prompted.
</Step>

<Step title="Send the first message">
Type a prompt and press Enter. Verify: streaming assistant content in chat, tool/terminal activity in the terminal panel, and no session `error` status. Packaged builds show the new version in the status bar after upgrades.
</Step>
</Steps>

<Warning>
Use `./scripts/dev.sh` for development—not bare `npm run start`—so QMD setup, port cleanup, dev `userData` separation, and instance naming run correctly.
</Warning>

## Persistence and environments

| Store file | Contents |
|------------|----------|
| `claudette-settings.json` | `AppSettings`, `anthropicApiKey`, provider keys, `autoRouterConfig`, theme, QMD flags |
| `claudette-sessions.json` | Map of `Session` records |
| `claudette-mcp-servers.json` | MCP server definitions |
| `claudette-identity.json` | Anonymous device id for analytics |

Production macOS path: `~/Library/Application Support/Build` (migrated from legacy **G-Build** / **Grep Build** names). Dev copies settings once into `/tmp/grep-build-dev` without symlinks to avoid corrupting prod on flush.

Remote debugging: CDP port **9222** (production) or **9223** (development / `DEV_INSTANCE_NAME`), overridable via `ELECTRON_CDP_PORT`.

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
macOS release, prerequisites, npm install, and dev vs production user data.
</Card>
<Card title="Quickstart" href="/quickstart">
Folder open, API key, first message, and verification signals.
</Card>
<Card title="Electron architecture" href="/electron-architecture">
Main vs renderer, services layout, webpack, protocols, CDP.
</Card>
<Card title="Harnesses and models" href="/harnesses-and-models">
Harness ids, model prefixes, permission modes, capability limits.
</Card>
<Card title="Sessions and workspaces" href="/sessions-and-workspaces">
Schema, lifecycle, SSH/Docker/OpenClaw, worktrees, persistence.
</Card>
<Card title="Auto Build routing" href="/auto-build-routing">
Plan/build/verify/refine tiers, controller routing, orchestration.
</Card>
<Card title="Configure providers" href="/configure-providers">
API keys, CLI detection, secure storage.
</Card>
</CardGroup>