# Quickstart

> Open a project folder, store an API key, pick a harness or Auto Build, send the first message, and verify success via chat stream, terminal output, or status bar version.

- 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`
- `src/renderer/components/onboarding/ApiKeyOnboarding.tsx`
- `src/renderer/components/session/NewSessionDialog.tsx`
- `src/renderer/components/chat/InputArea.tsx`
- `src/main/services/settings.service.ts`
- `scripts/dev.sh`

---

---
title: "Quickstart"
description: "Open a project folder, store an API key, pick a harness or Auto Build, send the first message, and verify success via chat stream, terminal output, or status bar version."
---

Build is an Electron desktop IDE that opens local project folders as **dev-mode sessions** (`isDevMode: true`), persists credentials in `claudette-settings` via `electron-store`, and routes chat through harness-specific backends (Claude Agent SDK, Codex, Cursor, Gemini CLI, OpenCode) or **Auto Build** when the per-session model is `auto`. The shortest path from install to a verified agent turn: open a folder → satisfy onboarding (CLI harness and/or Anthropic API key) → create or activate a session → pick a model in `InputArea` → send a message → confirm streaming in chat, shell output in the terminal panel, and `G-BUILD v{version}` in the status bar.

## Prerequisites

| Requirement | Notes |
|-------------|-------|
| macOS build (recommended) | Signed release from [GitHub Releases](https://github.com/Parcha-ai/build/releases), or from-source with Node/npm (see [Installation](/installation)) |
| Project folder | Any directory; git is optional but enables branch UI and worktrees |
| Provider credentials | At least one of: installed harness CLI with login, or `sk-ant-…` Anthropic API key stored in settings |
| Harness CLIs (optional per harness) | Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode — detected at onboarding via `auth.checkProviders` |

<Note>
Local-folder mode does not require a GitHub account. `LoginScreen` offers **LOCAL FOLDER** alongside GitHub login; choosing a folder sets `isDevMode` and skips the GitHub gate in `App.tsx`.
</Note>

## End-to-end flow

```mermaid
sequenceDiagram
  participant User
  participant UI as Renderer (LoginScreen / NewSessionDialog)
  participant Main as Main (dev.ipc / settings)
  participant Store as session.store
  participant Agent as claude.service + harness

  User->>UI: Open local folder
  UI->>Main: dev.openLocalRepo → dev.createSession
  Main-->>UI: Session record (isDevMode)
  UI->>Store: addSession + setActiveSession
  User->>UI: Onboarding: CLI and/or setApiKey
  UI->>Main: settings.setApiKey (optional)
  User->>UI: InputArea: model + message + Enter
  UI->>Store: sendMessage(sessionId, text)
  Store->>Agent: claude.sendMessage(model, mode, thinking)
  Agent-->>Store: onStreamChunk / onStreamEnd
  Store-->>UI: Chat stream + terminal tool output
```

## Open a project folder

<Steps>
<Step title="Production app">
Download **Build** from [GitHub Releases](https://github.com/Parcha-ai/build/releases) and open the app. On first launch you see `LoginScreen` unless you already have a GitHub session or dev mode.

</Step>
<Step title="First launch — local folder (fastest)">
On `LoginScreen`, click **LOCAL FOLDER**. The native folder picker runs `dev.openLocalRepo`. Build creates a session with `dev.createSession({ name, repoPath, branch })`, adds it to the sidebar, activates it, and sets `isDevMode: true`. Non-git folders prompt to initialize git or **OPEN WITHOUT GIT**.

</Step>
<Step title="Additional sessions from the IDE">
After you are in the main UI, use the sidebar **+** control (`openNewSessionDialog`) → **NEW SESSION** → **Local Folder**. Same picker and config step (`CONFIGURE SESSION`) with optional git branch and worktree options.

</Step>
<Step title="From-source development">
Run `./scripts/dev.sh` (not `npm run start` directly). The script assigns `DEV_INSTANCE_NAME` (e.g. `bouncy-penguin`), uses webpack port **9001**, and isolates user data at `/tmp/grep-build-dev` so production settings under `~/Library/Application Support/Build` are not overwritten. Confirm dev mode in the status bar: `G-BUILD v…` plus `[DEV_INSTANCE_NAME]` in amber.

</Step>
</Steps>

<Tip>
`NewSessionDialog` also supports GitHub clone, Teleport, SSH remote, and OpenClaw gateway sources. For a minimal quickstart, stay on **Local Folder**.
</Tip>

## Store API keys and provider readiness

On startup, `App.tsx` calls `checkApiKey()` (reads `anthropicApiKey` from settings). If no key and `onboardingSkipped` is not set, **Welcome to Build** (`ApiKeyOnboarding`) opens.

| Onboarding signal | Meaning |
|-------------------|---------|
| Green check on a harness row | `auth.checkProviders` reports `loggedIn: true` (CLI install + auth) |
| Amber / install or login command | CLI missing or sign-in required — copy commands from the row |
| Anthropic API key field | Required only when **no** harness is ready; optional when any harness is logged in |
| **Continue to Build** | Sets `onboardingSkipped: true` or saves `sk-ant-…` via `settings.setApiKey` |

<ParamField body="anthropicApiKey" type="string">
Stored in `claudette-settings` (top-level key, not inside `settings`). Onboarding validates prefix `sk-ant-` before save.
</ParamField>

<Warning>
Build does not proxy API traffic. Keys and CLI credentials stay on your machine (BYOC/BYOK). Use **Advanced Settings →** in onboarding for OpenAI, Google, Foundry, Cursor, DeepSeek, and custom proxy models.
</Warning>

## Pick a harness or Auto Build

The chat input footer hosts the **model picker** (`InputArea`). Models load from `claude.getModels()` into `session.store` `availableModels`.

| Picker entry | Model id | Behavior |
|--------------|----------|----------|
| **Auto Build** | `auto` | Default when no per-session override; orchestrates plan/build/verify/refine tiers and shows `AutoRouteBadge` while streaming |
| Claude | `claude-opus-4-8`, `claude-sonnet-4-6`, … | Anthropic models via Claude Code harness |
| Codex | `codex:gpt-5.4`, `codex:o3`, … | OpenAI Codex harness |
| Cursor | `cursor:…` | Cursor Agent harness |
| Gemini CLI | `gemini:…` | Google Gemini harness |
| OpenCode / custom | `opencode:…`, `custom:…` | Community or proxy-defined models |

**Default for new turns:** `selectedModel[sessionId] || 'auto'`.

**Permission mode** (prompt glyph next to input): cycles `auto`, `acceptEdits` (`>>`), `default` / ASK (`>`), `bypassPermissions`, `plan`, `dontAsk`. Default permission mode is `default` (approval required).

**Effort / thinking:** defaults to `high` when unset; adjust via the effort control in the input chrome.

To pin a specific harness model instead of Auto Build, open the picker → choose harness group → select a model. Recent picks persist in `localStorage` key `grep-recent-models`.

## Send the first message

1. Select the session in the sidebar so `activeSessionId` is set.
2. Focus the chat input (`InputArea`).
3. Type a concrete task (for example: “List the top-level directories and summarize `package.json` scripts”).
4. Press **Enter** to send (or **Cmd+Enter** / **Ctrl+Enter** to force-send during an active stream).

`handleSubmit` → `session.store.sendMessage` → `electronAPI.claude.sendMessage` with:

- `model` — `auto` or explicit id
- `permissionMode` — normalized per model
- `thinkingMode` — effort level (default `high`)
- Optional attachments (images, `@` file mentions)

If a stream is already running, new text is **queued** in the main-process queue and shown in `MessageQueuePanel` until the prior turn finishes.

## Verify success

Confirm the first agent turn with at least one of these signals:

### Chat stream

| Signal | Expected |
|--------|----------|
| `isStreaming[sessionId]` | `true` while the harness runs |
| Assistant content | Chunks arrive via `onStreamChunk`; final message on `onStreamEnd` |
| Auto Build | Purple **AUTO** label or `AutoRouteBadge` with tier/domain; tooltip shows resolved harness + model |
| Tool cards | Read, Bash, Edit, etc. appear in the thread |

### Terminal output

Open the **terminal** panel for the active session. Agent shell commands from tool use should appear in the integrated PTY (xterm + `node-pty`). Long-running setup during session create also streams to `NewSessionDialog` progress log (`dev.onSetupProgress` / `ssh.onSetupProgress`).

### Status bar version

Bottom-right status bar (`StatusBar.tsx`):

| Display | Meaning |
|---------|---------|
| `G-BUILD v0.5.27` (example) | `app.getVersion()` from packaged `package.json` — confirms you are on the build you expect |
| `[fuzzy-penguin]` (dev only) | `DEV_INSTANCE_NAME` from `./scripts/dev.sh` — distinguishes dev from production |
| Branch name | Git watcher active for the session worktree |
| `PORT:` | Shown when `session.status === 'running'` (container/dev server sessions) |

<Check>
Quickstart success checklist: onboarding harness or API key saved → session active in sidebar → model shows **AUTO** or chosen harness → first message streams in chat → terminal shows command activity (if tools run) → status bar version matches your install.
</Check>

## Persistence and paths

| Store file | Purpose |
|------------|---------|
| `claudette-settings.json` | `settings.*`, `anthropicApiKey`, `onboardingSkipped`, provider keys |
| `claudette-sessions.json` | Session list and metadata |
| Production userData | `~/Library/Application Support/Build` (also legacy `G-Build`, `Grep Build`) |
| Dev userData | `/tmp/grep-build-dev` when using `./scripts/dev.sh` |

Sessions created from a local folder are flagged `isDevMode: true` (no Docker container required for the default quickstart path).

## Common blockers

<AccordionGroup>
<Accordion title="Onboarding will not dismiss">
Install or log in to at least one harness CLI, **or** enter a valid `sk-ant-…` key, **or** click **Continue to Build** (sets `onboardingSkipped`). Open **Advanced Settings** for non-Anthropic keys.
</Accordion>
<Accordion title="Send does nothing">
Confirm `activeSessionId` is set, input is not `disabled`, and onboarding closed. Check main-process logs: production `~/Library/Application Support/Build/main.log`; dev uses console from `./scripts/dev.sh`.
</Accordion>
<Accordion title="Auto Build stays on AUTO with no stream">
Ensure a harness backing Auto Build is configured (Claude API key and/or logged-in CLI). See [Auto Build routing](/auto-build-routing) and [Harnesses and models](/harnesses-and-models).
</Accordion>
<Accordion title="Wrong build version in status bar">
Production should match the downloaded release tag. Dev builds show the repo `package.json` version plus `[DEV_INSTANCE_NAME]` — restart with `./scripts/dev.sh` after pulling changes.
</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
macOS download, from-source setup, and dev vs production user data separation.
</Card>
<Card title="Overview" href="/overview">
Product surfaces: sessions, harness picker, Auto Build, and BYOC/BYOK assumptions.
</Card>
<Card title="Configure providers" href="/configure-providers">
Full API key and provider matrix beyond onboarding.
</Card>
<Card title="Harnesses and models" href="/harnesses-and-models">
Harness ids, model strings, and capability limits.
</Card>
<Card title="Sessions and workspaces" href="/sessions-and-workspaces">
Session schema, dev vs Docker vs SSH, and `claudette-sessions` persistence.
</Card>
<Card title="Auto Build routing" href="/auto-build-routing">
Plan/build/verify/refine tiers when model id is `auto`.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Port conflicts, PATH/node in packaged apps, and log locations.
</Card>
</CardGroup>