# How to Set Up the AI Job Search Framework: A Complete Installation Guide

> Install the AI Job Search framework easily. Follow our comprehensive guide to clone the repository, set up dependencies, and configure your profile for AI powered job applications.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-07-20

---

**To set up the AI Job Search framework, clone the repository, install dependencies from [`requirements.txt`](https://github.com/MadsLorentzen/ai-job-search/blob/main/requirements.txt), configure your canonical candidate profile in [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and the `.claude/skills/job-application-assistant/` directory, then run the initialization command `python -m claude.commands.setup` to validate your profile and initialise the SQLite database before executing the job-search pipeline.**

This guide walks you through installing and configuring the AI Job Search framework (MadsLorentzen/ai-job-search), a modular system built on a **thin-pointer architecture** that separates candidate data from workflow logic. By centralizing your résumé, preferences, and writing style in version-controlled markdown files, you can orchestrate automated scraping, ranking, and application submission across multiple job portals without duplicating configuration.

## Phase 1: Install Core Dependencies

Begin by cloning the repository and preparing your Python environment. The framework requires only standard data-science and web-scraping libraries defined in the root-level dependency manifest.

Clone the repository and navigate into the directory:

```bash
git clone https://github.com/MadsLorentzen/ai-job-search.git
cd ai-job-search

```

Create a virtual environment and install the required packages listed in [[`requirements.txt`](https://github.com/MadsLorentzen/ai-job-search/blob/main/requirements.txt)](https://github.com/MadsLorentzen/ai-job-search/blob/master/requirements.txt):

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

```

Verify the installation by running the test suite located in the `tests/` folder:

```bash
pytest -q

```

All tests should pass; failures typically indicate missing system libraries (for example, `poppler` for PDF processing) that must be installed separately.

## Phase 2: Initialise the Candidate Profile

The framework uses a **thin-pointer design** where every component references a single canonical profile, eliminating data duplication. You must populate two locations: the root profile and the detailed skill specifications.

First, open [[`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/CLAUDE.md) and replace the placeholders with your personal information, including contact details, education history, and target job preferences. This file serves as the primary source of truth for all downstream automation.

Next, review the modular skill definitions in `.claude/skills/job-application-assistant/`. These files are numbered to reflect the workflow pipeline:

- [[`01-candidate-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/01-candidate-profile.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/01-candidate-profile.md) — Base biographical data and career objectives.
- [[`02-behavioral-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/02-behavioral-profile.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/02-behavioral-profile.md) — Interview tone and communication style.
- [[`03-writing-style.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/03-writing-style.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/03-writing-style.md) — Language preferences for cover letters and emails.
- [[`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/04-job-evaluation.md) — Scoring criteria for ranking job postings.
- [[`05-cv-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/05-cv-templates.md) — LaTeX template selection and formatting rules.
- [[`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/06-cover-letter-templates.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/06-cover-letter-templates.md) — Cover letter structure and paragraph logic.
- [[`07-interview-prep.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/07-interview-prep.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/skills/job-application-assistant/07-interview-prep.md) — Preparation checklists and question banks.

Because the framework reads these files at runtime, any edit you make automatically propagates to the scraper, ranker, and application modules.

## Phase 3: Configure and Activate the Workflow

### Register Portal Agents

Portal-specific scrapers are located under `.agents/skills/`. Each agent contains a [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) file that instructs the orchestrator how to invoke site-specific search logic.

For example, the LinkedIn integration is defined in [[`.agents/skills/linkedin-search/url-reference.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/linkedin-search/url-reference.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.agents/skills/linkedin-search/url-reference.md). To add a new job board, create a sibling directory following the same schema and reference it in your execution commands.

### Run the Setup Command

The [[`setup.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/setup.md)](https://github.com/MadsLorentzen/ai-job-search/blob/master/.claude/commands/setup.md) command performs three critical tasks:

1. **Validates** the candidate profile against required field schemas.
2. **Initialises** the SQLite job database (`jobs.db`) used for storing and ranking scraped postings.
3. **Creates** [`.claude/state.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/state.json), a flag file indicating the framework is ready for execution.

Run the initialization from the repository root:

```bash
python -m claude.commands.setup

```

If validation succeeds, you will see a confirmation message and the [`state.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/state.json) file will contain a `"ready": true` entry.

### Start the Job-Search Loop

With the database initialised, execute the full pipeline in sequence:

```bash

# Scrape postings from all registered portal agents

python -m claude.commands.scrape

# Rank results against your 04-job-evaluation.md criteria

python -m claude.commands.rank

# Generate applications for top-ranked jobs (manual review recommended)

python -m claude.commands.apply

# Fetch recommended courses and certifications

python -m claude.commands.upskill

# Generate interview preparation materials

python -m claude.commands.interview

```

Each command reads from the thin-pointer profile files, ensuring consistent voice and data across every stage.

## Phase 4: Optional Extras

Extend the framework with these supplementary utilities:

- **HTML Reports:** Generate a visual dashboard of your pipeline status with `python -m claude.commands.html-report`. Output is written to the `reports/` directory.
- **Notion Integration:** Synchronise your `jobs.db` with a Notion database using `python -m claude.commands.notion-sync`. Configure your API token in the command’s dedicated markdown file.
- **Salary Enrichment:** Run [[`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py)](https://github.com/MadsLorentzen/ai-job-search/blob/master/salary_lookup.py) against scraped postings to append market-rate compensation data before ranking, enabling more informed decision-making.

## Summary

- **Install** the framework via `pip install -r requirements.txt` and verify with `pytest -q`.
- **Configure** your canonical profile in [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and the seven numbered files under `.claude/skills/job-application-assistant/`.
- **Initialise** the SQLite database and validate settings by running `python -m claude.commands.setup`.
- **Execute** the pipeline (`scrape` → `rank` → `apply` → `upskill` → `interview`) to automate your job search while maintaining full editorial control through markdown-based configuration.

## Frequently Asked Questions

### What is the thin-pointer architecture used by this framework?

The thin-pointer architecture centralises all candidate-specific data—such as contact details, writing style, and job preferences—into a small set of markdown files (primarily [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and the skill modules). Instead of hard-coding variables into Python scripts, each command reads these files at runtime, ensuring that a single change to your profile automatically updates every downstream process from scraping to interview preparation.

### How do I add support for a new job portal?

Create a new subdirectory under [`.agents/skills/`](https://github.com/MadsLorentzen/ai-job-search/tree/master/.agents/skills) named after the portal (for example, `indeed-search/`), and add a [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) file that defines the portal’s URL structure, pagination logic, and CSS selectors. The orchestrator discovers these agents dynamically at startup, allowing you to include the new portal in the next `scrape` cycle without modifying core framework code.

### Where does the framework store job postings and rankings?

All scraped data persists in a local SQLite database named `jobs.db`, created during the `setup` phase. This file stores raw job descriptions, parsed metadata, and your custom ranking scores. The database path is configurable, but defaults to the repository root, making it easy to backup, version-control (via `.gitignore` exclusion), or sync to external services like Notion.

### How do I verify that I have correctly set up the AI Job Search framework?

After running `python -m claude.commands.setup`, check for the existence of [`.claude/state.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/state.json) containing a `"ready": true` flag. Additionally, running `pytest -q` should report zero failures, and the `jobs.db` file should appear in your directory. If these three conditions are met—valid state file, passing tests, and initialised database—the framework is correctly configured and ready to execute pipeline commands.