# How to Set Up a Local Development Environment for ai-job-search: Complete Setup Guide

> Set up your ai-job-search local development environment with this complete guide. Install essential tools, clone the repo, and run the setup command for personalized configuration.

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

---

**You can set up a local development environment for ai-job-search by installing Claude Code, Python 3.10+, Bun, and a LaTeX distribution, then cloning the repository, installing CLI dependencies with `bun install`, and running the interactive `/setup` command to generate your personal configuration files.**

The ai-job-search repository by MadsLorentzen implements a thin-pointer design that separates executable tooling from personalized methodology files. This guide walks you through setting up a local development environment based on the canonical instructions in [`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md), covering prerequisite installation, repository configuration, and the Claude Code interview process that populates your candidate profile.

## Prerequisites for the ai-job-search Development Environment

Before cloning the repository, you must install four core runtime components. According to [`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md), these provide the execution environment for Claude-driven commands, salary-lookup helpers, TypeScript job-portal CLIs, and PDF generation pipelines.

### Install Claude Code

The framework requires **Claude Code** for the interactive setup interview and application workflow. Install it globally via npm:

```bash
npm install -g @anthropic-ai/claude-code

```

### Python 3.10+ Setup

**Python 3.10 or higher** is required specifically for the salary-lookup tool located at [`tools/convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/convert_salary_excel.py). Ensure your system Python meets this version requirement to process Excel-based salary data.

### Bun JavaScript Runtime

**Bun** serves as the runtime for the job-search CLIs. Install Bun using the official installer:

```bash

# macOS/Linux

curl -fsSL https://bun.sh/install | bash

```

For Windows, use the PowerShell installer available at `https://bun.sh/install`.

### LaTeX Distribution

A full **LaTeX distribution** (MiKTeX, MacTeX, or TeX Live) is required to compile generated CVs and cover letters. The framework uses `lualatex` for CV generation and `xelatex` for cover letters, as implemented in the document compilation pipeline.

## Repository Setup and Installation

### Fork and Clone the Repository

Start by forking the repository to your GitHub account and cloning it locally. As documented in [`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md), use the GitHub CLI to maintain the upstream remote for future updates:

```bash
gh repo fork MadsLorentzen/ai-job-search --clone
cd ai-job-search

```

### Install Portal CLI Dependencies

The repository includes TypeScript-based CLIs for Danish job portals (`jobbank-search`, `jobdanmark-search`, `jobindex-search`, `jobnet-search`) and generic tools (`linkedin-search`, `freehire-search`). Install dependencies for each portal:

```bash
for tool in jobbank-search jobdanmark-search jobindex-search jobnet-search linkedin-search freehire-search; do
  (cd .agents/skills/$tool/cli && bun install)
done

```

### Run the Interactive Setup Interview

Launch Claude Code and invoke the `/setup` command to begin the onboarding interview defined in [`.claude/commands/setup.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/setup.md). This process creates structured Markdown files under `.claude/skills/job-application-assistant/` (including [`01-candidate-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/01-candidate-profile.md) and [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md)) and a LaTeX CV template at `cv/main_example.tex`:

```bash
claude    # Start Claude Code REPL

/setup    # Start onboarding interview

```

## Optional Configuration and Extensions

### Configure Salary Benchmarking

The salary lookup tool at [`tools/convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/convert_salary_excel.py) converts Excel spreadsheets into [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) for use by the `/apply` command during job applications:

```bash
pip install openpyxl
python3 tools/convert_salary_excel.py path/to/salary.xlsx --source "My Salary Data 2025"

```

### Manage Upstream Updates

Track framework methodology changes using [`tools/check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_upstream_updates.py) and [`tools/upstream_triage.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/upstream_triage.py). These scripts compare `framework_version` stamps in your personalized files against the upstream repository:

```bash
python3 tools/check_upstream_updates.py
python3 tools/upstream_triage.py --remote upstream

```

### Add Custom LaTeX Templates

You can extend the framework with custom CV or cover letter templates using the `/add-template` command. This records your preferred compile engine and fonts in `.claude/skills/job-application-assistant/` before wiring the template into the `/apply` workflow.

## Testing Your Local Development Environment

Verify your ai-job-search development environment setup by processing a real job posting. The `/apply` command generates LaTeX files that you compile into submission-ready PDFs:

```bash
/apply https://jobindex.dk/job/1234567
cd cv && lualatex main_<company>_<role>.tex
cd ../cover_letters && xelatex cover_<company>_<role>.tex

```

## Summary

- **Install four prerequisites**: Claude Code, Python 3.10+, Bun, and a LaTeX distribution before cloning the repository.
- **Fork with GitHub CLI**: Use `gh repo fork MadsLorentzen/ai-job-search --clone` to maintain upstream remote access for methodology updates.
- **Install CLI dependencies** by running `bun install` in each portal's CLI directory under `.agents/skills/`.
- **Run the `/setup` interview** in Claude Code to generate personalized profile files under `.claude/skills/job-application-assistant/`.
- **Track upstream changes** with [`tools/check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_upstream_updates.py) and triage updates using [`tools/upstream_triage.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/upstream_triage.py) to keep your local environment current.

## Frequently Asked Questions

### What are the minimum system requirements for ai-job-search?

You need Claude Code installed globally via npm, Python 3.10 or higher for the salary conversion tools, Bun for executing TypeScript CLIs, and a full LaTeX distribution capable of running `lualatex` and `xelatex` commands for document generation.

### Where are my personal configuration files stored?

The `/setup` interview creates structured Markdown files under `.claude/skills/job-application-assistant/` (such as [`01-candidate-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/01-candidate-profile.md) and [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md)) and LaTeX templates in the `cv/` directory, keeping your personal data separate from the executable framework code.

### How do I update my local environment when the framework changes?

Run `python3 tools/check_upstream_updates.py` to detect `framework_version` mismatches between your files and the upstream repository, then use `python3 tools/upstream_triage.py --remote upstream` to generate cherry-pick commands for specific methodology updates.

### Can I use ai-job-search without Claude Code?

No. The framework relies on Claude Code for the interactive `/setup` interview, the `/apply` workflow that generates tailored applications, and the `/add-template` command for custom LaTeX integration. Claude Code serves as the primary interface for the thin-pointer architecture.