kestrel-app 0.10.0

AI-powered job search platform. Self-hosted, open-source, privacy-first.

Kestrel

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

---

Install

Pick whichever feels right. They all give you the same app.

Quick install (one command)

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

Detects your OS, checks for Python 3.11+, installs Kestrel, and opens it in your browser.

Or if you have Node.js:

npx kestrel-app

Or with Homebrew (macOS):

brew install pleasedodisturb/kestrel/kestrel
kestrel start

Option 1: pip install (simplest)

pip install kestrel-app
kestrel start

Opens your browser automatically. Data stored in ~/.kestrel/.

Requires Python 3.11+. Don't have Python? Install it from python.org/downloads (Mac/Windows installer, takes 2 minutes). Or use Option 2 or 3 below instead.

Option 2: Docker (isolated, nothing touches your system)

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

Requires OrbStack (recommended for Mac) or Docker Desktop (Mac/Windows). Both are free. Don't know what Docker is? The step-by-step guide explains everything.

Option 3: Try in your browser (zero install)

Free with a GitHub account. Your own instance in 2 minutes. Nothing installed on your computer.

Lost? Step-by-step guide or FAQ.

---

Preview

Pipeline — drag applications across stages

Discovery — AI-scored job matches

Settings — connect your integrations

---

What it does

• Discovers jobs from multiple boards automatically (Indeed, LinkedIn, Glassdoor, Arbeitsagentur)
• Scores them against your profile with AI - stop guessing which jobs are worth applying to
• Tracks your pipeline on a Kanban board - drag applications between stages
• Prepares you for interviews - company research, mock questions, STAR story library
• Runs daily scans via GitHub Actions - wake up to a scored digest of new matches
• Works offline - Demo Mode included, zero cost to start. Add real AI when ready.

Everything runs on your machine. No account needed. No data leaves your computer (unless you connect an AI provider).

---

Docs

Getting started:

Guide	What you'll learn
Quickstart	First-time setup, step by step — zero assumptions
FAQ	"Can I...?" "What if...?" "Why does...?" — all answered
Help	Something broke? Start here. We'll fix it together.

Understanding AI in Kestrel:

Guide	What you'll learn
How Kestrel Uses AI	The electricity analogy — what AI providers are, what they cost, and which to pick
AI Provider Setup	Technical details — API keys, privacy policies, provider comparison tables
LLM Landscape Research	Deep dive — 2026 pricing, privacy audits, GDPR, EU sovereignty (for the curious)

How it works under the hood:

Guide	What you'll learn
How Scoring Works	What "fit score" actually means, and how Kestrel decides which jobs match you
How Testing Works	2,800+ automated checks — the kitchen analogy for quality assurance

Going deeper:

Guide	What you'll learn
Comparison	How Kestrel stacks up against Huntr, Teal, Simplify, and others
Features & API Reference	Full feature list, architecture, CLI, and API endpoints
Deployment	Host Kestrel on Railway, Fly.io, or your own VPS
Contributing	Development setup and pull request guidelines

---

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.

Option	Cost	Privacy	Speed	Best for
Demo Mode	Free	Perfect	Instant	Exploring before committing
OpenRouter (free tier)	$0/mo	Good	Varies	Start here — Llama 3.3 70B scores jobs for free
OpenRouter (paid models)	$1-30+/mo	Good	Varies	Premium models (Claude, GPT). Cost depends on model and volume — see note below
Anthropic (Claude)	$1-10/mo	Excellent	~200ms	Best quality + prompt caching savings. Can spike if scoring high volumes without caching
Together AI	~$1-5/mo	Good (ZDR available)	~213ms	Budget-friendly bulk scoring
Ollama	Free	Perfect	Depends on hardware	Nothing leaves your machine, ever

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.

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:

What Kestrel does	How it helps	Savings
Prompt caching	Your profile is sent once, then "remembered" by the API. Scoring 50 jobs doesn't resend your CV 50 times.	92% on repeat calls
Compressed prompts	Scoring instructions use telegraphic notation — same info, fewer words. The AI reads shorthand just fine.	29% on system prompts
Compact serialization	Your profile is sent without pretty-printing whitespace. {"name":"Jane"} instead of { "name": "Jane" }.	23% on profile data
Response caching	Asked the same question twice? Kestrel serves it from local encrypted cache. Zero API calls.	100% (free)
Token-efficient tool use	When Kestrel calls AI tools, it uses a compact format that cuts output size.	70% off output tokens
Smart model selection	Not every task needs the biggest brain. Simple classification uses a smaller model. Deep analysis uses the full thing.	60-95% on simple tasks
Batch scoring	Scoring a big backlog overnight? Batch APIs give a flat 50% discount for non-urgent work.	50% off everything
Provider fallback	If one provider's quota runs out, Kestrel automatically tries the next one. No failed scores, no wasted retries.	Resilience (not cost)

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 →

Benchmark: 50-job scoring batch, same user

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

The job description is ~60% of each call and can't be cached (it's different every time). The 92% savings apply to the other 40% — like speeding up the highway portion of your commute.

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.

Topic	For users	For developers	Raw research
Scoring	How Scoring Works	Scoring Strategy	Raw Findings
Testing	How Testing Works	Testing Strategy	Raw Findings
CI/CD	How CI/CD Works	CI/CD Strategy	Raw Findings
Observability	How Observability Works	Observability Strategy	Setup Guide
Token Optimization	How Token Optimization Works	Strategy & Implementation	Raw Findings
LLM Research Corpus	Quick Wins	Tools & Strategies	52 Papers + Sources

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.