Bun Unavailability Fallback Mechanisms in the AI Job Search CLI

When the Bun runtime is unavailable, the AI Job Search CLI automatically falls back to a universal WebSearch strategy, bypassing all Bun-dependent portal scrapers while maintaining job retrieval capabilities across all supported platforms.

The ai-job-search repository by MadsLorentzen implements a robust job-scraper workflow that prioritizes runtime availability before executing portal-specific CLI tools. When the bun --version command fails or returns a non-zero exit code, the system gracefully degrades to web-based search methods rather than failing entirely, ensuring continuous job data retrieval regardless of local runtime configuration.

Detecting Bun Runtime Availability

The fallback mechanism initiates with an explicit availability check defined in the job-scraper skill. Before attempting to execute any portal-specific CLI tools, the system validates that the Bun JavaScript runtime is properly installed and accessible in the environment path.

The Version Check Command

According to the skill definition in .claude/skills/job-scraper/SKILL.md, the workflow executes the following validation:

# Step 1a – Check bun availability (inside the job-scraper skill)

bun --version || echo "bun not installed – falling back to WebSearch"

This command serves as the gatekeeper for the entire Bun-dependent execution path. If the command returns a non-zero exit code or the executable is not found in $PATH, the skill immediately transitions to the fallback protocol.

WebSearch Fallback Strategy

When Bun unavailability is detected, the job-scraper abandons all native CLI integrations in favor of a universal WebSearch approach. This fallback ensures that job listings remain accessible even when optimized runtime-specific scrapers cannot execute.

Skipping Bun-Based Portal CLIs

The fallback logic explicitly omits all portal-specific command-line tools that require Bun. These include:

• linkedin-search – LinkedIn job search CLI
• jobbank-search – Job Bank portal scraper
• jobnet-search – JobNet integration tool

As documented in the skill workflow, these tools are completely bypassed when the runtime check fails, preventing execution errors and dependency-related failures.

Universal Search Implementation

The system substitutes the native CLIs with generic WebSearch tool invocations using portal-specific query templates. The fallback logic operates as follows:

# Example of invoking the fallback (pseudo-code from the skill)

if ! command -v bun >/dev/null; then
  # Skip all bun CLIs, use generic web search for every portal

  for portal in "${PORTALS[@]}"; do
    WebSearch "search query for $portal"
  done
fi

Query templates for these fallback searches are maintained in .claude/skills/job-scraper/search-queries.md, ensuring that WebSearch queries remain optimized for each portal's specific search syntax even when CLI tools are unavailable.

Portal-Specific CLI Considerations

Individual portal CLIs in the .agents/skills/ directory are designed with fallback compatibility in mind. The linkedin-search CLI, documented in .agents/skills/linkedin-search/cli/README.md, runs with plain Bun and minimal dependencies, making the fallback transparent when Bun is present but non-critical when it is absent.

Conversely, the jobbank-search CLI, detailed in .agents/skills/jobbank-search/cli/README.md, includes explicit documentation regarding Cloudflare blocks and recommends using the WebSearch fallback when the CLI encounters retrieval barriers, reinforcing the reliability of the fallback mechanism.

Logging and Transparency

The job-scraper workflow includes explicit logging to ensure users understand when fallback mechanisms activate. Step 5 of the workflow records that a WebSearch fallback occurred, providing clear audit trails showing which data sources switched from native CLI scraping to web-based retrieval.

This transparency ensures that users can differentiate between Bun-optimized data (typically faster and more structured) and WebSearch-derived results (universally accessible but potentially less structured), allowing for appropriate adjustments to search strategies.

Summary

• Availability Check: The system runs bun --version before executing any portal CLIs, treating non-zero exits as Bun unavailability.
• Complete Bypass: All Bun-dependent tools including linkedin-search, jobbank-search, and jobnet-search are skipped when the runtime is missing.
• WebSearch Substitution: Generic WebSearch tool calls using templates from search-queries.md replace native CLI execution for universal compatibility.
• Audit Logging: Step 5 of the job-scraper workflow logs fallback activation, ensuring transparent operation tracking.
• Documentation: Fallback logic is explicitly defined in .claude/skills/job-scraper/SKILL.md and reinforced in individual portal README files.

Frequently Asked Questions

What happens if Bun is partially installed but corrupted?

If bun --version returns a non-zero exit code or fails to execute, the job-scraper skill treats this as complete unavailability regardless of installation state. The system does not attempt to diagnose partial installations; it immediately triggers the WebSearch fallback to ensure workflow continuity.

Does the WebSearch fallback support all job portals equally?

Yes, the fallback mechanism is designed to provide universal coverage. When Bun is unavailable, the skill uses portal-specific query templates from .claude/skills/job-scraper/search-queries.md to construct appropriate WebSearch queries for every configured portal, including LinkedIn, Job Bank, and JobNet, ensuring no portal is excluded due to runtime constraints.

How can I verify if the fallback mechanism activated during a search?

The job-scraper workflow explicitly records fallback activation in Step 5 of its execution log. Users can review these logs to identify when WebSearch was substituted for Bun-based CLI execution, providing clear visibility into which data retrieval method was used for each portal.

Can I force the WebSearch fallback even if Bun is installed?

The current implementation automatically detects Bun availability through the bun --version check. To force WebSearch usage, you would need to temporarily remove Bun from your system $PATH or modify the availability check logic in .claude/skills/job-scraper/SKILL.md, as there is no configuration toggle to override the automatic runtime detection.

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