project-overview · diff
git:20260913.3f8e122 to git:20260919.db3e167
5 added, 7 removed. Audit A to A.
---
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/`.
+ Architecture notes live in `docs/architecture/`.
## 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
+ provider-neutral seam (`src/providers/`)
- **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)
+ ├── providers/ # provider-neutral seam (types, stream normalizer, fake)
├── 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)
+ ├── toolset/ # tool registry + tool schemas
├── 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
+ - **Settings hierarchy**: env (`SHELRA_*`) → 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).