job-hunter-team

---

Job hunting is a second job on top of your job: scanning boards daily, qualifying listings, tailoring every application. JHT hands that grind to a team of AI agents running around the clock — Scout finds positions, Analyst verifies them, Scorer ranks them against your profile, Writer prepares tailored documents, Critic blind-reviews everything — orchestrated by a Captain. You only review applications that clear the quality bar.

Everything runs locally in a container — your machine or your VPS, your profile, your data, your provider account. JHT itself is free (MIT); it runs on a dedicated LLM subscription (~€40–200/mo) — breakdown in Install, local-model support (€0) is open mission M5.

I built JHT for my own job hunt — ~200 offers analyzed, ~20 tailored applications, 5 interview invites in a few weeks (story). Then I rebuilt it as open source. On the public stack, a Codex team ran one month unattended: 658 positions found, 520 scored, 307 strong matches, weekly budget self-managed at 99–100% (results).

Demo

Live dashboards with real, anonymized field data: jobhunterteam.ai/case-studies.

Numbers are self-reported snapshots of the team's event log, committed in web/data/case-studies/. Methodology: docs/about/RESULTS.md.

The Team

Always-on core — 👨‍✈️ Captain (orchestration & anti-collision) · 💂 Sentinel (event-driven budget watchdog) · 👩‍💼 Assistant (platform copilot) · 🧙‍♂️ Mentor (career coach)

Worker pool, scaled 1..N by the Captain — 🕵️ Scout (finds positions) · 👨‍🔬 Analyst (verifies them) · 👨‍💻 Scorer (0–100 against your profile) · 👨‍🏫 Writer (CVs & cover letters) · 👨‍⚖️ Critic (3 blind review rounds)

Daily one-shots — 🩺 Dottore (agent health) · 👷‍♂️ Mantenitore (infra health) · plus 📡 Bridge, the usage clock (a process, not an agent)

Why a team instead of one clever prompt? Each role keeps its own small context (a model that just read 50 job ads reasons measurably worse about CV tone); blind review only works if the Critic genuinely hasn't seen the Writer's reasoning; and the Captain can throttle or scale each role independently to keep 24/7 operation inside a fixed subscription budget.

                                       👤 User
                       ┌─────────────────┼─────────────────┐
                       ▼                 ▼                 ▼
               🧙‍♂️ Mentor       👩‍💼 Assistant      👨‍✈️ Captain ◀··intervene·· 💂 Sentinel ◀──notify── 📡 Bridge
                                                           │
                                                           ▼
                                  🕵️ Scout → 👨‍🔬 Analyst → 👨‍💻 Scorer → 👨‍🏫 Writer → 📤✅ Ready to submit
                                                                          ⇅
                                                                     👨‍⚖️ Critic (3 blind rounds)

Each agent is an autonomous AI session on one of the supported CLIs (Claude Code, Codex, Kimi); a shared SQLite database keeps state in sync. Monitoring details: docs/about/MONITORING.md.

Install

🧪 Beta — CLI-first. The supported path is the CLI below (or the AI-agent path). The desktop app is not part of the beta yet (desktop/STATUS.md). Hit a snag? docs/guides/BETA.md.

What it costs — the team burns ~400M tokens/month, so it needs a flat-rate subscription dedicated to the team (a shared account hits rate limits): the same usage on pay-per-use APIs would be $1,000–2,500/mo. Reasoning: ADR-0004 · details: docs/about/PROVIDERS.md.

Provider	Plan	Cost/mo	Status
Claude	Max x20	~€200	Production-ready, best precision
Codex	Plus / Pro	~€100	Proven — 1-month autonomous run
Kimi	Pro	~€40	Beta — in observation

Recommended: inspect first, then run (macOS / Linux / WSL) — the installer is versioned in this repo and previews every action:

curl -fsSL https://jobhunterteam.ai/install.sh -o install.sh
less install.sh              # read what it does
bash install.sh --dry-run    # preview every action — no changes to your system
bash install.sh

Or the one-liner, if you've read it and trust it: curl -fsSL https://jobhunterteam.ai/install.sh | bash

It touches exactly two files on the host — ~/.jht/runtime/docker-compose.yml and the ~/.local/bin/jht wrapper. Everything else runs inside an isolated container; only ~/.jht and ~/Documents/Job Hunter Team are mounted.

Full walkthrough, expert mode and contributor setup: docs/guides/QUICKSTART.md.

Interfaces

CLI (jht team start — reference) · Web dashboard (Next.js) · Telegram (3 bots — the recommended channel for VPS teams) · Desktop app (Electron, in development)

AI agents can drive JHT

The jht CLI is designed to be driven by AI assistants, not just humans. Already use Claude Code, 🦞 OpenClaw, Codex or Cursor? Tell it "Set up JHT and start the team for me" — it figures out the rest. Guide: docs/guides/AI-AGENT-INTEGRATION.md.

Stack & status

Stack — Node.js/TypeScript + Python (agents, monitoring, skills) · Next.js 16 + Supabase (dashboard) · Electron (desktop) · Docker · SQLite · GitHub Actions + Vercel.

Status — team + CLI + web dashboard shipped and tested end-to-end on all three providers, full UI i18n in 7 languages; 240 test files — 200 active (869 vitest + 425 pytest, green in CI) + 40 legacy parked in tests/js/tasks/_disabled/ (tracked debt, issue #102). In progress: desktop app toward public beta, Kimi tier hardening. Full picture: docs/about/ROADMAP.md.

Monorepo: cli/ · web/ · desktop/ · tui/ · shared/ · agents/ · scripts/ · e2e/ · supabase/ · docs/ — each has its own README; index in docs/README.md.

Contributing

JHT is built by a solo maintainer orchestrating AI agents on parallel devN branches — external contributions come in as feat//fix/ branches → PR (CONTRIBUTING.md).

• Start here: good first issue · bigger directions: contributor missions M1–M5
• Beta tester? docs/guides/BETA.md — we want real job-seekers to break things
• Security issue? SECURITY.md — responsible disclosure, please no public issue

License

MIT — see LICENSE.