Skip to content

Getting Started (Technical)

This guide takes you from a clean Windows machine to a running WorkWingman dev environment: the .NET API, the Angular frontend, and (optionally) the Electron shell that wraps them.

WorkWingman is Windows-first and local-first: the API binds to loopback only (http://127.0.0.1:5211), and all app data lives on your machine.

Prerequisites

Tool Version Why Install
.NET SDK 10.x Builds and runs the backend (WorkWingman.Api) and tests. dotnet.microsoft.com/download
Node.js 22.12+ Runs the Angular frontend and the Electron shell. Electron 43 requires Node 22.12+. nodejs.org
Git any recent Clone the repo, branch, PR. git-scm.com

The Node minimum is enforced, not just recommended: electron/package.json declares "engines": { "node": ">=22.12.0" }, and .npmrc sets engine-strict=true, so npm will refuse to install under an older Node instead of failing later in a confusing way.

Everything else WorkWingman needs at runtime (Playwright's Chromium, KeePassXC, the Claude CLI, and so on) is handled by the in-app dependency doctor on first launch — see What the dependency doctor does.

Clone

git clone https://github.com/andrewjonesdev/WorkWingman.git
cd WorkWingman

Run it (three terminals)

The app is three cooperating processes. In development you run them separately so you get hot reload and readable logs from each.

Terminal 1 — the backend API

dotnet run --project src/WorkWingman.Api

Serves on http://127.0.0.1:5211 (loopback only — never 0.0.0.0). This is the brain: controllers over Core interfaces over Infrastructure implementations.

Terminal 2 — the Angular frontend

cd frontend
npm install
npm start

Serves the dev UI on http://localhost:4200. The Angular app calls the API directly at http://127.0.0.1:5211 (see api.service.ts) — there is no dev proxy, so the backend (terminal 1) must be running or those calls fail with a connection error in the browser console.

Terminal 3 — the Electron shell (optional)

cd electron
npm install
npm run dev

The Electron shell wraps terminals 1 and 2 into a desktop window. The dev script sets WINGMAN_DEV=1, which tells main.js to load the dev Angular URL (localhost:4200) instead of a built bundle, so you keep frontend hot reload inside the desktop window.

You do not need Electron to develop. The frontend at localhost:4200 talks to the API at 5211 on its own. Reach for Electron when you're testing shell behavior (window, supervisor, preload bridge).

Ports at a glance

Process URL Notes
API (WorkWingman.Api) http://127.0.0.1:5211 Loopback only.
Angular dev server http://localhost:4200 Proxies to the API.
Electron shell n/a (desktop window) WINGMAN_DEV=1 loads localhost:4200.

Running the tests

# Backend: 381 xUnit tests (unit + in-memory API smoke tests)
dotnet test

# Frontend: Vitest
cd frontend
npm test

Both must pass before you open a PR — see contributing.md.

What the dependency doctor does on first launch

On first launch the app runs a dependency doctor that probes for every third-party tool it needs or recommends — Node, Playwright's Chromium, KeePassXC, the Claude CLI, and so on — and reports each as Ok, Outdated, or Missing (see DependencyReport / DependencyStatus in src/WorkWingman.Core/Models/Dependency.cs).

  • Detection (GET /api/dependencies) is read-only and runs every launch.
  • Installs/repairs (POST /api/dependencies/install) act only on the explicit list of ids you approve in the UI — per-item approval, no "install everything" shortcut.
  • Auto-installable dependencies go through winget, npm, or the Playwright CLI. Ones that can't be installed unattended link you to their download page instead.
  • Required gaps block launch until resolved; optional ones (e.g. the gh CLI) are reported but never block.

The install endpoint is token-gated: it requires the X-WorkWingman-Token header (or a trusted dev origin) so a hostile web page can't drive winget/npm through the loopback API. See api-reference.md.

Troubleshooting

npm errors out about the Node engine / "Unsupported engine". Your Node is older than 22.12. engine-strict is on by design. Install Node 22.12+ from nodejs.org and re-run npm install. Check with node --version.

The frontend loads but the API isn't reachable (calls fail with a connection error in the browser console). Terminal 1 probably isn't up. The Angular app calls http://127.0.0.1:5211 directly (no dev proxy), so confirm dotnet run --project src/WorkWingman.Api is running and listening there. The API is loopback-only, so it must run on the same machine as the frontend. A quick check: curl http://127.0.0.1:5211/api/jobs.

The vault is locked (form-fill or vault screens can't read secrets). The KeePass vault starts locked. Unlock it (POST /api/vault/unlock, exposed by the Vault screen) before running an application. Check state with GET /api/vault/status ({ "unlocked": false } means locked). Note the vault never returns secrets over HTTP — only metadata — so "locked" is about enabling in-process resolution, not fetching passwords.