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

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

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

# 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, use the GitHub CLI to maintain the upstream remote for future updates:

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:

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. This process creates structured Markdown files under .claude/skills/job-application-assistant/ (including 01-candidate-profile.md and 04-job-evaluation.md) and a LaTeX CV template at cv/main_example.tex:

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 converts Excel spreadsheets into salary_data.json for use by the /apply command during job applications:

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 and tools/upstream_triage.py. These scripts compare framework_version stamps in your personalized files against the upstream repository:

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:

/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 and triage updates using 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}