Purpose of the `src` Directory in ai-job-search: Modular CLI Architecture

The src directory in ai-job-search contains the TypeScript source code that implements standalone command-line interfaces (CLIs) for each job portal agent, housing the business logic, commands, API wrappers, and parsing utilities required to automate job searches across platforms like LinkedIn, Jobnet, and Freehire.

The ai-job-search repository organizes its automation capabilities through modular agent skills, where the purpose of the src directory is to serve as the command center for portal-specific operations. Located within the hidden .agents/skills/{portal-name}/cli/ hierarchy, these directories transform high-level workflow instructions defined in .claude/ files into executable commands for scraping and querying job listings.

Location and Structure of the src Directory

Each job portal integration exists as a separate skill with its own src folder under .agents/skills/, followed by the portal identifier and /cli/src/. For example, the LinkedIn agent resides at .agents/skills/linkedin-search/cli/src/, while the Jobnet agent uses .agents/skills/jobnet-search/cli/src/. This separation ensures that portal-specific scraping logic remains isolated and maintainable.

Standard Internal Layout

Every src directory follows a consistent architectural pattern that supports the Bun runtime:

• cli.ts – The entry point that defines the CLI interface, argument parsing, and command routing.
• commands/ – Individual command modules including search.ts, detail.ts, and occupations.ts, each encapsulating specific operations like querying listings or retrieving job details.
• helpers/ – Reusable utilities for HTTP fetching, HTML parsing, rate limiting, and data normalization (e.g., apiFetch.ts, parseJobCards.ts).
• types/ – TypeScript interfaces and type definitions for API responses, job objects, and command option schemas.
• tests/ – Unit and integration tests validating CLI behavior, typically located alongside the source files.

Core Implementation Files

The src directories house all business logic that powers the automated job-search agents, while higher-level orchestration merely invokes these standalone CLIs. This architecture keeps concerns separated and allows each portal integration to function independently.

Entry Point: cli.ts

In each skill's cli.ts file—such as .agents/skills/linkedin-search/cli/src/cli.ts—the command-line interface is constructed for Bun execution. This file bootstraps the argument parser and dispatches to the appropriate command handler, enabling patterns like bun run src/cli.ts search [options].

Command Modules

The commands/ subdirectory contains operation-specific implementations that handle distinct user intents:

• search.ts – Processes job queries across all supported portals, handling parameters like query strings (-q), locations (-l), job age filters (--jobage), and output formats (--format).
• detail.ts – Retrieves comprehensive job posting information using unique identifiers, such as fetching a specific Jobnet listing by UUID.
• occupations.ts – Lists available job categories and occupations for platforms like Freehire, supporting filtering via --search-string and pagination via --per-page.

Helper Utilities

Reusable scraping and API logic resides in helpers/ to prevent code duplication across commands:

• parseJobCards.ts (LinkedIn) – Extracts structured job data from HTML responses, processing card elements into standardized objects.
• apiFetch.ts (Jobnet, Jobbank) – Manages authenticated HTTP requests, response handling, and error normalization for JSON-based APIs.
• htmlFetch.ts (Freehire) – Handles raw HTML retrieval for subsequent parsing operations.
• parseSearchPage.ts (Jobindex) – Processes search result pages into iterable job listings.

Executing Commands from the src Directory

Practical usage requires running TypeScript files directly through Bun, targeting the specific skill's cli.ts entry point. The src directory structure supports immediate execution without separate compilation steps.

Searching LinkedIn for backend positions:

bun run .agents/skills/linkedin-search/cli/src/cli.ts search \
    -q "backend engineer" \
    -l "Remote" \
    --jobage 30 \
    --format table

Fetching detailed job information from Jobnet using a specific job ID:

bun run .agents/skills/jobnet-search/cli/src/cli.ts detail 9ef43bce-d82b-4ea1-a098-7ff6520f99be \
    --format json

Querying occupations through Freehire with pagination:

bun run .agents/skills/freehire-search/cli/src/cli.ts occupations \
    --search-string "sygeplejerske" \
    --per-page 5

Portal-Specific Source Implementations

The repository maintains dedicated src directories for each integrated job portal, each containing similar structural patterns but portal-specific implementation details:

LinkedIn Search

• Key files: cli.ts, commands/search.ts, helpers/parseJobCards.ts
• Path: .agents/skills/linkedin-search/cli/src/

Jobnet Search

• Key files: cli.ts, commands/search.ts, helpers/apiFetch.ts
• Path: .agents/skills/jobnet-search/cli/src/

Freehire Search

• Key files: cli.ts, commands/search.ts, helpers/htmlFetch.ts
• Path: .agents/skills/freehire-search/cli/src/

Jobindex Search

• Key files: cli.ts, commands/search.ts, helpers/parseSearchPage.ts
• Path: .agents/skills/jobindex-search/cli/src/

Jobbank Search

• Key files: cli.ts, commands/search.ts, helpers/apiFetch.ts
• Path: .agents/skills/jobbank-search/cli/src/

Summary

• The src directory in ai-job-search acts as the implementation layer for TypeScript-based CLI agents, located at .agents/skills/{portal}/cli/src/.
• Each directory isolates portal-specific business logic through standardized subdirectories: commands/ for operation handlers, helpers/ for utilities, and types/ for TypeScript definitions.
• Entry points in cli.ts enable direct Bun execution: bun run .agents/skills/linkedin-search/cli/src/cli.ts.
• This modular architecture separates scraping concerns from workflow orchestration, allowing independent development, testing, and maintenance of each job portal integration.

Frequently Asked Questions

Where is the src directory located in ai-job-search?

The src directory resides within each agent skill at .agents/skills/{skill-name}/cli/src/, where {skill-name} represents specific portals such as linkedin-search, jobnet-search, freehire-search, jobindex-search, or jobbank-search.

What programming language is used in the src directories?

All src directories contain TypeScript source code executed through the Bun runtime. This includes the main entry point cli.ts, command modules like search.ts and detail.ts, and helper utilities such as apiFetch.ts and parseJobCards.ts.

How do I run commands using files in the src directory?

Execute commands by targeting the skill's cli.ts entry point with Bun. For example: bun run .agents/skills/linkedin-search/cli/src/cli.ts search -q "data engineer" -l "Berlin, Germany" --format table. The CLI arguments are passed directly to the TypeScript implementation in src/cli.ts.

Why does each job portal have its own src directory?

This separation isolates portal-specific scraping logic, API wrappers, and authentication mechanisms. It enables developers to add new job portals without affecting existing implementations, and allows the repository to treat each integration as a standalone CLI tool that can be invoked independently or composed into larger automated workflows.

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