Repository Guidelines

Use the fff MCP tools for all file search operations instead of default tools.

Project Structure & Module Organization

The UI is extracted from the desktop shell (CodeNomad-style): the desktop app is an Electron shell that loads its UI over HTTP from the local daemon, and @argos/ui is a standalone, reusable web package.

• apps/desktop/src/main/: Electron main process (the shell); presenters in presenter/ (Window/Tab/Thread/Mcp/Config/LLMProvider), eventbus.ts for app events. Windows load UI routes from the local daemon via lib/daemonUi.ts (resolveUiUrl).
• apps/desktop/src/preload/: Secure IPC bridge (contextIsolation on). Typed window.argos hybrid bridge via createBridge.ts → packages/client-sdk (WebSocket→daemon for routes, IPC→main for native-only routes).
• packages/ui/ (@argos/ui): the React 19 + TanStack Router frontend — built independently to dist/, served by the daemon. App code in src/ (components/, stores, pages, lib); secondary renderers settings/, floating/, splash/, browser-overlay/, web/. UI↔backend boundary in api/ (typed *Client classes over the ArgosBridge).
• packages/ui/shadcn/: shadcn/ui components shared across renderers.
• packages/shared-contracts/ (@argos/shared-contracts): Shared route contracts (Zod-validated), event contracts, the ArgosBridge interface, and the ARGOS_ROUTE_CATALOG.
• packages/shared/ (@argos/shared): Shared types and utilities (web-safe; no hard electron dependency).
• apps/daemon/ (@argos/daemon): Backend server (Bun) that serves the @argos/ui build over HTTP and exposes /api/v1/route + /api/v1/events.
• apps/desktop/test/ (test/main, test/renderer) and packages/ui: Vitest suites with setup files.
• scripts/: Build/signing/runtime installers, architecture guards, commit checks.
• Build outputs/assets: build/, resources/, out/, dist/.

Build, Test, and Development Commands

• Install: bun install + bun run installRuntime (first time).
• Dev: bun run dev (HMR). Inspect: bun run dev:inspect; Linux: bun run dev:linux.
• Preview: bun run start.
• Type check: bun run typecheck (covers @argos/desktop and @argos/ui; or typecheck:node / typecheck:web). Uses TypeScript 7 (tsc, the native Go-rewrite compiler).
• Lint: bun run lint (runs agent-cleanup-guard, architecture-guard, then oxlint).
• Format: bun run format (oxfmt). Check: bun run format:check.
• After completing a feature, always run bun run format and bun run lint.
• Test: bun test, test:main, test:renderer, test:coverage, test:watch, test:ui.
• Build: bun run build then build:win|mac|linux (add :x64|:arm64).

Turborepo + Vite + Electron Development

For agent-driven development with long-running Vite/Electron processes, follow these patterns:

Agent Dev Workflow

Never run dev servers in the foreground. Use background processes with log capture:

# Start the dev command in background, redirect logs
bun run dev > /tmp/desktop-dev.log 2>&1 &
echo $! > /tmp/desktop-dev.pid

# Wait for Vite readiness (poll the @argos/ui dev server)
for i in {1..60}; do
  curl -fsS http://127.0.0.1:5180 >/dev/null && break
  sleep 1
done

# Inspect logs (never assume a long-running command is stuck)
tail -n 200 /tmp/desktop-dev.log

Electron Readiness Checks

Two readiness states matter:

1. Vite renderer ready: Poll http://127.0.0.1:5180 (the @argos/ui dev server; it proxies /api → daemon)
2. Electron process launched: Check logs for errors

In dev, the desktop shell loads windows from the @argos/ui dev server when VITE_DEV_SERVER_URL is set; otherwise (and in packaged builds) it loads from the local daemon (http://127.0.0.1:<port>).

Stopping Dev Servers

kill $(cat /tmp/desktop-dev.pid)

Key Rules

• Never run dev servers in the foreground
• Never assume a long-running dev command is stuck; Vite/Electron tasks are persistent by design
• Use --filter with Turbo to avoid running all dev servers at once
• Check logs before assuming failure

Monorepo Packages

Renderer-Main Architecture (Typed Route/Client Pattern)

All renderer↔main communication uses the typed route/client pattern. Direct window.electron/window.api access and legacy presenter hooks (usePresenter/useLegacyPresenter) are removed; the architecture guard fails on reintroduction.

How it works

1. Route contracts (packages/shared-contracts/src/routes/*.routes.ts): Zod-validated input/output schemas per operation.
2. Bridge (packages/shared-contracts/src/bridge.ts): ArgosBridge interface with invoke(routeName, input) and on(eventName, listener).
3. Preload (apps/desktop/src/preload/createBridge.ts): Creates the window.argos hybrid bridge (IPC for native-only routes; WebSocket→daemon for the rest).
4. Typed Clients (packages/ui/api/*Client.ts): Domain-specific clients (e.g., ChatClient, ConfigClient, SessionClient) that wrap bridge.invoke().
5. Runtime wrappers (packages/ui/api/runtime.ts): Named helpers for clipboard, paths, external open — no window.api directly.

Adding a new renderer-main capability

1. Define route in packages/shared-contracts/src/routes/<domain>.routes.ts
2. Add to ARGOS_ROUTE_CATALOG in packages/shared-contracts/src/routes.ts
3. Register route handler in apps/desktop/src/main/routes/ (desktop) and/or apps/daemon/src/dispatch/ (daemon)
4. Create or extend packages/ui/api/<Domain>Client.ts
5. Use the client from UI business code

Renderer transport rules

• Business code (packages/ui/src/**, packages/ui/settings/**) reaches main/daemon only through typed clients (packages/ui/api/*Client.ts) and runtime wrappers (packages/ui/api/runtime.ts).
• window.electron, window.api, raw ipcRenderer channels, and legacy presenter hooks (usePresenter/useLegacyPresenter) are banned in renderer code; the architecture guard fails on reintroduction.

Architecture guards

bun run lint runs three guard scripts before oxlint:

• scripts/architecture-guard.mjs: Prevents direct window.electron/window.api/legacy-presenter access in renderer code, validates bridge register, tracks hot-path edges, and enforces the bun-file-io rule (Bun.file/Bun.write in Bun-runtime code; Bun.* forbidden in shared packages)
• scripts/agent-cleanup-guard.mjs: Prevents new code from importing legacy presenter directories or @argos/chat
• scripts/route-catalog-drift-guard.mjs: Keeps the ARGOS_ROUTE_CATALOG and registered route handlers in sync

Coding Style & Naming Conventions

• TypeScript + React 19 + TanStack Router; TanStack Store for state; Tailwind CSS + shadcn/ui for styles.
• Oxfmt: double quotes, semicolons, width 120, trailing commas. Run bun run format.
• OxLint for JS/TS; hooks run lint-staged and typecheck.
• Names: React components PascalCase (ChatInput.tsx); variables/functions camelCase; types/classes PascalCase; constants SCREAMING_SNAKE_CASE.

Testing Guidelines

• Daemon (apps/daemon): bun test (Bun's built-in runner). Imports come from bun:test, which exports a vitest-compatible vi object (no vi.hoisted/vi.stubEnv/vi.stubGlobal — see the bun-file-io skill for workarounds). Standalone e2e harnesses live as test/e2e-*.ts (not *.test.ts) so bun test does not discover them.
• Desktop + UI: Vitest (+ jsdom for renderer, node for main) and React Testing Library.
• Two separate desktop configs: vitest.config.ts (main, node env) and vitest.config.renderer.ts (renderer, jsdom env).
• Location mirrors source under test/main/** and test/renderer/** (desktop).
• Names: *.test.ts/*.test.tsx/*.spec.ts. Coverage: bun run test:coverage.
• Test aliases match Vite aliases: # → UI src, #api → UI api, @argos/shared → shared.

Path Aliases

Path aliases use the # prefix (Node subpath-imports style) for internal module references, and real workspace package names for cross-package references. This avoids colliding with npm scoped packages (@scope/name).

The #/ alias is context-sensitive: a custom Vite plugin (createPathAliasPlugin in each package's vite-plugins/path-alias.ts) resolves it to src/main/ for desktop main-process files and src/ for UI files. @argos/shared and @argos/shared-contracts are real workspace packages resolved via their exports maps (with tsconfig paths pointing at source for type checking).

Commit & Pull Request Guidelines

• Conventional commits enforced by hook: type(scope): subject ≤ 50 chars; types: feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip|release.
• Do not include AI co-authoring footers in commits.
• PRs: clear description, link issues (Closes #123), screenshots/GIFs for UI, pass lint/typecheck/tests. Keep changes focused.
• Default PR base is master (this fork has a single integration branch; there is no dev/main). Use gh pr create --base master for routine feature, bugfix, docs, test, and refactor branches. Releases are cut from short-lived release/<version> branches and landed on master following docs/release-flow.md.
• UI changes: include BEFORE/AFTER ASCII layout blocks to communicate structure.

Architecture Notes & Security

• Patterns: Presenter pattern in main; EventBus for inter-process events; typed route contracts as renderer-main boundary; two-layer LLM provider (Agent Loop + Provider); integrated MCP tools.
• File I/O: Bun-runtime code (apps/daemon/src, bun-run scripts/) uses Bun.file/Bun.write for reads/writes and node:fs for directory APIs. Electron main and shared packages/* use node:fs only — Bun.* is forbidden there. Enforced by the bun-file-io rule in bun run lint; see the bun-file-io skill.
• Secrets: use .env (see .env.example); never commit keys.
• Toolchains: Bun 1.4.0. Windows: enable Developer Mode for symlinks.
• Build: Vite 8 with Rolldown; vite-plugin-electron multi-env for main/preload/renderer.
• Runtimes: uv and ripgrep seeds in runtime/ — installed via bun run installRuntime. Node, uv, and ripgrep resolve at runtime through the daemon's managed toolchain service (see docs/features/managed-toolchains).

Specification-Driven Development

Follow the SDD methodology before changing code, tests, configuration, documentation, build scripts, or project structure. See docs/spec-driven-dev.md.

Pure release metadata work does not require SDD. Version bumps, CHANGELOG.md updates, release branch management, tags, and release PR preparation should follow docs/release-flow.md without creating docs/features/*release* folders.

Create one kebab-case folder per goal and keep spec.md, plan.md, and tasks.md together:

• docs/features/<goal>/ for new features, user-visible capabilities, integrations, and tools.
• docs/issues/<goal>/ for bug fixes, regressions, failing tests, CI failures, reliability issues, and prompt/runtime problems.
• docs/architecture/<goal>/ for refactors, migrations, dependency boundaries, shared contracts, runtime architecture, and cross-module design.

Resolve every [NEEDS CLARIFICATION] item before implementation. Move completed or stale goal folders to docs/archives/<goal>/; delete documents that only describe removed code and have no reusable decision record.

Core principles: specification-first, architectural consistency, minimal complexity, compatibility/migration awareness.