Run the commands in this guide from the repository root. Back to the README.
- Rust toolchain pinned in rust-toolchain.toml
- Node.js 22.13 or newer
- Bun 1.3.5, pinned in package.json
- Platform toolchain for the local Tauri target
- cargo-binstall, used by the pinned Tauri CLI installer
- Optional authenticated local AI CLIs:
claude,codex, orcopilot
Install frontend dependencies:
bun install --cwd frontend --frozen-lockfile
bun run tauri:cli:installFull verification also requires cargo-audit. Install the version pinned in tool-versions.json:
cargo binstall cargo-audit --locked --version "=$(node -p 'require("./scripts/tool-versions.json").cargoAudit')" --no-confirmFrontend checks and editor language features use tsc-rs, pinned to 0.8.0. Both the UI and Vite configuration are checked before production builds. Vite bundles the frontend. Oxlint 1.89.0 and its Go-based oxlint-tsgolint 7.0.2004 engine provide typed linting. The separate Microsoft compiler SDK is not installed.
The npm package version identifies the Rust release. Its TypeScript language version, reported by tsc-rs --version, is 7.1.0-dev. Builds and the editor use the same native executable. The Microsoft TypeScript 7 extension remains the editor client.
On Linux x64, macOS Apple Silicon, or macOS Intel, a frozen frontend install prepares frontend/node_modules/.tsc-rs-sdk as a relative link to the installed host package's lib directory. Installation does not edit workspace or user settings. If lifecycle scripts were disabled or the link is missing, run the repair command explicitly:
bun run --cwd frontend sdk:prepareThe helper repairs only recognized helper links. It refuses foreign links, files, or directories at the reserved path. The tooling guard reports missing or stale setup without repairing it.
For VS Code, open the repository root or frontend directly and install the recommended TypeScript 7 (TypeScriptTeam.native-preview) and Oxc (oxc.oxc-vscode) extensions. Trust your checkout through Manage Workspace Trust, then open a TypeScript file and click Allow when TypeScript 7 offers the configured SDK. Its notification can label this SDK local. If hidden, run Notifications: Show Notifications to find it.
Root settings select ./frontend/node_modules/.tsc-rs-sdk. Frontend settings select ./node_modules/.tsc-rs-sdk. In the TypeScript 7 output, check that Resolved to identifies the checkout's @tsc-rs/<host>/lib/tsc executable. A Bun installation can place that package under node_modules/.bun. Check Oxc (Lint) output for the local Oxlint launcher and version 1.89.0. Both layouts retain per-file project discovery for UI sources and vite.config.ts. Compiler diagnostics show ts; lint diagnostics show oxc. Formatting and save actions are unchanged.
Run the tooling guard to inspect the entire lock and installed dependency graph, verify lint coverage, and exercise deliberate lint violations. Run the compiler probe to verify that valid TypeScript and TSX pass and deliberate type errors stop builds:
bun run frontend:tooling:check
bun run frontend:compiler:checkThe probe checks the installed package version and removes its temporary fixtures. Both verification commands and CI run the probe. Read the migration findings for compatibility evidence and scope.
Read the Rust SDK validation record for editor coverage, the pinned shutdown qualification, and current limits.
For continuous native checks on Linux or macOS, run bun run frontend:typecheck:watch. To run both checkers with Vite, run bun run frontend:dev:checked. From frontend, use bun run typecheck:watch or bun run dev:checked. Both project watchers show type errors and recover after edits. The checked session uses Vite's configured port, defaulting to 5173, and fails if it is occupied.
These opt-in watchers add resident memory. On the probe host, median additional RSS was about 296 to 349 MiB. This watch measurement is conditional on that host and workload, rather than a universal memory cost.
For these development watchers, Ctrl-C stops every owned process group. A second interrupt skips the shutdown grace period. A failed or unexpectedly terminated child stops the session without restarting it. Process-group cleanup does not cover Ctrl-Z, killing the supervisor with SIGKILL, or descendants that create independent sessions. Ordinary bun run --cwd frontend dev runs Vite alone. Production builds and CI use their existing one-shot checks.
Run the desktop app in development mode:
bun run devBuild the Rust workspace and frontend:
bun run buildChoose one gate for the current source. Use bun run verify:fast during the edit loop:
bun run verify:fastThis checks source isolation, native tooling and compiler contracts, frontend checks and tests, command contracts, Rust formatting, and clippy. It omits dependency audits, Rust tests, a full build, smoke, and built-app E2E.
Before handing off a completed change, use the full local gate:
bun run verifyThis adds audits, release-script and package metadata tests, a production build and isolation check, bindings, Rust tests and build, and non-GUI smoke. It omits built-app E2E, startup launches, workflow lint and online audit, platform matrix, and installed-package checks. CI supplies those applicable obligations. Do not run both gates and every constituent command against unchanged source. Use focused tests while editing and the full gate when its broader proof is needed. See the check inventory for the exact scope.
Run the non-GUI smoke harness:
bun run smokeRun the built desktop application against deterministic end-to-end workflows. On Linux, the native-close workflow requires an isolated X11 display:
GDK_BACKEND=x11 xvfb-run -a bun run e2eOn macOS, run bun run e2e. Both desktop defaults include first use, the
read-only example, Help, ordinary creation, Copy, and the Session sheet. Each default workflow has
isolated app data and artifacts. The model evidence and selection restart pairs
intentionally share only their own state on Linux. Select one maintained spec
with QA_SCRIBE_E2E_SPEC=first-use.e2e.mjs bun run e2e when working on first use.
Keep QA_SCRIBE_AC3_RECORD unset for normal checks. CI disables this optional
Linux recorder even when inherited from the environment.
If a command fails, read artifacts/e2e/latest-run.json and the per-invocation
logs. Startup failures retain artifacts/startup/startup-report.json, including
earlier samples. A timeout is distinct from an application assertion or process
exit. These wrappers bound their direct children and do not prove descendant
cleanup. Keep isolated native runs serialized with other users of the target.
Verify the minimal Ask AI interface with its six synthetic native journeys:
QA_SCRIBE_E2E_SPEC=ask-ai-conversation-isolation.e2e.mjs bun run e2eThe fixture exercises fresh record launch, image-backed refinement with a single saved Update,
reclick and close, exact unfinished recovery, typed Jira follow-ups, and short-window
keyboard access. It uses the maintained embedded WebView driver, DOM keyboard events,
and the operating-system clipboard. It does not call real providers or Jira. The
separate ask-ai-conversation-routing.e2e.mjs initial/restart pair retains process
recovery coverage. Completed record conversations have no History or Continue UI. The older
ask-ai-refinement.e2e.mjs staging suite is retired; these journeys cover the
current single-update interaction.
Run the reproducible large-data startup measurement (five launches by default):
bun run startup:benchmarkValidate package metadata JSON:
bun run package:check