Local-first AI job intelligence for scraping better roles, ranking fit, and generating tailored application materials.
What It Does · Workflow · Architecture · Quick Start · Contributing · Roadmap
JustHireMe is an open-source desktop workbench for people who are tired of noisy job boards and black-box AI apply tools.
JustHireMe is in alpha. The repository is public, hackable, and ready for source-adapter, ranking, docs, and Windows packaging contributions, but it is not a polished one-click consumer product yet.
| Area | Status |
|---|---|
| Frontend workbench | Active |
| Python sidecar API | Active |
| Scraper, ranking, vector matching, and customizer core | Supported OSS scope |
| Windows desktop packaging | First release target |
| Browser automation / auto-apply | Experimental lab, disabled by default |
| API key storage | Local app settings for now; OS keychain planned |
If you are new here, start with the frontend preview first. If you want to contribute backend behavior, source adapters, or packaging, use the full desktop setup below.
It helps you:
| Stage | What JustHireMe Does | Why It Matters |
|---|---|---|
| Scrape | Collect leads from ATS boards, feeds, communities, APIs, and configured sources | You are not locked into one job board |
| Quality Gate | Reject stale, thin, spammy, senior-only, or low-context leads before they pollute the pipeline | Better signal, less cleanup |
| Rank | Score lead quality and candidate fit with explainable deterministic rules, feedback learning, and optional LLM reasoning | You can see why a role is worth attention |
| Match | Use Kuzu graph data and LanceDB vectors to compare jobs against your profile context | Matching is profile-aware, not keyword-only |
| Customize | Generate tailored resume PDF, cover letter PDF, and outreach drafts | You get a useful package, not just a list of links |
Browser automation and auto-apply code exists in the repository, but it is experimental and unsupported. The supported OSS core is scraper, ranker, vector matching, and customizer.
flowchart LR
A["Import Resume / Profile"] --> B["Profile Graph<br/>Kuzu"]
A --> C["Skill + Project Vectors<br/>LanceDB"]
D["Scraper Sources"] --> E["Normalized Leads"]
E --> F["Lead Quality Gate"]
F --> G["Ranker + Evaluator"]
B --> G
C --> G
G --> H["Lead Pipeline"]
H --> I["Customizer"]
I --> J["Resume PDF"]
I --> K["Cover Letter PDF"]
I --> L["Outreach Drafts"]
flowchart TD
S["Source Adapter"] --> N["Normalize Lead"]
N --> Q{"Quality Gate"}
Q -- "Reject" --> R["Filtered with reason"]
Q -- "Accept" --> C["Local CRM"]
C --> E["Fit Evaluation"]
E --> U["User Review"]
Q:::gate
R:::reject
C:::store
E:::score
classDef gate fill:#e0f2fe,stroke:#0284c7,color:#0f172a
classDef reject fill:#fee2e2,stroke:#dc2626,color:#0f172a
classDef store fill:#dcfce7,stroke:#16a34a,color:#0f172a
classDef score fill:#fef3c7,stroke:#d97706,color:#0f172a
|
Collect jobs from ATS/company boards, RSS feeds, Hacker News, GitHub-style sources, Reddit/community sources, APIs, and custom configured targets. |
Apply a deterministic quality gate before saving leads. Filter stale, thin, senior-only, unpaid, spammy, or missing-context postings. |
|
Score role alignment, stack coverage, project evidence, seniority fit, location constraints, red flags, source signal, and semantic profile similarity. |
Create a resume PDF, cover letter PDF, founder message, LinkedIn note, cold email, keyword coverage summary, and selected-project rationale. |
Most job search tools make one of two mistakes:
| Problem | Result |
|---|---|
| They scrape too broadly | Users drown in stale, irrelevant, senior-only, or spammy jobs |
| They automate too aggressively | Users lose control and trust |
| They rank opaquely | Nobody knows why a job was recommended |
| They are cloud-first | Sensitive profile/job data leaves the user's machine |
| They are hard to extend | Contributors cannot easily add new sources or improve ranking |
JustHireMe takes a different path:
More signal.
More explanation.
More local control.
More contributor-friendly source adapters.
Less blind automation.
| Principle | Meaning |
|---|---|
| Local-first | Profile data, lead history, generated docs, graph data, vectors, and settings live locally by default |
| Explainable | Every important ranking and filtering decision should have a visible reason |
| Contributor-friendly | Adding a source adapter should be approachable and testable |
| Human-controlled | Generated materials are drafts for review, not magic submissions |
| Honest fallback | If vectors, models, or source data fail, the app should say so |
| Automation is experimental | Browser automation is a lab area, not the core OSS promise |
flowchart TB
subgraph Desktop["Tauri Desktop Shell"]
UI["React + TypeScript UI"]
Bridge["Tauri Commands<br/>Port + API Token"]
end
subgraph Backend["Python Backend Sidecar"]
API["FastAPI + WebSockets"]
Scrapers["Scraper Agents"]
Gate["Lead Quality Gate"]
Ranker["Ranker / Evaluator"]
Customizer["Document + Outreach Generator"]
end
subgraph LocalData["Local Data Layer"]
SQLite["SQLite CRM"]
Kuzu["Kuzu Profile Graph"]
LanceDB["LanceDB Vectors"]
Files["Generated PDFs"]
end
UI --> Bridge --> API
API --> Scrapers --> Gate --> SQLite
API --> Ranker
Ranker --> Kuzu
Ranker --> LanceDB
API --> Customizer --> Files
API --> SQLite
| Area | Technology |
|---|---|
| Desktop shell | Tauri 2 |
| Frontend | React 19, TypeScript, Vite, Tailwind CSS |
| Backend API | Python 3.13, FastAPI, WebSockets |
| Local CRM | SQLite |
| Profile graph | Kuzu |
| Vector store | LanceDB |
| Matching | Deterministic scoring, semantic search, optional LLM evaluation |
| Documents | Markdown/PDF rendering |
| Experimental lab | Playwright browser automation |
| Packaging | Tauri bundle + Python sidecar |
More detail: docs/ARCHITECTURE.md
JustHireMe/
|-- src/ React frontend
| |-- components/ Shared UI components
| |-- hooks/ Data and websocket hooks
| |-- settings/ Settings panels
| `-- views/ Main screens
|-- backend/ Python API and agents
| |-- agents/ Scrapers, rankers, evaluator, generator
| |-- db/ SQLite, Kuzu, LanceDB helpers
| |-- graph/ Evaluation graph flow
| `-- tests/ Backend tests
|-- src-tauri/ Tauri Rust shell
|-- docs/ Architecture, source adapter, release docs
|-- scripts/ Build scripts
`-- .github/ CI, issue templates, PR template
| Tool | Version |
|---|---|
| Node.js | 20+ |
| Python | 3.13+ |
| Rust | stable |
| uv | latest stable |
| Git | any modern version |
Optional:
- Ollama for local model experiments
- Playwright browser dependencies only for experimental automation work
Use this path if you just want to inspect the UI, design direction, or frontend code.
git clone https://github.com/vasu-devs/JustHireMe.git
cd JustHireMe
npm install
npm run devThis starts the Vite frontend only. Backend-backed workflows may show empty, mocked, or unavailable states depending on the screen.
Use this path if you want the Tauri shell and Python backend sidecar.
git clone https://github.com/vasu-devs/JustHireMe.git
cd JustHireMe
npm install
cd backend
uv sync --dev
cd ..Then run:
npm run tauri devThe Tauri shell starts the frontend and launches the Python backend sidecar/dev process.
- Check whether the bug is in supported core behavior or experimental automation.
- Remove API keys, cookies, resumes, local databases, and generated private documents from logs or screenshots.
- For source requests, include a public example URL and expected normalized fields.
- For ranking bugs, include the expected score behavior and sanitized job/profile snippets.
| Task | Command |
|---|---|
| Frontend dev server | npm run dev |
| Desktop dev app | npm run tauri dev |
| TypeScript check | npm run typecheck |
| Frontend tests | npm test |
| Frontend build | npm run build |
| Backend tests on Windows | backend/.venv/Scripts/python.exe -m pytest backend/tests |
| Backend tests on macOS/Linux | backend/.venv/bin/python -m pytest backend/tests |
| Rust check | cd src-tauri && cargo check |
Source adapters turn external job sources into normalized lead dictionaries.
flowchart LR
A["Raw Source"] --> B["Adapter"]
B --> C["Normalized Lead"]
C --> D["Quality Gate"]
D --> E["Local CRM"]
Read: docs/source-adapters.md
The gate lives in backend/agents/quality_gate.py.
It checks:
| Signal | Example |
|---|---|
| URL exists | Reject rows with no source/apply URL |
| Posting depth | Penalize thin scraped snippets |
| Freshness | Penalize stale jobs |
| Seniority | Reject senior-only roles in beginner-focused feeds |
| Red flags | Penalize unpaid, commission-only, no-budget, homework, or exposure posts |
| Company/context | Penalize missing company or unclear source context |
Ranking combines:
- source signal
- lead quality score
- deterministic fit rubric
- seniority caps
- project and stack evidence
- optional LLM-assisted evaluation
- semantic fit when vectors are available
- feedback learning
flowchart LR
Resume["Resume / Profile"] --> Graph["Kuzu Graph"]
Resume --> Embed["Embeddings"]
Embed --> Vectors["LanceDB"]
Job["Job Description"] --> Query["Semantic Query"]
Query --> Vectors
Vectors --> Fit["Semantic Fit Signal"]
Graph --> Fit
For a strong lead, the customizer produces:
| Output | Purpose |
|---|---|
| Tailored resume PDF | Role-specific resume package |
| Cover letter PDF | Focused application narrative |
| Founder message | Short direct outreach |
| LinkedIn note | Concise connection/message draft |
| Cold email | Longer outreach draft |
| Keyword coverage | Shows what the generated package covers |
| Selected projects | Explains which profile evidence was used |
Settings are configured inside the desktop app. For v1, API keys are stored in local app settings.
Local data may include:
| Data | Stored Locally |
|---|---|
| Profile graph | yes |
| Vector tables | yes |
| Lead CRM | yes |
| Generated PDFs | yes |
| Settings | yes |
| Activity history | yes |
Do not share screenshots, logs, local app data, issue attachments, or database files that contain API keys, cookies, private resumes, or personal data.
Planned improvement:
- OS keychain-backed API key storage
The first public packaging target is Windows.
.\scripts\build-sidecar.ps1
npm run tauri buildRelease smoke test: docs/windows-release.md
The best first contribution path is scraper/source quality.
|
Add parser fixtures, improve docs, polish UI copy, or add a small source rule. |
Add ATS/company-board adapters with normalized lead fields and quality-gate tests. |
Improve score bands, seniority handling, semantic fallback, and feedback learning. |
Start here:
| Document | Purpose |
|---|---|
| CONTRIBUTING.md | Contribution rules and development workflow |
| CODE_OF_CONDUCT.md | Community standards |
| docs/ARCHITECTURE.md | System design |
| docs/source-adapters.md | Scraper adapter contract |
| ROADMAP.md | Project direction |
| SECURITY.md | Privacy and responsible reporting |
Please do not open public issues with API keys, resumes, cookies, bearer tokens, or database files.
The repository contains browser automation and auto-apply code for experimentation and future plugin work.
| Status | Meaning |
|---|---|
| Disabled by default | Not part of the supported job workflow |
| Unsupported lab | Useful for contributors, not normal users |
| Not marketed as core | The product works without it |
| Potential future plugin | May be separated later |
timeline
title JustHireMe OSS Roadmap
v0.1 : OSS readiness
: Quality gate
: Source adapter docs
v0.2 : More ATS adapters
: Parser fixtures
: Better source quality dashboards
v0.3 : Ranking evaluation dataset
: Semantic matching visibility
: Feedback learning improvements
Future : OS keychain support
: Cross-platform installers
: Optional automation plugin
Near-term priorities:
- more high-quality ATS/company source adapters
- stronger quality gate tests
- clearer vector matching state in the UI
- Windows installer polish
- contributor-friendly source plugin boundaries
- OS keychain support for API keys
JustHireMe is released under the MIT License.
This project is being built in the open because one person cannot cover every job source, every market, every ranking edge case, and every packaging path alone.
The goal is a useful local tool and a welcoming codebase where contributors can add sources, improve ranking, and help job seekers get better signal with less noise.