Kestrel

A job search system that runs on your computer.
Finds jobs. Scores them. Tracks your pipeline. Your data stays yours.

At a glance · See it in action · Install · Features · Privacy · Roadmap · Docs · AI providers

At a glance

Kestrel scans job boards, scores every posting against your profile with an LLM, and tracks the whole search in a local-first web app (FastAPI backend, React frontend). Numbers first:

Looking for something more established?

career-ops is a bigger, more mature, far more popular take on the same problem — tens of thousands of stars, a large community, and a polished agent-skill workflow that plugs into whichever AI coding CLI you already use. If you want the well-trodden path, start there. It is genuinely good, and it was built independently of this project — we arrived at a lot of the same ideas separately, which is usually a sign the ideas are right.

Kestrel is a different shape, not a competitor:

• A running system, not a skill layer. FastAPI + React + SQLite, a real state machine, and a web UI you operate — rather than commands driven through an AI assistant.
• Measurement as a first-class feature. A golden-set eval harness in nightly CI, a geo-eligibility engine with a committed 277-item reference set, and a source registry that reports every scan source on every run — so a dead source shows up as ZERO instead of vanishing from the report. It warns; it does not fail the run, and catching degradation (rather than a hard zero) needs floors you calibrate yourself.
• Provider economics taken seriously. Ten providers behind one interface, fallback chains, and guards that stop an exhausted cheap tier from quietly billing a premium model.

Pick whichever fits how you work. If you use both, the pieces here that are generic are meant to be portable — issues and PRs in that direction are welcome in either repo.

The scoring pipeline is treated as a measured system, not a prompt that felt right once: the eval harness scores the production code path (never a reimplementation), and a scoring regression fails the nightly build before it ships. How that works, and what is still interim about it, is written up in tests/eval/README.md.

From unemployed to multiple offers

A job search is chaos. Dozens of tabs. Spreadsheets that go stale. Applications you forget about. Kestrel replaces all of that with a single system that runs on your computer and gets smarter as you use it.

Here's what that looks like in practice:

1. Tell Kestrel about yourself (2 minutes)

Answer six questions — name, location, target role, salary range, skills, experience level. That's your profile. Kestrel uses it to score every job it finds against what you actually want.

2. Discover jobs automatically

Kestrel scans Indeed, LinkedIn, Glassdoor, and Arbeitsagentur. Every result gets an AI fit score — A+ means "apply today", C means "probably not worth your time". Stop scrolling job boards. Let the jobs come to you.

3. Track your entire pipeline

Every application lives on a Kanban board. Drag cards between stages as you progress — from Discovered to Interested to Applied to Interviewing to Offer. At a glance, you know exactly where everything stands.

4. Go deep on any application

Click into any application and you get everything: fit score breakdown, salary range, follow-up reminders, full activity log, interview prep materials, and a timeline of every interaction. No more "wait, where did I leave off with Stripe?"

5. Never drop the ball

Follow-ups with due dates, organized by urgency. "Respond to Stripe offer." "Call Datadog recruiter about competing offer." "Send thank-you after Vercel final round." Nothing slips through the cracks.

6. See your progress in real numbers

A 41.7% response rate. A conversion funnel showing where applications advance or stall. Time-in-stage metrics so you know if a company is ghosting you or just slow. Data replaces anxiety.

7. Know your strengths (and gaps)

Your entire skill inventory, categorized and rated. Technical skills, tools, domain expertise, soft skills — each with a proficiency level from Beginner to Expert. When Kestrel scores a job, it matches against this.

8. Build your network, not a spreadsheet

Every recruiter, referral, mentor, and hiring manager in one place. Warmth indicators (cold/warm/hot), relationship types, referral status, tags. Your network is an asset — treat it like one.

9. Prepare for every interview

STAR story library — your best professional moments, tagged by skill. When you apply to a role that needs "system design leadership", Kestrel surfaces the story where you led the migration to microservices. Gap analysis tells you which required skills don't have a story yet, so you can prepare before the behavioral round starts.

10. Brainstorm cover letters out loud

Voice mode turns your messy thoughts into structured cover letter drafts. Pick an application, start talking about why you want the role, and Kestrel shapes your stream-of-consciousness into something you'd actually send. Three modes: cover letter brainstorming, career coaching Q&A, and job evaluation — all conversational.

11. Track referrals from intro to offer

Your contacts aren't just names — they're referral pipelines. Track each one from "contacted" through "CV sent" to "submitted" to "feedback received." Log every interaction. Know exactly who to follow up with and when. The warm intro is often worth more than the perfect resume.

12. Connect your tools

TickTick for task sync. Calendar for interview scheduling. Pushover for mobile alerts when new matches arrive or follow-ups are due. AI providers for scoring intelligence. Everything plugs in through Settings.

The result

You started with an empty pipeline and a vague sense of dread. Six weeks later, you're negotiating between two offers, your follow-ups are on autopilot, and you have data showing exactly which companies are worth your time. That's Kestrel.

Your data stays yours

This isn't a slogan — it's the architecture. Kestrel runs on your computer. Your database is a SQLite file in your home directory. Your resume, cover letters, STAR stories, salary expectations, networking notes — none of it touches a server unless you explicitly connect an AI provider.

Snapshots and recovery

Months of job-search history sit in one SQLite file. Lose it and you've lost the search. Kestrel ships with a rotating-snapshot script so an accidental wipe is recoverable in under a minute:

python tools/snapshot_db.py                # daily snapshot, last 7 days retained
python tools/snapshot_db.py --keep 30      # 30-day window instead
python tools/snapshot_db.py --dry-run      # preview without writing

Snapshots land in data/snapshots/career_os-YYYY-MM-DD.db. The script uses SQLite's online backup API, not plain cp, so the file is consistent even if the live DB is mid-transaction under WAL.

Wire it into your daily cron (Linux/macOS):

0 3 * * * cd /path/to/kestrel && /path/to/kestrel/.venv/bin/python tools/snapshot_db.py

Or as a macOS launchd plist / systemd timer if you prefer. Recovery is a copy:

cp data/snapshots/career_os-2026-05-04.db data/career_os.db
rm -f data/career_os.db-shm data/career_os.db-wal
# restart the server

Even then, you control what goes where:

• Ollama — everything stays on your machine. Zero network calls. Free.
• Anthropic — 7-day data retention, shortest in the industry. SOC 2 certified.
• Together AI — one-click Zero Data Retention (ZDR). SOC 2 Type 2. Frankfurt data center for EU users.
• OpenRouter — routes to any model. Privacy depends on the underlying provider.

Job descriptions are public data — safe to send anywhere. Your personal information (resume, stories, contacts) should only go to providers you trust. Kestrel keeps these separate by design.

What it does

What's coming

Kestrel is under active development. Here's what's next:

Everything above will follow the same principle: your data, your machine, your choice. The hosted version will be the only exception — and even there, you'll own your data with full export and delete.

For the full picture — every shipped milestone with deep dives, every planned milestone with open questions, and "Want to help?" callouts pointing to concrete contribution areas — see ROADMAP.md.

Install

Six ways in, ranked from "I don't want to think" to "I'll run it myself."

1. Try in your browser

Nothing installed. Nothing configured. Free with a GitHub account — your own instance in 2 minutes. Data resets when the codespace stops.

2. Deploy to Railway

Your own Kestrel instance with a permanent URL. Free tier, no credit card. Data persists across restarts. See deployment guide for volume setup.

3. One-command install

curl -fsSL https://raw.githubusercontent.com/pleasedodisturb/kestrel/main/install.sh | bash

Detects your OS, checks for Python 3.11+, installs Kestrel, opens it in your browser. Also available as npx kestrel-app (Node.js) or brew install pleasedodisturb/kestrel/kestrel (macOS).

4. pip install

pip install kestrel-app
kestrel start

Opens your browser automatically. Data stored in ~/.kestrel/. Requires Python 3.11+ — install it here if you don't have it (2 minutes).

5. Docker

git clone https://github.com/pleasedodisturb/kestrel.git && cd kestrel
bash setup.sh

Fully isolated — nothing touches your system Python. Requires OrbStack (Mac, recommended) or Docker Desktop (Mac/Windows).

Lost? Step-by-step guide or FAQ.

Docs

Getting started:

Understanding AI in Kestrel:

How it works under the hood:

Going deeper:

Add real AI (optional)

Kestrel works out of the box in Demo Mode — free, offline, no account needed. When you're ready for real AI-powered scoring, you have options. Think of AI providers like electricity companies: the light switch works the same no matter who supplies the power.

Cost depends on model and volume. A typical daily scan scrapes 1,000-1,500 jobs from multiple boards. That's a lot of AI calls. Here's what it actually costs:

Model	Cost per job	1,500 jobs/day	Monthly (30 days)
Llama 3.3 70B (OpenRouter free)	$0	$0	$0
Llama 3.1 8B (Together AI)	$0.0002	$0.30	$9
GPT-4o-mini (OpenRouter)	$0.0006	$0.90	$27
Llama 3.3 70B (Together AI)	$0.002	$3.00	$90
Claude Sonnet (OpenRouter)	$0.02	$30.00	$900

Kestrel defaults to free-tier models for bulk scanning. Premium models like Claude Sonnet are best reserved for deep analysis of shortlisted roles, not bulk filtering. The optimizations below help keep costs in check regardless of which model you use.

Order your fallback chain cheap-first. If you chain providers (AI_PROVIDER_FALLBACK), whatever sits at the end is what you pay when the cheaper ones run out of quota. Put free/cheap models first and premium last — otherwise a busy or exhausted-quota day can bill an entire scan at premium rates (that $900 row, not the $0 one), often 20-50× the norm. The rule + a worked example →

Quickest path: Go to Settings → click "Connect to OpenRouter" → log in → done. No API keys to copy. Free-tier models like Llama 3.3 70B handle job scoring at zero cost — add $10 of credits to unlock 1,000 requests/day.

How Kestrel keeps costs low

AI APIs charge per token (roughly per word). Scoring 50 jobs a day could get expensive — unless you're smart about it. Kestrel stacks eight optimizations that compound:

Benchmarked on a real profile + real job posting: Naive approach = ≈$16/month. With all optimizations = ≈$1-5/month for the same results. How it works →

System prompt:  sent 50× full price  →  1× full + 49× cached (92% saved)
Profile data:   sent 50× with indent →  1× compact + 49× cached (92% saved)
Job description: 50× unique (no savings — this is the irreducible cost)

Single call:  877 tokens (old) → 512 tokens (new, Anthropic cached) = 42% reduction
50-job batch: 43,862 tokens (old) → 25,846 tokens (new) = 41% reduction
Monthly (200 jobs/day): $15.79 → $9.45 input tokens only

Choosing a provider

Don't want to think about it? Use OpenRouter. It's the universal adapter — one account gives you Claude, GPT, Gemini, and open-source models. You can always switch later.

Care about privacy? Anthropic has 7-day data retention (shortest in industry). Together AI has a one-click ZDR toggle (SOC 2 Type 2 certified). Ollama keeps everything on your machine.

On a tight budget? Together AI runs open-source models (Llama 3.3, Mixtral) on their own GPUs — no middleman markup. If you're in Europe, their Frankfurt data center means lower latency too. Great for bulk scoring where you don't need Claude-level intelligence.

Want the best of everything? Kestrel can use multiple providers at once — route simple scoring to Together (cheap), complex analysis to Anthropic (quality), and never worry about which is which.

Want to understand more? Read How Kestrel Uses AI — it explains everything in plain English, no jargon. For the full technical comparison with pricing tables and privacy audits, see the AI Provider Setup guide or the LLM landscape research.

Privacy and free/cheap models

Free and cheap AI models often train on your data or have weaker privacy guarantees. That's fine for some tasks and dangerous for others. Kestrel distinguishes between the two:

Safe to send without ZDR (generic, non-identifying):

• Job descriptions (public postings)
• Career preferences (target roles, salary range, location)
• Scoring criteria and rubrics

Never sent without ZDR (personally identifying):

• Your name, email, phone number, or address
• CV/resume content and work history
• Cover letters and application materials
• Interview preparation with personal STAR stories
• Contact details and networking notes

Currently: Kestrel does not enforce this boundary automatically - it's your responsibility to choose an appropriate provider for sensitive features. If you disable ZDR for cheap scoring, be mindful of which features you use with that provider.

Planned: Automatic routing that blocks personal data from reaching non-ZDR providers, so you can use free models for scoring without worrying about accidentally leaking personal data through other features.

Rule of thumb: If it's about the job market, cheap models are fine. If it's about you, use Ollama (local), Anthropic (strong privacy), or a provider with ZDR enabled.

How we build

Human-first, data-driven. Every infrastructure decision — testing, CI/CD, scoring — is backed by deep research. We investigate thoroughly, then choose the sanest path: not the most sophisticated, but the most sustainable.

Our proof is in the research artifacts. Before building anything, we run parallel research agents, synthesize findings, and publish the decision rationale so anyone can understand why things work the way they do.

License

AGPL-3.0 — free and open source. If you modify Kestrel and offer it as a service, you must share your changes under the same license.

Data sources

• ESCO (European Skills, Competences, Qualifications and Occupations) — the bundled skills and occupations taxonomies are © European Union, esco.ec.europa.eu, reused under CC BY 4.0 per Commission Decision 2011/833/EU. Kestrel ships processed, English-only subsets; changes are described in each fixture's metadata.