Boosted OS

Electron + React desktop application — an AI-powered terminal and research assistant for financial services professionals. SOC 2 Type II certified. ISO 27001 and ISO 42001 in progress.

Quick Start

# Clone with submodules
git clone --recurse-submodules git@github.com:GBI-Core/boosted-computer.git
cd boosted-computer

# If already cloned without submodules
git submodule update --init --recursive

# Install dependencies
npm install

# Run dev (renderer only)
npm run dev

# Run Electron app
npm run electron:dev

SSH → HTTPS Redirect (for CI)

The submodule URL uses HTTPS for CI compatibility. For local SSH access:

git config --global url."git@github.com:".insteOf "https://github.com/"

Project Structure

.agent-base/                     git submodule — shared Claude standards
.claude/
├── agents/
│   ├── base.md                → symlink to .agent-base (universal agent rules)
│   ├── review.md              → symlink to .agent-base (PR review agent)
│   ├── refactor.md            → symlink to .agent-base (refactor agent)
│   ├── test-coverage.md       → symlink to .agent-base (test coverage agent)
│   ├── pr-description.md      → symlink to .agent-base (PR title/description writer)
│   ├── pr-learnings.md        → symlink to .agent-base (PR pattern mining)
│   ├── review-overrides.md          repo-specific (Electron security, D-grade modules)
│   ├── refactor-overrides.md        repo-specific (fragile modules, IPC patterns)
│   ├── test-coverage-overrides.md   repo-specific (Vitest, testing-library, mock patterns)
│   ├── pr-description-overrides.md  repo-specific (risk flags, SOC 2 context)
│   └── pr-learnings-overrides.md    repo-specific (scan focus, grouping)
├── skills/                          # SKILL.md symlinked per-dir (not dir-level) so repos
│   │                                # can add local companion files alongside the symlink
│   ├── testing-principles/  → symlink to .agent-base
│   └── stacked-prs/        → symlink to .agent-base
├── settings.local.json              repo-specific Claude Code settings (gitignored)
docs/
├── architecture.md                  repo-specific — module boundaries, IPC channels
├── golden-principles.md             repo-specific — rules from real bugs, with PR citations
├── quality.md                       repo-specific — module quality grades (A–D)
├── runbook.md                       repo-specific — setup, env vars, common issues
├── security.md                      repo-specific — SOC 2 controls, data classification
└── decisions/                       ADR directory
electron/
├── main.js                          Main process (~172KB — GREP ONLY)
└── __tests__/                       Main process tests (node environment)
src/
├── components/                      UI components (layout, chat, cowork, inbox, settings)
├── stores/                          Zustand state management
├── hooks/                           Data fetching hooks
├── lib/                             API clients
├── utils/                           Pure utility functions
├── types/                           TypeScript interfaces
└── **/*.test.{ts,tsx}               Renderer tests (happy-dom environment)
CLAUDE.md                            Repo-specific engineering standards
BOOSTED_OS_CAPABILITIES.md           Feature catalog
DATA_SOURCES.md                      Data integration reference
COMPONENTS.md                        Design system reference

What Lives Where

Location	What goes here
.agent-base/	Git submodule — shared universal standards (security, coding, testing, CI/CD, agents, skills)
.claude/agents/*.md (symlinks)	Master agent definitions from agent-base, discovered by Claude Code
.claude/agents/*-overrides.md	Repo-specific additions to master agents (Electron security, D-grade modules, Vitest patterns)
.claude/skills/ (symlinks)	Universal skills from agent-base
docs/	Repo-specific guides (architecture, runbook, quality, golden-principles, security)
CLAUDE.md	Repo-specific config + @.agent-base/... references to shared standards

Updating Shared Standards

# Pull latest agent-base
cd .agent-base
git fetch origin
git checkout origin/main
cd ..
git add .agent-base
git commit -m "chore: bump agent-base to latest"

Commands

Command	Purpose
npm install	Install dependencies
npm run dev	Vite dev server (dev env)
npm run dev:prod	Vite dev server (prod env)
npm run electron:dev	Electron app (dev env)
npm run electron:prod	Electron app (prod env)
npm run build	TypeScript check + Vite production build
npm test	Run Vitest tests
npm run test:watch	Watch mode tests
npx tsc --noEmit	TypeScript check (run after every .tsx edit)
node --check electron/main.js	Syntax check main process
npm audit	Dependency vulnerability check

Custom Backend URL

Point the app at a custom backend (e.g. a test load balancer or local server):

# Vite only (renderer in browser)
make custom URL=http://your-backend-host

# Full Electron app
make electron-custom URL=http://your-backend-host

# Via npm (pass URL after --)
npm run dev:custom -- http://your-backend-host
npm run electron:custom -- http://your-backend-host

The URL should be the base host only (no /api suffix) — the scripts append /api and /api/llm/v1 automatically. A trailing slash is stripped.

If the backend is behind an AWS ELB whose TLS certificate doesn't match the ELB hostname (e.g. cert is for boosted.ai but you're hitting *.elb.amazonaws.com), use http:// instead of https:// — Chromium will reject the TLS mismatch and return HTML instead of JSON.