how-to-guide

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

July 20, 2026 MadsLorentzen/ai-job-search ↗

To set up the AI Job Search framework, clone the repository, install dependencies from requirements.txt, configure your canonical candidate profile in 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:

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/master/requirements.txt):

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:

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/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:

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 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/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/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, a flag file indicating the framework is ready for execution.

Run the initialization from the repository root:

python -m claude.commands.setup

If validation succeeds, you will see a confirmation message and the state.json file will contain a "ready": true entry.

Start the Job-Search Loop

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


# 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/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 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 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/ named after the portal (for example, indeed-search/), and add a 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 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →