Job Search HQ

A private, local-first job-search control room. It discovers product roles, deduplicates reposts, creates evidence-backed fit analyses, pauses workflows when clarification is needed, generates approved DOCX/PDF CV packages, and tracks manual submissions and follow-ups.

The application, worker, SQLite database, candidate profile, CV content, and generated documents remain on your computer. Internet access is used only for the configured AI provider and the Techmap job feed.

Run with npx

Requires Node.js 20.9 or newer on macOS or Linux.

npx job-search-hq

The first run initializes local storage, starts the app on 127.0.0.1, and opens a browser-based onboarding screen. There you choose OpenAI or Google Gemini, add the private API key, candidate contact details, target roles, locations, work models, and timezone. No setup answers are requested in the terminal. After setup, the app opens Career Memory so you can upload the canonical CV as Markdown.

Subsequent runs reuse the local configuration and data:

npx job-search-hq --no-open
npx job-search-hq --port 3100
npx job-search-hq config

Press Ctrl+C to stop both local services. A second launch detects the running instance instead of starting another worker.

Local storage

• macOS: ~/Library/Application Support/job-search-hq/
• Linux: $XDG_DATA_HOME/job-search-hq/ or ~/.local/share/job-search-hq/

Use --app-dir <path> to select another location. Configuration is stored with restrictive permissions. Provider environment variables override a saved key.

Backup and restore

Stop the app before creating a backup.

npx job-search-hq backup --output ./job-search-hq-backup.tar.gz
npx job-search-hq restore ./job-search-hq-backup.tar.gz --app-dir ./restored-job-search-hq

Backups contain a consistent SQLite snapshot, generated artifacts, checksums, schema information, and table counts. API keys are deliberately excluded. Restore only accepts an empty destination and verifies archive paths, checksums, SQLite integrity, and foreign keys before activating the restored data.

Local development

1. Copy .env.example to .env.local.
2. Add OPENAI_API_KEY or GOOGLE_AI_API_KEY.
3. Run npm install.
4. Run npm run dev.
5. Open http://127.0.0.1:3000.

Useful commands:

npm run lint
npm test
npm run build
npm run backup -- --output /safe/path/backup.tar.gz
npm run restore -- /safe/path/backup.tar.gz --app-dir /empty/path
npm run package:build
npm run package:verify
npm run privacy:scan

Safety and privacy

• API keys are server-side and are never stored in SQLite or included in backups.
• The canonical Markdown CV controls chronology; tailoring cannot alter verified companies, titles, or dates.
• Only approved career facts may add information beyond the canonical CV.
• A recruiter-eye review is required before document generation.
• The app never submits applications or automates LinkedIn authentication.
• The local server binds only to 127.0.0.1.
• Public export and npm packaging are blocked by privacy scans for secrets, personal identifiers, private files, databases, CV documents, generated artifacts, and an optional private denylist.

To create a fresh public Git history without copying the private repository metadata:

JOB_SEARCH_HQ_PRIVACY_DENYLIST=/path/to/private-denylist.txt \
  npm run public:export -- --output /empty/path/job-search-hq-public

The export creates a separate repository, scans its complete history, and does not add a remote.

Automatic npm releases

Every commit pushed to main runs .github/workflows/npx-release.yml. The workflow installs locked dependencies, runs typechecking and tests, scans the source and complete Git history, builds in an isolated directory, scans the packed tarball, assigns the next available patch version, and publishes job-search-hq publicly.

Publishing uses npm trusted publishing rather than a long-lived npm token. Configure the package's npm trusted publisher with GitHub user IdoZiv, repository job-search-hq, workflow filename npx-release.yml, and the npm publish permission. The GitHub repository may remain private; npm provenance is disabled because npm does not support provenance for private repositories.

Store the optional private denylist as the GitHub Actions secret JOB_SEARCH_HQ_PRIVACY_DENYLIST, with one forbidden value per line. It is written only to a permission-restricted runner-temporary file during the release.