# How Realtime Functionality and Updates Are Handled in ai-job-search

> Discover how ai-job-search handles realtime functionality and updates. Learn about on-demand CLI skill execution for live data and efficient framework update management.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: internals
- Published: 2026-07-25

---

**The ai-job-search repository implements realtime job searching through on-demand CLI skill execution that fetches live data via HTTP requests, while framework updates are managed through explicit version metadata and Python utilities that track upstream changes.**

This repository does not run a continuously-running server. Instead, all realtime behavior is performed on-demand when users invoke CLI skills or helper scripts, with framework modifications tracked through explicit version markers and sync utilities.

## Real-Time Job Portal Queries

### Live Search Execution

When a user requests job listings, the repository executes **live searches** by sending fresh HTTP requests to public job-board APIs or scraping current HTML pages. The TypeScript CLI files under `.agents/skills/*/cli/src/` use `fetch`, `axios`, or `curl` via Bash to retrieve data at execution time. No background polling or caching layer is performed.

For example, the Jobindex skill executes searches through its CLI entry point at [`.agents/skills/jobindex-search/cli/src/cli.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobindex-search/cli/src/cli.ts). According to the accompanying [`.agents/skills/jobindex-search/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobindex-search/SKILL.md) documentation, this skill searches "live Danish job listings" with no authentication required, confirming that each invocation triggers a real-time network call.

### Live Detail Fetching

After retrieving search results, users can request detailed information for specific job postings using the `detail <id>` command. This functionality performs a second HTTP request to the job-board's live endpoint to return the full posting, deadline, and application link. The `detail` implementation resides in the same CLI command files that handle the initial search, ensuring all data reflects the current state of the job portal.

### Continuous Integration Constraints

The GitHub Actions workflow at [`.github/workflows/ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.github/workflows/ci.yml) deliberately excludes live portal testing. The configuration file contains explicit comments such as "Deliberately NOT here: live smoke tests of the job‑portal CLIs" and executes only static type-checks and fixture tests. This design prevents CI pipelines from hitting external rate limits while maintaining code quality.

### Example: Running a Real-Time Search

To execute a live search for Python jobs posted in the last seven days:

```bash
bun run .agents/skills/jobindex-search/cli/src/cli.ts search \
  --query python \
  --jobage 7 \
  --sort date \
  --format table

```

This command contacts `jobindex.dk` at execution time, returning the current 20 results (or more if `--limit` is specified) without any cached data.

## Framework Versioning and Update Management

### Enforcing Version Bumps with check_framework_version.py

The repository versions its methodology files using a `framework_version` front-matter field in markdown files. The script [`tools/check_framework_version.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_framework_version.py) ensures that any edited framework file has its version marker incremented. If the version is out-of-date, the CI pipeline fails, preventing unversioned changes from merging.

### Previewing Upstream Changes with check_upstream_updates.py

To synchronize with upstream changes, the repository provides [`tools/check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_upstream_updates.py). This utility calls `git fetch` on the upstream remote, computes a diff between `origin/master` and the local branch, and prints a list of touched files with their new version markers. Users can preview changes before merging:

```bash
python3 tools/check_upstream_updates.py

```

When accepting changes, users merge via standard Git workflow (`git merge upstream/master`). The version bump in each updated file signals that framework behavior—such as new scoring rules or CLI flag defaults—may have changed.

## Optional File System Monitoring

The repository includes a **Watchman hook** at `.git/hooks/fsmonitor-watchman.sample` that optimizes local Git performance by reporting file changes. This optional integration calls `watchman query` to obtain a clock token and changed path list, speeding up Git operations but remaining unrelated to job-portal queries.

## Summary

- **On-demand execution**: Realtime job searches occur only when CLI skills are invoked, with no continuous server or background polling.
- **Live HTTP requests**: Skills under `.agents/skills/*/cli/src/` use `fetch`, `axios`, or `curl` to retrieve current data directly from job portals.
- **CI isolation**: The GitHub Actions workflow deliberately skips live network calls to avoid rate limiting and external dependencies in testing.
- **Versioned updates**: Framework changes use `framework_version` front-matter tracked by [`tools/check_framework_version.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_framework_version.py) and [`tools/check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_upstream_updates.py).
- **Fork synchronization**: The [`check_upstream_updates.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/check_upstream_updates.py) script previews upstream changes before merging, ensuring controlled framework updates.

## Frequently Asked Questions

### Does ai-job-search maintain a background service for realtime updates?

No. The repository does not run a continuously-running server or daemon. All realtime functionality is performed on-demand when a user invokes a specific CLI skill, which then executes HTTP requests to fetch current job data.

### How does the repository prevent CI pipelines from hitting job portal rate limits?

The [`.github/workflows/ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.github/workflows/ci.yml) configuration explicitly excludes live smoke tests. Comments in the workflow indicate that live portal CLI tests are "Deliberately NOT here," ensuring that automated testing performs only static analysis and fixture-based validation without external network calls.

### What triggers a framework version check in the methodology files?

Any modification to a framework methodology file (marked with `framework_version` front-matter) triggers the [`tools/check_framework_version.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/check_framework_version.py) validator. The CI pipeline runs this check to ensure the version marker is incremented, failing the build if an edited file lacks a proper version bump.

### Can I preview upstream changes before merging them into my fork?

Yes. Running `python3 tools/check_upstream_updates.py` fetches the upstream remote and displays exactly which methodology files have changed, along with their new version markers. This allows you to review changes before executing `git merge upstream/master`.