Job Hunt

An evidence-gated, human-in-the-loop CLI for finding and triaging jobs.

Job Hunt discovers listings from public company hiring systems, removes duplicates, scores the remaining roles against claims you have verified, and builds a short daily report. It can prepare context for semantic analysis and application materials. Every application remains a human decision.

Install

Job Hunt is distributed as the evidence-job-hunt Python package. The installed command is jobhunt.

pipx install evidence-job-hunt

If pipx is missing, follow the official pipx installation guide.

Job Hunt requires Python 3.10 or newer.

First run

jobhunt init
jobhunt doctor

jobhunt init asks a few plain-language questions about:

• the roles you want;
• where you can work;
• technologies you can honestly claim;
• compensation and excluded industries;
• one concrete piece of verified professional evidence.

It creates a private workspace in ~/.jobhunt. Your profile, listings, decisions, and generated reports stay there rather than inside the installed package.

When configuration is valid, jobhunt doctor ends with:

RESULT: READY

Morning routine

jobhunt daily
jobhunt open

daily reads configured public Ashby, Greenhouse, and Lever boards, filters titles, normalizes descriptions, removes previously seen listings, calculates provisional evidence-based scores, and writes the daily report.

open opens the report folder. The shortlist is deliberately small enough to inspect rather than another feed to scroll.

To preview discovery without writing jobs or changing state:

jobhunt discover --preview

LinkedIn searches

jobhunt linkedin --freshness day

This generates targeted LinkedIn search links. It does not log into LinkedIn, scrape an account, or automate applications. You open the searches and choose listings manually.

One manually selected listing

Save the public job description as a text file, then run:

jobhunt ingest PATH_TO_JOB.txt

The same normalization, deduplication, and scoring pipeline is used.

From candidate to application

Mechanical scores are provisional. A title can say “AI” while the actual job requires browser internals, Kubernetes operations, or another profession entirely.

Prepare a self-contained semantic-analysis bundle:

jobhunt analyze JOB

After reviewing the evidence map and gaps, record a decision:

jobhunt decide JOB SHORTLISTED \
  --analysis-score 74 \
  --analysis-recommendation "STRONG MATCH" \
  --reason "Evidence-backed reason for the decision."

Optional stretch assessment remains separate from factual fit:

jobhunt stretch JOB STRETCH_CANDIDATE \
  --direct-matches 4 \
  --core-gap "Explicit missing requirement" \
  --hard-blockers 0 \
  --learning-ramp-weeks 8 \
  --reason "Why this is a credible bounded stretch."

For an eligible shortlisted role:

jobhunt application-bundle JOB

The lifecycle is explicit:

DISCOVERED → REJECTED / MAYBE / SHORTLISTED
SHORTLISTED → APPROVED_TO_APPLY → APPLIED

Only record APPLIED after you have submitted the application yourself.

Why the evidence registry exists

~/.jobhunt/profile/evidence.yaml is the factual boundary. Each claim has safe wording, technologies, evidence strength, and forbidden exaggerations.

The mechanical layer can match and score those claims. An LLM can interpret whether the evidence is direct, transferable, missing, or blocked. Neither layer receives permission to invent experience or turn an experiment into production work.

Useful commands

jobhunt init                         Create a private workspace
jobhunt doctor                       Validate configuration
jobhunt daily                        Run discovery, triage, and reporting
jobhunt open                         Open the report folder
jobhunt discover --preview           Preview public ATS matches
jobhunt linkedin --freshness day     Generate manual LinkedIn searches
jobhunt ingest JOB.txt               Process one saved listing
jobhunt analyze JOB                  Prepare semantic-analysis context
jobhunt decide JOB STATE             Record a human lifecycle decision
jobhunt stretch JOB STATUS           Record a stretch assessment
jobhunt application-bundle JOB       Prepare gated application context
jobhunt help                          Show CLI help

Private workspace

The default workspace is ~/.jobhunt. To use another location:

export JOBHUNT_HOME="$HOME/my-job-search"

Back up this directory if you want to preserve listing history and lifecycle decisions.

Advanced users can edit the generated YAML, profile, evidence registry, resume template, discovery targets, and prompts directly. See GETTING_STARTED.md.

Safety boundary

Job Hunt does not submit forms, contact employers, send outreach, fabricate qualifications, or automate a LinkedIn account. It prepares evidence and preserves an audit trail; the candidate controls every consequential action.

Development

git clone https://github.com/Tesliana-code/job-hunt.git
cd job-hunt
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

The project is licensed under the MIT License.