project-overview git:20260913.3f8e122A

Immutable. This exact content never changes and is served at /api/v1/blob/1f73fb7f5cdcb486.

---
description: Project overview and architecture reference
globs: "**/*"
alwaysApply: true
---

# ShelraCode — Project Overview

`shelra` (product name **ShelraCode**) is a **cloud-first AI coding agent** for
the terminal. It defaults to OpenRouter Free when configured; a small reviewed
GGUF model through an app-managed `llama.cpp` server remains available through
the explicit `--local` mode.
It began as the Grok CLI and is mid-migration to this architecture — see
`docs/migration/`.

## Tech Stack

- **Language**: TypeScript (ES2022, ESNext modules, `strict: true`)
- **Runtime**: Bun (required at build AND runtime — the bundle imports `bun:sqlite`)
- **UI**: React with [OpenTUI](https://github.com/anomalyco/opentui)
  (`@opentui/react`, `jsxImportSource` set in `tsconfig.json` — no `import React`)
- **Build**: `bun run scripts/build.ts` (bundle + declarations + `dist/shelra.exe`)
- **Lint/format**: Biome (`biome.json`)
- **Tests**: Vitest
- **Model layer**: Vercel AI SDK (`ai`, `@ai-sdk/openai-compatible`) behind a
  provider-neutral seam (`src/providers/`); `@ai-sdk/xai` remains only as an
  isolated migration-compat surface
- **Storage**: local SQLite via `bun:sqlite` (`src/storage/`)
- **Tools**: bash, file read/write/edit, grep, LSP, MCP, schedules, computer-use

## Architecture (high level)

```
src/
├── index.ts          # CLI entry (Commander) + OpenTUI bootstrap + startup state machine
├── startup/          # explicit local-mode startup orchestrator + state machine
├── agent/            # agent loop, kernel, compaction, delegations
├── providers/        # provider-neutral seam (types, stream normalizer, fake, xai-compat)
├── runtimes/         # managed llama.cpp lifecycle, discovery, local OpenAI-compatible adapter
├── models/           # Hugging Face GGUF download/catalog + recommendation
├── router/           # cloud model routing + local privacy/capability routing
├── context/          # bounded repository-context compiler
├── hardware/         # host hardware profile + model-fit scoring
├── security/         # workspace path guard, sandboxing
├── grok/             # tool schemas + legacy Grok client (compat)
├── tools/            # bash, file, grep, schedule, computer
├── ui/               # OpenTUI React shell (app.tsx, startup.tsx, modals)
├── storage/          # bun:sqlite sessions/transcripts/usage
├── mcp/  lsp/         # MCP + LSP integrations
├── telegram/         # Telegram remote-control bridge
├── verify/           # host-owned verification / completion gate
└── product/identity.ts  # product/name/env-var/config-path constants
```

## Key Patterns

- **Cloud-first**: normal startup discovers OpenRouter models and gates cloud
  chat behind catalog/capability policy. `--local` activates
  `runStartup` (`src/startup/orchestrator.ts`) for managed local inference.
- **Research-first**: every agent turn performs bounded web research and
  combines repository evidence with official documentation or primary sources.
- **Provider seam**: no AI-SDK or vendor object crosses the agent/UI boundary —
  enforced by `src/providers/architecture.test.ts`.
- **Settings hierarchy**: env (`SHELRA_*`, legacy `GROK_*`) → user
  (`~/.shelra/user-settings.json`) → project (`.shelra/settings.json`).
- **Custom instructions**: `AGENTS.md` discovered from git root through cwd.
- **ESM only** (`"type": "module"`); imports omit extensions (`moduleResolution: Bundler`).

## CI/CD

- **typecheck.yml**: `bun run format` → `bun run lint` → `bun run typecheck` →
  `bun run build:binary` on push/PR to `main`/`develop`.
- **security.yml**: `bun pm untrusted` + TruffleHog secret scan (weekly + PR).