Skip to main content
Glama

hermes-jobsuche

An open-source Hermes Agent native v2 plugin, Antigravity CLI MCP plugin, and Python CLI suite (jobsuche) for searching, monitoring, scoring, and exporting Ausbildung offers from the Bundesagentur für Arbeit (Jobsuche — arbeitsagentur.de) into LLM-ready Markdown & JSON bundles.

License: MIT Python 3.11+ Hermes Plugin v2 Antigravity MCP


Features

  • Triple-Surface Architecture:

    • Hermes Agent Standalone v2 Plugin (plugin.yaml + __init__.py): Exposes jobsuche_search, jobsuche_monitor, jobsuche_export_llm, and jobsuche_status tools plus the bundled jobsuche skill.

    • Antigravity CLI Plugin (.agents/plugins/jobsuche/): Bundles a stdio JSON-RPC 2.0 MCP server (mcp_server.py) with 6 tools (jobsuche_search_ausbildung, jobsuche_fetch_offer_details, jobsuche_sync_and_export, jobsuche_list_offers, jobsuche_update_offer_status, jobsuche_auth_status), rules/AGENTS.md, and skills/jobsuche/SKILL.md.

    • Standalone CLI (jobsuche): 7 subcommands (search, sync, export, companies, status, login, otp-test) for terminal and cron workflows.

  • Fast Public REST API (pc/v6/jobs + pc/v4/jobdetails):

    • Queries https://rest.arbeitsagentur.de/jobboerse/jobsuche-service/pc/v6/jobs (angebotsart=4 for Ausbildung / Duales Studium) and fetches full descriptions from pc/v4/jobdetails/{base64(refnr)} with zero browser overhead and no BA account required.

  • SQLite Deduplication & Audit History (db.py):

    • Tracks seen refnr IDs, groups offers by normalized company_slug, logs field changes (title, start_date, city, status) in offer_history, and preserves applicant triage states (new, shortlisted, drafted, applied, rejected, ignored) across re-syncs.

  • Relevance Scoring & LLM-Ready Exports (sorter.py, exporter.py):

    • Scores offers (0–100) by technical keyword alignment (e.g., Linux, Debian, Netzwerk, Windows Server, Active Directory, Virtualisierung, Proxmox, Docker, Firewall, IT-Support), distance (km), and start date.

    • Generates per-offer folders exports/offers/<Company_Slug>__<RefNr>/{offer.md,offer.json} with 16 YAML frontmatter fields and 5 structured sections, plus exports/INDEX_FOR_LLM.md and exports/companies_summary.json so AI agents can immediately draft tailored German Anschreiben and CVs.

  • Optional Playwright Enrichment & 6-Digit TOTP (auth_otp.py, browser.py, portal_scraper.py):

    • Supports pyotp 6-digit TOTP generation (with <3s window rollover guard) and IMAP/CLI fallback, de-DE stealth browser context with storage_state.json persistence, and strict CAPTCHA safety (never attempts to solve/bypass CAPTCHAs; saves diagnostic screenshot + JSON and alerts the user).


Related MCP server: job-search-mcp

Repository Layout

.
├── .agents/
│   └── plugins/
│       └── jobsuche/                    # Antigravity CLI plugin (MCP server + rules + skill)
│           ├── assets/logo.svg
│           ├── mcp_config.json
│           ├── mcp_server.py
│           ├── plugin.json
│           ├── rules/AGENTS.md
│           └── skills/jobsuche/SKILL.md
├── plugins/
│   └── hermes/
│       └── jobsuche/                    # Hermes plugin mirror for local script installs
├── scripts/
│   ├── deploy_and_test_remote.sh        # Remote SSH/rsync test runner
│   └── install_plugins.sh               # Local installer for Antigravity & Hermes plugins
├── skills/
│   └── jobsuche/
│       └── SKILL.md                     # Bundled Hermes Agent skill
├── src/
│   └── jobsuche_pkg/
│       ├── __init__.py
│       ├── api_client.py                # Jobsuche REST API v6/v4 client
│       ├── auth_otp.py                  # 6-digit TOTP (pyotp) + IMAP/CLI fallback
│       ├── browser.py                   # Playwright context manager & CAPTCHA guard
│       ├── cli.py                       # `jobsuche` CLI entrypoint
│       ├── config.py                    # Settings & environment configuration
│       ├── db.py                        # SQLite storage, history & company profiles
│       ├── exporter.py                  # LLM-ready Markdown + JSON exporter
│       ├── models.py                    # Pydantic domain models
│       ├── portal_scraper.py            # Optional authenticated portal scraper
│       └── sorter.py                    # Relevance scoring, filtering & company grouping
├── tests/
│   ├── e2e/                             # 4-tier opaque-box E2E test suite (158 tests)
│   ├── test_api_and_db.py
│   ├── test_otp.py
│   ├── test_plugins.py
│   └── test_sorter_exporter.py
├── .env.example
├── CHANGELOG.md
├── LICENSE
├── README.md
├── __init__.py                          # Root Hermes plugin entrypoint (register(ctx))
├── plugin.yaml                          # Root Hermes plugin manifest (v2 standalone)
└── pyproject.toml

Installation

1. Hermes Agent Plugin

# Install directly from GitHub
hermes plugins install clockwork-dev/hermes-jobsuche --enable --yes-deps

# Validate & inspect tools
hermes plugins validate ~/.hermes/plugins/jobsuche --json
hermes plugins doctor --ci ~/.hermes/plugins/jobsuche

2. Local Clone (Python CLI + Antigravity CLI + Hermes Agent)

git clone https://github.com/clockwork-dev/hermes-jobsuche.git
cd hermes-jobsuche

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e ".[dev]"

# Link/install both Antigravity CLI and Hermes Agent plugins into ~/
./scripts/install_plugins.sh

CLI Usage (jobsuche)

# Search Ausbildung offers (defaults: Fachinformatiker/in für Systemintegration, Aachen, 25 km)
.venv/bin/jobsuche search --was "Fachinformatiker/in für Systemintegration" --wo Aachen --umkreis 25

# Sync offers into SQLite (data/jobsuche.db) and export LLM bundles into exports/
.venv/bin/jobsuche sync --was "Fachinformatiker/in für Systemintegration" --wo Aachen --umkreis 25
.venv/bin/jobsuche export

# List grouped companies and highest-scoring offers
.venv/bin/jobsuche companies

# Update application status and notes
.venv/bin/jobsuche status 10000-1208214389-S shortlisted --notes "Linux, Windows Server, AD, Firewall, VPN"

LLM Export Structure (exports/)

Running jobsuche sync + jobsuche export (or calling jobsuche_sync_and_export / jobsuche_export_llm) generates:

  • exports/INDEX_FOR_LLM.md — Ranked Markdown table of all active offers (score, status, company, city/distance, start date, matched skills, relative path to offer.md).

  • exports/companies_summary.json — Aggregated statistics per employer (company_slug, offer_count, max_score, avg_score, offers).

  • exports/offers/<Company_Slug>__<RefNr>/offer.md — Token-optimized Markdown card with 16 YAML frontmatter keys (refnr, title, profession, company, plz, city, distance_km, start_date, contact_name, contact_email, contact_phone, apply_url, portal_url, score, matched_skills, status) and 5 structured sections for immediate Anschreiben generation.

  • exports/offers/<Company_Slug>__<RefNr>/offer.json — Full normalized JSON payload.


Testing

.venv/bin/pytest

License

Released under the MIT License.

Available Tools

6 tools
jobsuche_auth_statusA

Check Bundesagentur für Arbeit session state, credentials, and 6-digit TOTP generator readiness.

Inputs: test_totp.

jobsuche_fetch_offer_detailsC

Fetch full description, requirements, and employer contact details for a Jobsuche refnr.

Inputs: refnr (required), mode, persist.

jobsuche_list_offersB

List and filter tracked Ausbildung offers stored in SQLite.

Inputs: city, limit, status, company, +2 more.

jobsuche_search_ausbildungC

Search Bundesagentur für Arbeit (arbeitsagentur.de) for Ausbildung offers (default: Fachinformatiker/in für Systemintegration in Aachen, 25 km radius).

Inputs: wo, plz, was, mode, +4 more.

jobsuche_sync_and_exportB

Synchronize Ausbildung offers from Jobsuche API into SQLite, score and group by company, and export LLM-ready Markdown/JSON packages to exports/.

Inputs: wo, plz, was, limit, +4 more.

jobsuche_update_offer_statusB

Update an offer's application status (new, shortlisted, drafted, applied, rejected, ignored) and notes.

Inputs: refnr (required), status (required), notes, db_path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool has a distinct role: remote search (search_ausbildung), remote detail fetch (fetch_offer_details), local tracking queries (list_offers), and status mutation (update_offer_status). The main potential confusion is list_offers vs. search_ausbildung, but descriptions clearly signal local SQLite vs. live API, so misselection risk is low.

    Naming Consistency4/5

    All tools share the jobsuche_ prefix and mostly follow verb_noun style (fetch_offer_details, list_offers, search_ausbildung, update_offer_status, sync_and_export). auth_status deviates as a noun phrase, and sync_and_export bundles two actions, but the pattern remains readable and predictable.

    Tool Count4/5

    Six tools cover a focused workflow (auth, search, fetch, sync/export, list, update) without redundancy. It is slightly lean — no removal/pruning operation and no standalone scoring tool — but each tool earns its place for this niche pipeline.

    Completeness4/5

    The core lifecycle is covered: session auth, discovery via search, detail retrieval, local tracking, status mutation, and bulk export. Minor gaps exist (no delete/archive of tracked offers, no manual add, no separate rescore), but agents can work around them via update_offer_status (e.g., 'ignored').

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Searches LinkedIn, Indeed, USAJobs, and Google Jobs from the command line, deduplicates across sources, and optionally finds hiring manager emails; also runs as an MCP server for AI agents.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that aggregates job listings from Remotive and Arbeitnow, with local SQLite caching, application tracking, and saved searches.
      66 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.
      20
      -
    • A
      license
      A
      quality
      D
      maintenance
      A privacy-first MCP server for locally managing job, fellowship, and graduate-school applications. It offers tools for tracking application status, analyzing role fit, generating LaTeX CV/cover letters, interview prep, and discovering public jobs from ATS APIs.
      8
      1
      MIT