What Is the Backend Development Framework for ai-job-search?

The ai-job-search repository uses Claude Code as its primary backend development framework, orchestrating agentic workflows rather than running a traditional web server like Flask or Django.

The ai-job-search project is an AI-powered job application automation system that leverages the Claude Code framework as its core backend infrastructure. Unlike conventional web applications that rely on HTTP servers and REST APIs, this repository treats Claude Code agents as the primary runtime, interpreting prompts and executing commands through a file-based skill architecture.

How Claude Code Functions as the Backend Framework

According to the repository's README.md (lines 15-16), the project is explicitly described as "An AI-powered job application framework built on [Claude Code]". This declaration establishes Claude Code not merely as a development tool, but as the actual runtime environment that powers the application's backend logic.

The AGENTS.md file documents this architecture with a framework_version: 1.0.0 marker and introduces a thin-pointer design principle. As implemented in MadsLorentzen/ai-job-search, this design mandates that all agent runtimes load canonical specifications from files rather than hardcoding logic, making the repository itself the single source of truth.

Command and Skill Architecture

The backend operates through a hierarchy of commands and skills stored in the .claude/ directory. This directory contains the Claude Code skill definitions that drive all backend behavior:

• .claude/commands/setup.md – Defines the /setup onboarding command that initializes the job search environment.
• .claude/commands/ – Contains additional command definitions for /scrape, /apply, and /interview workflows.
• .claude/skills/job-application-assistant/SKILL.md – Houses the skill specification that drives the core job-application pipeline.

When you invoke a command like /setup, the Claude Code backend reads these markdown specifications and executes the corresponding workflow by manipulating repository files and invoking external tools.

Integration with Python and Bun-Based Tools

While Claude Code serves as the primary orchestration layer, the backend integrates auxiliary utilities written in Python and JavaScript. The framework invokes these tools as subprocesses rather than hosting them as long-running services:

# Example: invoking the /setup command via Python subprocess

import subprocess

# Assumes Claude Code CLI is installed and authenticated

subprocess.run(["claude", "/setup"], check=True)

For job portal interactions, the backend calls Bun-based CLI tools located in .agents/skills/ directories:

# Navigate to a specific skill's CLI directory

cd .agents/skills/linkedin-search/cli
bun run search --query "data scientist" --location "Berlin, Germany"

These JavaScript utilities handle specific scraping and search tasks, but remain subservient to the Claude Code agent that coordinates the overall workflow.

Framework Version Validation and CI

The repository includes guard rails to ensure compatibility with the expected Claude Code framework version. The file tools/check_framework_version.py serves as a CI validation tool that checks for the framework_version markers in AGENTS.md and other configuration files. This ensures that the thin-pointer design remains intact and that agents can properly locate their skill specifications.

Summary

• Claude Code serves as the primary backend development framework for ai-job-search, replacing traditional web servers like Flask or FastAPI.
• The backend uses a file-based architecture where commands and skills are defined in the .claude/ directory and interpreted by Claude Code agents.
• No HTTP server runs continuously; instead, workflows are triggered through Claude Code commands such as /setup, /scrape, /apply, and /interview.
• Supporting tools written in Python and Bun (JavaScript) are invoked as subprocesses by the Claude Code agents to perform specific tasks like job portal scraping.
• The AGENTS.md file maintains the canonical framework_version: 1.0.0 and enforces a thin-pointer design pattern.

Frequently Asked Questions

Does ai-job-search use Flask or Django for its backend?

No. According to the source code analysis of the repository, ai-job-search does not use Flask, Django, FastAPI, or any traditional Python web framework. Instead, it relies on the Claude Code agentic framework to orchestrate workflows. The backend logic is executed by Claude Code agents that read skill definitions from files and invoke helper scripts as needed.

What is the thin-pointer design mentioned in the AGENTS.md file?

The thin-pointer design is an architectural pattern documented in AGENTS.md (lines 2-9) that requires all agent runtimes to load canonical specifications from files rather than embedding logic directly in the agents. This design treats the repository files as the single source of truth. It allows the Claude Code backend to remain flexible and version-controlled through standard Git workflows.

How do I run the ai-job-search backend locally?

To run the backend, you need the Claude Code CLI installed and authenticated. Once installed, you can invoke commands like claude /setup from the repository root. The Claude Code agent will then read the command definitions from .claude/commands/ and execute the appropriate workflows, potentially calling Bun-based tools in .agents/skills/ if the workflow requires job portal scraping.

What version of the Claude Code framework does ai-job-search require?

The repository specifies framework_version: 1.0.0 in the AGENTS.md file. The CI pipeline validates this version using tools/check_framework_version.py to ensure compatibility. You should use a Claude Code version that supports this framework specification to ensure the thin-pointer design functions correctly.

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