Local-first, human-controlled career workspace for official-source lead generation, resume-to-role validation, shortlist review, and approval-gated outreach.
JobHuntOS Core helps one person find roles from sanctioned public sources, evaluate them truthfully, and prepare next steps without turning the workflow into hidden automation.
Most job-search tooling breaks in one of two ways:
- it collapses into spreadsheets with weak provenance and no audit trail
- it pushes toward scraping, spam, or automation that hides what the system is doing
JobHuntOS Core takes the opposite approach. It is designed to help a human decide what to do next, keep the workflow reviewable, and make every externally visible action explicit.
- a local FastAPI + React application with SQLite as the source of truth
- a compliance-first product for ingesting roles from official public ATS endpoints
- a truthful resume-to-role validation workspace
- a shortlist and dossier workflow with provenance, confidence, and risk flags
- a draft-first outreach workflow with visible approval gates
- a demo-first repo with a synthetic public walkthrough
- not an auto-apply bot
- not a browser automation agent
- not a scraper for LinkedIn, Indeed, or restricted job boards
- not a recruiter spam tool
- not a hidden messaging system
Demo mode is the primary public path. It uses synthetic data and stays separate from any real local workspace.
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e .[dev]
npm install --prefix frontend
npm run build --prefix frontend
python -m jobhunt_os.cli seed-demo --app-home .fresh_runtime\demo
python -m jobhunt_os.cli demo-ui --app-home .fresh_runtime\demo --host 127.0.0.1 --port 8011Open http://127.0.0.1:8011.
Public demo walkthrough:
- Dashboard: understand the workflow in under two minutes
- Source Hub: see compliant public-source ingestion
- Resume Fit: compare a stored resume against a role truthfully
- Shortlist: review strategy-ranked opportunities
- Dossiers: inspect provenance, confidence, and risk
- Outreach: review draft-only, approval-gated next steps
More detail: Quickstart Demo
This repo is differentiated by the combination of:
- official ATS lead generation Greenhouse, Lever, and Ashby via sanctioned public endpoints
- truthful Resume Fit compare what a resume actually supports, surface gaps, and save a role packet without inventing experience
- strategy-aware shortlist + dossiers prioritize candidate-relevant roles, not just salary, and explain why a role made the cut
- approval-gated outreach keep drafts, review state, and human confirmation explicit
- demo-first transparency the public repo is understandable without live credentials or real user data
| Area | Included in Core | Why it matters |
|---|---|---|
| Official ATS source adapters | Yes | Compliant lead generation from Greenhouse, Lever, and Ashby |
| Resume Fit workspace | Yes | Truthful role matching, gap detection, and apply-ready notes |
| Shortlist + dossiers | Yes | Ranked decisions with provenance, confidence, and risk flags |
| Approval-gated outreach | Yes | Draft-first workflow with visible review and send boundaries |
| Demo mode | Yes | Synthetic, public-safe walkthrough of the full product |
| Resume Vault | Yes | Local storage and preview for lane-specific resume assets |
| Diagnostics + audit log | Yes | Visibility into runtime state, approvals, and workflow history |
| Gmail workflow | Optional | Local OAuth only; not fully validated end-to-end without credentials |
| LinkedIn sign-in | Optional | OIDC-ready local setup; only validated when local credentials are configured |
| LinkedIn posting | Conditional | Requires approved LinkedIn product and w_member_social |
| Tauri shell | Packaging-prep only | Present for future desktop packaging, not a shipped headline feature |
| Auto-apply | No | Explicitly out of scope |
The dashboard explains the product quickly: public-source intake, human control, next actions, and a synthetic demo checklist.
Source Hub shows which adapters are configured, how healthy they are, when they last refreshed, and whether they are producing shortlist-worthy roles.
Resume Fit compares a stored resume against an imported or pasted role, explains the fit score, highlights unsupported requirements, and saves a truthful role packet.
The shortlist is for ranked decisions, not raw volume. It surfaces candidate-relevant roles with clear next-step reasoning.
Each dossier consolidates source provenance, official careers URL, confidence, risk flags, fit notes, and recommended action.
| Settings | Diagnostics |
|---|---|
 |
 |
Settings keeps profile, integrations, source registry, and compliance reminders in one place. Diagnostics exposes runtime health, autostart state, logs, and auth status without leaving the app.
- Local-first The product is designed to run on one machine with local storage and explicit runtime paths.
- Human-controlled Review, approval, and manual action stay visible. Nothing should quietly act on a user’s behalf.
- Truthful resume adaptation Resume Fit and role packets should surface gaps, not fabricate capability.
- Approval-gated outreach Outreach remains draft-first, with explicit confirmation before any send-capable integration is used.
- Provenance and auditability Leads, dossiers, and decisions should be explainable and traceable.
- No restricted scraping or hidden automation Official public feeds only. No login automation, no DM automation, no auto-apply.
flowchart LR
A[Official public ATS feeds or local imports] --> B[Source adapters / normalization]
B --> C[Deduped leads]
C --> D[(SQLite)]
D --> E[Shortlist + dossiers]
D --> F[Resume vault + Resume Fit]
D --> G[Draft outreach + approvals]
D --> H[Audit log + diagnostics]
I[FastAPI backend] --> D
J[React local UI] --> I
K[Optional local integrations\nGmail, LinkedIn] --> I
Supporting docs:
Gmail and LinkedIn exist as optional local integration surfaces, not as headline public features.
- Gmail: local OAuth setup, approval-gated recipient flow, draft preview, and explicit send confirmation
- LinkedIn: bounded workspace, OIDC-ready sign-in, and scope-gated posting only when the app actually has the required product approvals
These integrations should be treated as configuration-dependent. They are intentionally documented more conservatively than the core local workflow.
- engineers who want a local-first, inspectable career workflow
- people who want structured sourcing and role review without hidden automation
- founders, collaborators, and hiring managers evaluating product judgment around compliance and workflow reliability
- open-source users who care about provenance, boundaries, and truthful automation support
- users looking for one-click job application automation
- users expecting LinkedIn scraping or recruiter DM automation
- users who want a cloud multi-user CRM
- users who want unrestricted connector sprawl over explicit workflow boundaries
The public repo is demo-first. If you want to run the real local operator workflow:
python -m jobhunt_os.cli startup-checks --mode operator --app-home .fresh_runtime\operator
python -m jobhunt_os.cli ui --mode operator --app-home .fresh_runtime\operator --host 127.0.0.1 --port 8010Open http://127.0.0.1:8010.
Near-term roadmap, kept intentionally honest:
- improve the public source registry workflow and source-quality analytics
- continue tightening demo-first docs and screenshots
- deepen Resume Fit explainability and role-packet ergonomics
- keep Gmail / LinkedIn integration surfaces conservative and clearly bounded
- stabilize packaging-prep for a future desktop shell without making it the main story
- contribution guide: CONTRIBUTING.md
- security policy: SECURITY.md
- architecture and workflow docs: docs/
- issue templates:
- bug report
- source adapter request
- integration idea
Before using this repo publicly:
- run the demo path and confirm screenshots still match
- confirm no runtime DBs or generated private exports are committed
- confirm optional integrations are documented honestly
- confirm the app still says nothing gets sent automatically
- confirm demo assets remain synthetic and safe to share
Checklist: