AI-Job-Search Codebase Structure: Understanding the Repository Layout

The ai-job-search repository separates core AI workflows, job portal integrations, and user assets into a thin-pointer architecture that enables reproducible application pipelines via Claude Code commands.

The MadsLorentzen/ai-job-search repository implements a structured framework for AI-assisted job searching. Understanding the ai-job-search codebase structure reveals a deliberate separation between workflow definitions in .claude/, external tool integrations in .agents/, and personal document assets. This design allows users to maintain sensitive candidate data in private forks while leveraging shared automation logic and LaTeX templates.

Core Workflow Definitions (.claude/)

The .claude/ directory contains the central nervous system of the application, defining how Claude Code agents execute job search workflows.

Skill Definitions and Workflow Rules

The primary skill definition resides in .claude/skills/job-application-assistant/SKILL.md. This file declares the job-application-assistant skill, describing its allowed tools and the step-by-step workflow covering research, CV tailoring, cover-letter drafting, and interview preparation. The skill references seven supporting files that define specific evaluation criteria and persona configurations.

During the onboarding process, the /setup command defined in .claude/commands/setup.md reads source materials from the documents/ folder and populates these skill files, ultimately generating the master CLAUDE.md candidate profile.

Command Specifications

Each slash command available to users exists as a Markdown file under .claude/commands/:

• setup.md - Implements the onboarding wizard with Path A, B, and C workflows
• apply.md - Orchestrates the full application pipeline from parsing to PDF compilation
• rank.md - Provides job ranking functionality

These files contain exact procedural steps the agent must follow when invoked, effectively serving as executable documentation.

Permission Manifest

The .claude/settings.json file lists tools the Claude Code runtime may invoke, including Read, Glob, WebFetch, and others. This enforces the thin-pointer security model by explicitly declaring permissible system interactions.

Portal-Specific Search Tools (.agents/skills/)

The .agents/skills/ directory houses self-contained CLI integrations for individual job boards. Each portal skill follows a common contract implementing search and detail commands, an enabled: flag in its SKILL.md, and support for JSON, table, or plain text output.

The repository includes integrations for:

• Jobbank (Denmark) - .agents/skills/jobbank-search for public-sector positions
• Jobdanmark (Denmark) - .agents/skills/jobdanmark-search for national employment services
• Jobindex (Denmark) - .agents/skills/jobindex-search for private aggregator listings
• Jobnet (Denmark) - .agents/skills/jobnet-search for government portals
• LinkedIn (Global) - .agents/skills/linkedin-search using guest-mode API with zero dependencies
• freehire (Global) - .agents/skills/freehire-search for tech-focused REST API aggregation

The /scrape command auto-discovers any enabled skills in this directory, executing searches across all active portals and deduplicating results based on the scoring framework defined in 04-job-evaluation.md.

User-Facing Document Assets

LaTeX Templates

The cv/ and cover_letters/ directories contain professional typesetting templates. The cv/main_example.tex file provides a moderncv-based curriculum vitae template, while cover_letters/cover.cls defines a custom LaTeX class for cover letters with accompanying example documents. The /apply command renders these templates using candidate-specific data extracted during setup.

Source Material Archive

The documents/ folder serves as the user-facing intake for raw materials. As specified in documents/README.md, this directory holds CV PDFs, LinkedIn data exports, diplomas, reference letters, and archives of past applications. The /setup command validates and indexes these files to populate the AI workflow memory.

Utility Tools and Testing Infrastructure

The tools/ directory contains helper scripts supporting the automation pipeline. The tools/verify_pdf.py script performs ATS compatibility checks by verifying PDF layout and extractable text. Additional utilities include check_upstream_updates.py for safe repository synchronization.

The tests/ directory maintains pytest suites verifying correctness for every command and tool, including integration tests like test_apply_records_application.py that validate the end-to-end application recording workflow.

Runtime State and Persistence

The repository maintains operational state in two key locations:

• job_scraper/ - Stores transient scraper cache including seen_jobs.json and temporary search results
• job_search_tracker.csv - Persistent CSV dashboard summarizing all applications, outcomes, and pipeline status

These files enable the system to maintain continuity across sessions while keeping sensitive tracking data under user control.

Executing Core Workflows

The ai-job-search codebase structure supports several key operational commands. To initialize the system, users run the onboarding flow:

claude          # start Claude Code REPL

/setup          # invoke the /setup command – chooses Path A, B, or C automatically

This populates the skill files and generates CLAUDE.md from the documents/ folder.

To search across all enabled job portals:

/scrape

This discovers enabled skills in .agents/skills/, executes searches, and presents ranked results.

To apply to a specific posting:

/apply https://jobindex.dk/job/1234567

This executes the full pipeline: parsing the posting, evaluating fit, drafting LaTeX documents, running ATS verification via verify_pdf.py, and returning final PDFs with a completion checklist.

Summary

• The ai-job-search codebase structure follows a thin-pointer architecture separating AI workflows, portal integrations, and user data
• Workflow definitions live in .claude/ including skill manifests, command specifications, and security settings
• Job portal integrations reside in .agents/skills/ with standardized CLI contracts for Danish and global job boards
• Document generation relies on LaTeX templates in cv/ and cover_letters/ with ATS verification via tools/verify_pdf.py
• User materials are isolated in documents/ and tracked via job_search_tracker.csv, enabling private fork workflows

Frequently Asked Questions

What is the purpose of the .claude/settings.json file?

The .claude/settings.json file serves as the permission manifest for the Claude Code runtime. It explicitly lists which tools the AI agent may invoke, such as Read, Glob, and WebFetch, enforcing the repository's thin-pointer security model by restricting system access to declared capabilities only.

How does the repository handle different job portals uniformly?

Each job portal integration in .agents/skills/ implements a common contract defined in its respective SKILL.md file. This contract requires implementing search and detail commands, maintaining an enabled: configuration flag, and supporting multiple output formats including JSON, table, and plain text. The /scrape command auto-discovers these skills and executes them through a standardized interface.

Where is sensitive candidate data stored in the ai-job-search codebase?

Sensitive candidate data resides in the documents/ folder and the generated CLAUDE.md file. The repository architecture intentionally separates this user-specific content from shared automation logic, allowing users to maintain private forks containing personal data while continuing to pull updates from the upstream MadsLorentzen/ai-job-search repository.

What testing infrastructure ensures the reliability of automation commands?

The tests/ directory contains comprehensive pytest suites covering unit and integration tests for all commands and tools. For example, test_apply_records_application.py validates that the /apply command correctly records application metadata, ensuring CI reliability and preventing regression in the job application pipeline.

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