--- name: Freehire Search slug: freehire-search category: Automation description: Freehire Search queries the freehire.me public API to search live software, data, and engineering job listings across many countries, with faceted filters for skills, seniority, category, and region. Use it when an agent needs to find technical roles or look up a specific posting by slug. github: "https://github.com/MadsLorentzen/ai-job-search/tree/master/.agents/skills/freehire-search" language: TypeScript stars: 31589 forks: 10956 install: "npx degit https://github.com/MadsLorentzen/ai-job-search/tree/master/.agents/skills/freehire-search ~/.claude/skills/freehire-search" installs_to: ~/.claude/skills/freehire-search source_path: .agents/skills/freehire-search/SKILL.md collection_size: 9 category_size: 1523 collection_url: "https://dirskills.com/collections/MadsLorentzen/ai-job-search" added: 2026-08-14T07:11:24.292Z last_synced: 2026-08-14T07:11:24.292Z canonical_url: "https://dirskills.com/skills/freehire-search" --- # Freehire Search Freehire Search queries the freehire.me public API to search live software, data, and engineering job listings across many countries, with faceted filters for skills, seniority, category, and region. Use it when an agent needs to find technical roles or look up a specific posting by slug. **Install:** ```bash npx degit https://github.com/MadsLorentzen/ai-job-search/tree/master/.agents/skills/freehire-search ~/.claude/skills/freehire-search ``` ## README # freehire Search Skill Search live job listings from the **[freehire.me](https://freehire.me)** job aggregator — an open-source IT job board that normalizes postings from ~50 ATS platforms across many countries into one schema. No authentication, no API key, and **zero runtime dependencies** — it runs with just `bun`. The market is chosen per query via facet flags (`--region`, `--country`), so the same skill works for a forker in any market out of the box. > This is a country-agnostic worked example of the repo's job-portal-skill pattern, > like `linkedin-search`. Unlike the HTML-scraping portals, it queries freehire's > public JSON API, so results are structured (skills, seniority, region facets) > rather than parsed from markup. ## ⚠️ Scope: tech-focused freehire's corpus already includes some non-tech postings (it crawls whole company career pages), **but its faceted filtering — skills, categories, and seniority dictionaries — is tuned tech-first today**, so this skill scopes its triggers to software / data / engineering / tech roles, where the filtering is strong. Non-tech coverage exists but is still maturing; don't rely on this skill for general (non-technical) job coverage yet. ## ℹ️ Hosted-service dependency (best-effort, no SLA) This skill depends on a third-party hosted service, freehire.me. Reads are **public and unauthenticated** — the same zero-signup bar as `linkedin-search`. **freehire.me is a personal project but actively maintained; it runs on a best-effort basis (no formal SLA).** If the API is unreachable, the CLI fails gracefully — a non-zero exit with a clear error message — so an outage degrades this source rather than breaking the surrounding workflow. **Self-hosting / swappable base URL.** The freehire backend is a separate MIT-licensed repo — [`strelov1/freehire`](https://github.com/strelov1/freehire) (Go + PostgreSQL + Meilisearch) — that stands up with one command via Docker Compose (`make up` → API on `:8080`, same `/api/v1/...` paths). The skill honors a base-URL env var, `FREEHIRE_API_URL` (default `https://freehire.me`), so pointing it at a local instance is a one-line change: ```bash FREEHIRE_API_URL=http://localhost:8080 bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "go" ``` Caveat: standing up the *API* is light, but keeping a *full, continuously-fresh* mirror (millions of postings across ~50 platforms) is resource-heavy — a self-hoster would either crawl a scoped subset of sources or point the env var back at the hosted API. ## When to use this skill - Search for tech job openings by keyword, in a given region/country or remotely — each result comes back with its **full description**, no per-hit follow-up needed - Filter by seniority, category, skills, or recency (posted within N days) - Look one freehire posting up by its slug (including a closed one) ## Commands ### Search job listings ```bash bun run .agents/skills/freehire-search/cli/src/cli.ts search [-q ""] [facet flags] ``` Key flags: - `--query ` / `-q ` — keyword search (title, skill, role). Full-text; optional. - `--jobage ` — posted within N days (maps to `posted_within_days`). - `--page ` — 1-indexed page. Default 1. - `--limit ` / `-n ` — results per page (API limit). Default 25. - `--format json|table|plain` — default `json`. - `--description-format markdown|text|html` — how each result's full description is rendered. Default `markdown`, which keeps the posting's headings and requirement lists intact. `json` output only. **Search results already carry the full description.** This skill queries freehire's agent search endpoint, which replaces the index's truncated preview with each posting's complete text, so a search of 20 roles is 1 request rather than 1 + 20. Do **not** loop `detail` over search hits to read their descriptions — reach for `detail` only to look one posting up by slug (e.g. from the tracker, or a posting already closed and therefore absent from search). Full descriptions are verbose: keep `--limit` modest, and pre-filter on title/company before reading bodies. Facet filters (values come from freehire's controlled vocabularies; comma-separate for OR within a facet): - `--region ` — macro-region, e.g. `global`, `eu`, `us`, `apac`, `latam`, `cis`. `--region eu,us`. Use `none` to match jobs whose region could **not** be resolved (see "Partial data" below). - `--country ` — ISO-3166 alpha-2, e.g. `--country DE,GB` - `--city ` — city name(s), e.g. `--city Berlin` - `--seniority ` — `junior`, `middle`, `senior`, `staff`, `principal`, `lead`, … - `--category ` — `backend`, `frontend`, `fullstack`, `devops`, `ml_ai`, `qa`, … - `--skill ` — canonical skill(s), e.g. `--skill go,kubernetes` - `--company ` — company slug (from a result's `company_slug`) - `--remote ` — `remote` | `hybrid` | `onsite` (`work_mode` facet) - `--facet ` — any other facet param (repeatable), e.g. `--facet salary_min=100000` > **Location is a facet, not free text.** Unlike `linkedin-search`'s `--location`, > freehire filters geography through the structured `--region`/`--country`/`--city` > facets. Discover the live values for a market at > [`/api/v1/jobs/facets`](https://freehire.me/api/v1/jobs/facets) (append `?q=` > to scope it) — never invent facet values. ### Fetch full job detail ```bash bun run .agents/skills/freehire-search/cli/src/cli.ts detail [--format json|plain] ``` `slug` is the `id` from a `search` result (e.g. `golang-zensar-2bxu6dxm`). You may also pass a full `https://freehire.me/jobs/` URL. Returns the full (HTML-stripped) description, skills, region/country, and — when the posting is enriched — seniority, category, employment type, and salary. Use it for a posting you already have a slug for — a tracked application, a shared link, or a closed posting search no longer lists. Re-fetching a hit that `search` just returned only re-reads a description you already have. ## Usage examples ```bash # Senior backend roles, table view bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table # Remote React roles in the EU bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "react" --remote remote --region eu --format table # DevOps roles in Germany posted in the last 14 days bun run .agents/skills/freehire-search/cli/src/cli.ts search --category devops --country DE --jobage 14 --format table # ML/AI roles anywhere, fully remote bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "machine learning" --category ml_ai --remote remote --format table # Descriptions as plain text instead of Markdown bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "platform engineer" --limit 5 --description-format text # Full details for a specific job bun run .agents/skills/freehire-search/cli/src/cli.ts detail golang-zensar-2bxu6dxm --format plain ``` ## Output formats | Format | Best for | |--------|----------| | `json` | Default — programmatic use; the only format carrying each hit's description | | `table` | Quick human-readable scanning | | `plain` | Reading a single job's full detail (`detail` command) | Search JSON is `{ "meta": { "count", "page", "total" }, "results": [...] }`; each result carries at least `id` (the freehire slug), `title`, `company`, `location`, `date`, `url`, and `description` (missing values are `null`). `table` and `plain` omit the description — it would swamp a scannable list. All errors are written to **stderr** as `{ "error": "...", "code": "..." }` and the process exits with code `1`. ## Partial data Facets are derived per-posting and can be **incomplete** — geography especially. A job may resolve its `work_mode` (e.g. `remote`) but leave its **region or country undetermined** when the source's location text is ambiguous (freehire's dictionaries never guess). So: - A missing region/country means "not resolved", **not** "not applicable" — filtering on `--region eu` silently drops jobs whose region wasn't resolved, even if they are in fact EU. Widen or drop the facet if you need those back. - There is a dedicated facet value for the unresolved bucket: `--region none` matches jobs with **no** resolved region — useful to sweep up remote roles that never pinned a geography. It ORs with real regions, e.g. `--region eu,none`. - `result.regions` / `countries` / `cities` may be empty arrays for the same reason; treat empty as unknown, not as "none of the above". ## Notes - Data is from freehire.me's public API — no credentials required. Only per-user tracking (apply/save) needs a key, and this skill deliberately does not touch it: it is **search + detail only**. - `id` in search results is the freehire `public_slug` — pass it as-is to `detail`. - `date` is the posting date (`posted_at`); it may be `null` for undated postings. - Facet values are controlled vocabularies. Use `/api/v1/jobs/facets` to see the live values (with counts) for a query before filtering. - The API retries 429/5xx with exponential backoff; an unreachable API exits non-zero with a clear message (best-effort service, see the dependency note above). - `search` calls `/api/v1/agent/jobs/search` (public, like the rest). A self-hosted instance older than that endpoint answers 404, and the CLI reports it as an error naming the endpoint — never as an empty result set.