Desktop App Guide
Installation
Download from vipr.dev/download. Available for macOS, Windows, and Linux.
Getting started
- Launch the app and sign in
- Open a local Git repository
- Vipr runs an initial analysis and populates the dashboard
Key features
- 40+ dashboard widgets covering complexity, anti-patterns, architecture, and trends
- Historical git backfill to analyze how code quality changed over time — offered during the initial assessment, and available later from the Analysis Status menu (top right) under Historical Analysis
- A/B snapshot comparison to compare two points in time
- Local AI inference for AI-assisted remediation (Pro)
- SQLite-backed storage: all data stays on your machine
Deep analysis providers
Beside the per-file analysis, Desktop runs project-wide passes in the background and merges their findings into the Anti-Patterns page (each card shows the provider's status badge; a pass that does not apply to the repository shows as Not applicable with the reason):
| Provider | What it reports | Needs |
|---|---|---|
| Dead code (knip) | Unused files, exports, and dependencies | — |
| Duplicate code (jscpd) | Copy-pasted blocks across files | — |
| tsconfig posture | Strictness flags that are off at the root, and packages whose tsconfig is weaker than the root | a tsconfig.json |
| Boundary violations | Imports that reach into another workspace package's internals instead of its entry point | a pnpm/npm workspace with more than one package |
| Type-aware TypeScript | Checker-backed findings the per-file lane cannot see (silent any flow, unnecessary non-null assertions, dead union arms, nominal constructor dependencies, hidden collaborators, fat interfaces with narrow clients) |
a tsconfig.json; skipped above 3,000 files |
| Compile trace | The files driving type-check time, from a tsc --generateTrace directory |
typescript.traceDir in vipr.config.json (opt-in) |
The type-aware pass runs in its own helper process, so the app stays responsive while its badge reads running; its findings are keyed to the whole project (tsconfig + file set) and refresh when any TypeScript file or tsconfig changes.
Project configuration
Desktop loads vipr.config.json from the opened repository using the shared config loader used by
the CLI and VS Code extension. The resolved config and config hash are stored with analysis runs and
snapshots.
When vipr.config.json changes after initial analysis, Desktop keeps the previous results visible
and shows a config-changed state while it clears in-memory caches and queues reanalysis. Current
views update after fresh config-aware results are stored; historical views remain tied to the config
hash used when those runs were produced.
Desktop imports config-managed budgets as read-only deterministic budget rows and preserves
budgets created in the app. Budget exceptions remain visible as suppressed violations with current
value, threshold, reason, and expiry.
Notifications and sounds
Notifications appear as a toast in the bottom-right corner and collect in the notifications panel behind the bell icon in the title bar, so nothing is lost if a toast dismisses before you read it.
Vipr also plays a short sound for the things worth hearing: a confirmation chime when a dialog asks you to confirm or choose, an error tone for anything that fails visibly, a notification tone for general activity, a success tone when something completes (including a deep analysis run), and Vega's hiss when the welcome screen appears.
Control all of it under Settings → System → Notifications:
| Setting | What it does |
|---|---|
| Application sounds | Master switch for every sound listed above |
| Analysis / Export / MCP Server / Repository notifications | Which categories of notification you see at all |
Your operating system wins. On macOS, if System Settings → Sound → "Play user interface sound effects" is off, Vipr stays silent regardless of the in-app switch, and the setting's description says so rather than leaving you wondering why a switch reading "On" makes no sound. Windows and Linux do not expose an equivalent preference, so on those platforms the in-app switch is the only control.
Auto-updates
The desktop app checks for updates automatically. You can also check manually from the app menu.