Stellenpilot

Your local AI job assistant. Open source, private, and on autopilot.

Stellenpilot is an AI agent for your job search that runs on your own computer. Every morning it finds new jobs, an AI reads each one against your CV, tells you honestly how well it fits, and writes a tailored CV and cover letter for the best matches. When you open the dashboard, the work is done: you read, decide and send.

It comes with its own free built-in AI, so you need no account, no API key and no cloud. Your CV never leaves your computer. Built for the job market in Germany, and it works in other countries too.

_{All names, companies and jobs in this demo are fictional.}

pip install stellenpilot
stellenpilot serve

Open http://127.0.0.1:8765. Setup takes a few minutes, plus the one time AI download: drop your CV, say what you are looking for, press Download for the built-in AI, and switch on the daily search. Windows, macOS and Linux, Python 3.11 or newer.

How it works

flowchart LR
    A["🔎 Collect<br/>6 job sources<br/>+ 200 company sites"] --> B["🧠 AI scores<br/>each job 0 to 100<br/>with reasons and gaps"]
    B --> C["✍️ AI writes<br/>tailored CV and<br/>cover letter"]
    C --> D["📬 Gmail tracks<br/>replies and moves<br/>statuses forward"]
    D --> E["✅ You decide<br/>read, edit, send"]

Every day, by itself:

1. Collect. Stellenpilot searches the Bundesagentur für Arbeit, Arbeitnow, Adzuna, TheirStack, Jobicy and Remotive, plus the career pages of about 200 companies with offices in Germany. Duplicates are removed.
2. Score. The AI reads each ad against your CV and gives a match from 0 to 100, a short reason, and the honest gaps. It reads which German level the ad really asks for and skips ads far above yours.
3. Write. For the best matches it writes a CV and a cover letter tailored to that job, using only facts from your CV, as Word files and PDF.
4. Track. With Gmail connected, confirmations, interview invitations and rejections move each application forward on their own. Interviews get a prep pack.
5. Report. The dashboard (and, if you like, a Telegram or email digest) shows what is ready to send today.

It never applies for you and never contacts a company. The agent prepares; you stay in control of every application.

The AI

What the AI does for you

• Reads your CV. Drop a PDF or Word file and the AI turns it into a structured profile. Every bullet is checked against your original, and anything left out or made up is flagged.
• Scores every job from 0 to 100 with a one line reason and the honest gaps (for example "asks for dbt, which you are still learning").
• Understands German job ads. It finds the German level an ad really needs (A1 to C2, from phrases like "verhandlungssicher" or "gute Deutschkenntnisse"), compares it with yours, and writes an English summary of every German ad.
• Tailors your CV. It picks and orders the experience, projects and skills from your profile that matter most for this job, and chooses the best fitting headline.
• Writes the cover letter in natural language for that company and role, plus a short report: what the ad asks for, what you cover, and which gaps to be honest about. German letters only if your German is B2 or better.
• Prepares interviews with likely questions and questions to ask them.
• Learns your taste. Mark jobs as a good match or not for you, and the next search leans toward what you liked.

Truthful by design

A job assistant that invents experience gets people into trouble. Stellenpilot has a truth guard: any generated sentence that mentions a number, a tool or a language level your profile does not back up is rejected and replaced with safe text. Skills in a group called "Learning" are never presented as experience. The AI rephrases and selects; it never adds facts.

Choose your AI

Built-in AI is the default for new users. Pick it in setup or in Settings, AI model and press Download. Stellenpilot downloads the llama.cpp engine and an open Qwen3.5 model (Apache 2.0) once, into ~/.stellenpilot/ai. It starts by itself when a search needs it and stops when the search is done.

How fast is it? It runs on your processor, so it is slower than Claude, but free and private:

• Standard on a typical laptop: about 20 to 40 seconds to score one job, and 1 to 2 minutes for a CV with its cover letter. Light is about twice as fast.
• To keep searches short, an AI on your own computer reads the 20 most promising new jobs of each search (picked by keywords); the others keep a keyword score. Change it with max_ai_jobs under [llm].
• A daily search with the AI takes about 10 to 20 minutes with Standard, or 5 to 10 with Light, in the background. Without AI it takes a minute or two.
• Measured on our small test server with only 2 processor cores: Standard needed 67 seconds per job and 2 minutes per CV and letter; Light 32 seconds and about 1 minute. Older laptops can be that slow; newer ones and Macs with Apple chips are faster.
• After the download, Test speed in Settings measures your own computer.

The laptop figures are estimates from published CPU benchmarks for these model sizes, not measured on every computer.

Automation

• Daily autopilot. Switch on Automatic search in Settings and pick a time. Stellenpilot sets up Task Scheduler on Windows or cron on macOS and Linux for you. The dashboard does not need to be open. A search missed because the computer was off runs when you log in or open Stellenpilot. Doing it by hand: docs/scheduling.md.
• Company watchlist. Switch on the ready made list of about 200 companies with offices in Germany, or add your dream companies that use Greenhouse, Lever, Ashby, Personio or SmartRecruiters. Their new roles often appear here before they reach the job boards.
• Gmail sync. Read only. Connect it in Settings, Gmail in three steps, and statuses move forward as replies arrive. It never sends, deletes or labels mail. Details: docs/gmail.md.
• Daily digest to Telegram or email: top new matches, documents ready to send, interviews. See docs/digest.md.
• Jobs you found yourself. Paste a link or the ad text from LinkedIn, a friend or anywhere, and the AI scores and tailors it like the rest.

The dashboard

Five calm pages, in your browser, on your computer:

• Home: what is ready to apply, interviews coming up, the newest matches, and a small 3D office where you can watch the agent work.
• Jobs: every job with its score, why it fits, honest gaps, your documents, notes and interview prep.
• Applications: a board you drag cards across (Applied, Interview, Offer, Rejected), with reply rates by source, the skill gaps employers mention most, and a weekly summary.
• My CV: your profile, with tips to improve your matches.
• Settings: job sources, the AI, the daily search and Gmail, with step by step help for every key.

Install

New to Python or the terminal? Follow INSTALL.md: step by step for Windows, macOS, Linux and Docker, from installing Python to your first search.

pip install stellenpilot
mkdir my-hunt
cd my-hunt
stellenpilot serve      # open http://127.0.0.1:8765, setup opens by itself

"stellenpilot is not recognized"? pip put the command in a folder that is not on your PATH. Use python -m stellenpilot serve instead (python3 on macOS and Linux). That always works.

Update with pip install -U stellenpilot. Your files in my-hunt are never touched by an update.

git clone https://github.com/srvskr1/stellenpilot.git
cd stellenpilot
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS or Linux: source .venv/bin/activate
pip install -e .

mkdir my-hunt
cd my-hunt
stellenpilot init      # creates config.toml, profile.toml and .env
stellenpilot demo      # optional: fictional sample jobs, to look around first
stellenpilot serve     # open http://127.0.0.1:8765

mkdir data
docker compose build
docker compose run --rm stellenpilot init
docker compose up -d      # http://127.0.0.1:8765

Prefer files to the dashboard? Everything also lives in profile.toml, config.toml and .env, stellenpilot run searches from the terminal, and stellenpilot doctor checks the setup.

Job sources

There is no LinkedIn, StepStone or Indeed scraper on purpose. LinkedIn's and StepStone's terms forbid scraping, and Indeed has no public job search API. See docs/sources.md for the details and links.

Other countries: set country in config.toml. Adzuna covers 19 countries, Jobicy and Remotive cover remote roles open to your country, TheirStack and the company watchlist cover any country, and the Bundesagentur and Arbeitnow cover Germany only.

Privacy and safety

• Local first. Everything is stored in jobhunt.db and the output folder next to your config, on your computer. With the built-in AI or another local model, nothing about you leaves it.
• With Claude or OpenAI, your profile and the job ads are sent to that provider.
• The dashboard listens on 127.0.0.1 only, and write requests need a custom header, so other websites cannot change your data through your browser.
• Read every document before you send it. The truth guard checks digits and the tools it knows (see VOCAB in stellenpilot/score.py). It cannot judge spelled out numbers or vague claims, so you are the final check.

Commands

Use --home PATH to keep your files in another folder.

Use --home PATH to keep your files in another folder.

Project layout

stellenpilot/
  sources/      one module per job API
  pipeline.py   the daily run: collect, score, tailor, Gmail
  score.py      LLM or keyword scoring, taste from your ratings
  tailor.py     truthful CV plan, DOCX, cover letter, report, PDF
  server.py     local dashboard API
  web/          dashboard page
  examples/     example config and profile
tests/          offline tests: python -m unittest discover -s tests

Uninstall completely

Do these steps in order. Steps 1 and 2 matter most: they stop the daily search before the program is gone.

1. Stop the dashboard. Press Ctrl+C in the terminal where stellenpilot serve runs (Docker: docker compose down).

2. Remove the automatic daily search, if you switched it on. Easiest: in the dashboard open Settings, switch off Search every day under Automatic search and press Save changes. If the dashboard is already gone:

• Windows (PowerShell): schtasks /Delete /TN "Stellenpilot daily search" /F
• macOS and Linux: run crontab -e and delete the line that ends with # jobhunt-daily

3. Remove the program.

• Installed with pip: activate the environment you installed it in, then pip uninstall stellenpilot. Delete that environment folder too if you made one just for it (for example stellenpilot-env or .venv).
• Installed from source: delete the stellenpilot folder you cloned or unzipped (the environment .venv is inside it).
• Docker: in the project folder run docker compose down, then docker rmi ghcr.io/srvskr1/stellenpilot (and docker image prune to free the space of any self built image).

4. Delete your data. Your workspace folder (my-hunt, or data for Docker) holds everything personal: your CV profile, .env with your API keys, the job database, the generated CVs and cover letters, run.log, backups and the Gmail token.json. Delete the whole folder. The only other place is the Built-in AI folder .stellenpilot in your home folder, if you downloaded it (see step 5).

5. Close your accounts and keys (optional, but good practice):

• API keys you created for it: delete them at Adzuna, TheirStack, Anthropic or OpenAI.
• Gmail sync: remove access at https://myaccount.google.com/permissions and delete the Google Cloud project you made for it.
• Telegram digest: send /deletebot to @BotFather.
• Built-in AI: press Remove the AI files in Settings, or delete the folder .stellenpilot in your home folder (C:\Users\<you>\.stellenpilot on Windows). It holds the engine and the model, about 1.5 to 4 GB.
• Ollama model: ollama rm qwen3.5:4b (or the model you pulled), and uninstall Ollama or LM Studio if you only used them for this.

LibreOffice and Python stay installed; remove them like any other app if you no longer need them.

Contributing

Issues and pull requests are welcome. New sources should use an official or clearly permitted API, follow the shape in stellenpilot/sources/__init__.py, and come with an offline test.

Credits and license

MIT, see LICENSE. Credits for ideas and data are in NOTICE.md. The built-in AI uses llama.cpp (MIT) and Qwen3.5 models (Apache 2.0), downloaded from their official sources.