Skip to content
Back to search

agentic-career-search

Agentic job-discovery backend: 119 ATS & job-board adapters (Greenhouse, Lever, Workday, JSON-LD), explainable scoring with decision traces, cancellable runs, JobSpy-style search with CSV/JSONL export and Atom feeds, resume-to-job matching with missing skills, a read-only MCP server and optional GPT-6, Claude 5.5, Gemini 4 or Kimi K3.1 enrichment.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Francis1998/agentic-career-search with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Francis1998/agentic-career-search'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/francis1998--agentic-career-search/badge.svg)](/listings/francis1998--agentic-career-search)

HTML

<a href="/listings/francis1998--agentic-career-search"><img src="/api/listings/francis1998--agentic-career-search/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/Francis1998/agentic-career-search.git && cd agentic-career-search
uv sync --extra dev --frozen
export DATABASE_URL=sqlite+aiosqlite:///./demo.db

# Offline: seed demo jobs and serve them (no network, no keys)
uv run python scripts/seed_demo_jobs.py
ENABLE_WORKER=false uv run uvicorn autoapply_agent.main:app --port 8000 &
# Wait up to 10 s for the server, then check it: continue once this prints {"status":"ready"}
for _ in $(seq 50); do curl -sf localhost:8000/health/ready >/dev/null && break; sleep 0.2; done
curl -sS localhost:8000/health/ready

Then search, export and subscribe:

curl -sS 'localhost:8000/jobs?q=python&remote=true&sort=score&dedupe=true' \
  | jq -c '.[] | [.title, .company, .score]'
curl -sS -OJ 'localhost:8000/jobs/export?format=csv&min_score=0.7'    # spreadsheet-safe CSV
curl -sS 'localhost:8000/jobs/feed.atom?remote=true' | head -20       # Atom feed

Rank the same feed against a resume (plain text; the sample is synthetic):

jq -n --rawfile resume docs/guides/RESUME_JOB_MATCH_SAMPLE_RESUME.txt '{resume_text: $resume, remote: true}' \
  | curl -sS localhost:8000/jobs/match -H 'content-type: application/json' -d @- \
  | jq -c '.jobs[] | [.rank, .match_score, .title, .missing_skills]'

[RESUME_JOB_MATCH_GUIDE.md](docs/guides/RESUME_JOB_MATCH_GUIDE.md) covers the skill lexicon, `sort=blend`, CSV output, limits and privacy.

For live data, start the API with the worker enabled (omit `ENABLE_WORKER=false`), then register a public board and start a run:

curl -s -X POST localhost:8000/source-configs -H 'content-type: application/json' \
  -d '{"name":"gitlab","source_type":"greenhouse","base_url":"https://boards.greenhouse.io/gitlab"}'
curl -s -X POST localhost:8000/runs -H 'content-type: application/json' \
  -d '{"query":"backend engineer python remote"}'

[PORTFOLIO_WALKTHROUGH.md](docs/guides/PORTFOLIO_WALKTHROUGH.md) follows one real search end to end, and [QUICKSTART.md](QUICKSTART.md) covers setup details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 215 lines
  1. # agentic-career-search
  2. ![CI](https://github.com/Francis1998/agentic-career-search/actions/workflows/ci.yml/badge.svg) ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB) ![FastAPI](https://img.shields.io/badge/framework-FastAPI-009688) ![License](https://img.shields.io/badge/license-MIT-green)
  3. **An agentic job-discovery backend that explains every decision.** Point it at public
  4. career boards (119 ATS and job-board adapters: Greenhouse, Lever, Workday, Ashby,
  5. SmartRecruiters, schema.org JSON-LD and more). A worker runs cancellable discovery runs
  6. that score every posting and record why, then you search, export and subscribe to the
  7. results.
  8. ![Job search, export and Atom feed — real terminal session](assets/demo/job-search-export-feed.gif)
  9. ## Why this exists
  10. Job-search automation usually fails in practice because it:
  11. - **can't explain its ranking** → every job stores a deterministic score, priority tier,
  12. matched terms, rationale and plan steps (`raw.agent_decision`);
  13. - **breaks silently** → one adapter contract with timeouts, bounded scope and per-source
  14. `source.failed` events instead of a crashed script;
  15. - **can't be steered** → runs follow a `queued → running → completed / cancelled / failed`
  16. state machine with cooperative cancellation and an ordered event log;
  17. - **leaves results in a terminal** → JobSpy-style search, CSV/JSONL export and an Atom
  18. feed for Slack, Teams or any feed reader;
  19. - **can't tell what fits *you*** → `POST /jobs/match` ranks the captured feed against your
  20. resume text with matched and missing skills — deterministic, and the resume is never stored;
  21. - **can't be asked about** → a read-only MCP server lets Claude Desktop, Claude Code,
  22. VS Code or Cursor search your feed and explain any score;
  23. - **depends on one LLM** → enrichment is optional and works with the current OpenAI,
  24. Anthropic, Google and Kimi models, while the deterministic core runs offline.
  25. ## How it works
  26. ```mermaid
  27. flowchart LR
  28. SC["Source configs<br/>POST /source-configs"] --> RUN["Runs<br/>POST /runs"]
  29. RUN --> W["InProcessWorker<br/>claims queued runs"]
  30. W --> AD["119 source adapters<br/>Greenhouse · Lever · Workday · JSON-LD …"]
  31. AD --> SCORE["Deterministic scoring<br/>+ planning"]
  32. SCORE --> DT["Decision trace<br/>agent_decision + run events"]
  33. SCORE -. optional .-> LLM["LLM enrichment<br/>GPT-6 · Claude 5.5 / Fable 5.2<br/>Gemini 3.8 / 4 · Kimi K3.1"]
  34. LLM -.-> DT
  35. DT --> DB[("Jobs + run events")]
  36. DB --> API["Search · export · Atom feed<br/>GET /jobs …"]
  37. DB --> MCP["Read-only MCP server<br/>career-search-mcp (stdio)"]
  38. DB --> MATCH["Resume match<br/>POST /jobs/match"]
  39. ```
  40. Every step is observable through `GET /runs/{run_id}/events`, and every stored job carries
  41. its decision trace. See [ARCHITECTURE.md](ARCHITECTURE.md) for the state machine and
  42. event types.
  43. ## 60-second quickstart
  44. ```bash
  45. git clone https://github.com/Francis1998/agentic-career-search.git && cd agentic-career-search
  46. uv sync --extra dev --frozen
  47. export DATABASE_URL=sqlite+aiosqlite:///./demo.db
  48. # Offline: seed demo jobs and serve them (no network, no keys)
  49. uv run python scripts/seed_demo_jobs.py
  50. ENABLE_WORKER=false uv run uvicorn autoapply_agent.main:app --port 8000 &
  51. # Wait up to 10 s for the server, then check it: continue once this prints {"status":"ready"}
  52. for _ in $(seq 50); do curl -sf localhost:8000/health/ready >/dev/null && break; sleep 0.2; done
  53. curl -sS localhost:8000/health/ready
  54. ```
  55. Then search, export and subscribe:
  56. ```bash
  57. curl -sS 'localhost:8000/jobs?q=python&remote=true&sort=score&dedupe=true' \
  58. | jq -c '.[] | [.title, .company, .score]'
  59. curl -sS -OJ 'localhost:8000/jobs/export?format=csv&min_score=0.7' # spreadsheet-safe CSV
  60. curl -sS 'localhost:8000/jobs/feed.atom?remote=true' | head -20 # Atom feed
  61. ```
  62. Rank the same feed against a resume (plain text; the sample is synthetic):
  63. ```bash
  64. jq -n --rawfile resume docs/guides/RESUME_JOB_MATCH_SAMPLE_RESUME.txt '{resume_text: $resume, remote: true}' \
  65. | curl -sS localhost:8000/jobs/match -H 'content-type: application/json' -d @- \
  66. | jq -c '.jobs[] | [.rank, .match_score, .title, .missing_skills]'
  67. ```
  68. ![Resume-to-job match — real terminal session](assets/demo/resume-job-match.gif)
  69. [RESUME_JOB_MATCH_GUIDE.md](docs/guides/RESUME_JOB_MATCH_GUIDE.md) covers the skill lexicon,
  70. `sort=blend`, CSV output, limits and privacy.
  71. For live data, start the API with the worker enabled (omit `ENABLE_WORKER=false`), then
  72. register a public board and start a run:
  73. ```bash
  74. curl -s -X POST localhost:8000/source-configs -H 'content-type: application/json' \
  75. -d '{"name":"gitlab","source_type":"greenhouse","base_url":"https://boards.greenhouse.io/gitlab"}'
  76. curl -s -X POST localhost:8000/runs -H 'content-type: application/json' \
  77. -d '{"query":"backend engineer python remote"}'
  78. ```
  79. [PORTFOLIO_WALKTHROUGH.md](docs/guides/PORTFOLIO_WALKTHROUGH.md) follows one real search
  80. end to end, and [QUICKSTART.md](QUICKSTART.md) covers setup details.
  81. ## Ask your AI assistant (MCP)
  82. `career-search-mcp` is a read-only [Model Context Protocol](https://modelcontextprotocol.io)
  83. server (stdio; protocol 2026-07-28 plus the 2025-11-25 / 2025-06-18 handshake). Assistants
  84. get seven tools — `search_jobs`, `get_job`, `explain_job_score`, `list_runs`, `get_run`,
  85. `list_sources`, `match_resume_to_jobs` — over the jobs your runs already captured, scored
  86. and deduplicated, so *"show me this week's best-fit remote roles and why the top one ranks
  87. first"* needs no scraping, keys or writes. For example, in Claude Code:
  88. ```bash
  89. claude mcp add --transport stdio career-search -- \
  90. /abs/path/agentic-career-search/.venv/bin/career-search-mcp \
  91. --database-url sqlite+aiosqlite:////abs/path/agentic-career-search/autoapply_agent.db
  92. ```
  93. [MCP_SERVER_GUIDE.md](docs/guides/MCP_SERVER_GUIDE.md) covers Claude Desktop, VS Code and
  94. Cursor configuration examples, every tool, the audit log and a recorded session.
  95. ## Feature map
  96. | Area | What you get | Docs |
  97. |---|---|---|
  98. | Sources | 119 adapters (ATS, job boards, vendor-neutral JSON-LD) behind one `CareerSourceAdapter` contract | [Supported sources](docs/SUPPORTED_SOURCES.md) |
  99. | Runs | Queue, worker, cooperative cancel, ordered run events | [ARCHITECTURE.md](ARCHITECTURE.md) |
  100. | Decisions | Deterministic score, priority tier, matched terms, rationale, plan steps per job | [ARCHITECTURE.md](ARCHITECTURE.md) |
  101. | Search & export | Filters, `X-Total-Count` paging, cross-board dedupe, OWASP-safe CSV, JSON Lines, Atom 1.0 | [Search & export guide](docs/guides/JOB_SEARCH_EXPORT_GUIDE.md) |
  102. | Resume match | `POST /jobs/match` and MCP `match_resume_to_jobs`: rank jobs against resume text with a 254-skill alias-aware lexicon (`k8s` → `kubernetes`); match score, matched/missing skills, explanation, `sort=match\|blend`, CSV; resume never stored or logged | [Resume match guide](docs/guides/RESUME_JOB_MATCH_GUIDE.md) |
  103. | AI assistants (MCP) | Read-only stdio MCP server: search, decision traces, plain-language score explanations, runs and events; audit log with hashed arguments | [MCP server guide](docs/guides/MCP_SERVER_GUIDE.md) |
  104. | LLM enrichment | Optional summaries from GPT-6, Claude 5.5 / Fable 5.2, Gemini 3.8 / 4 or Kimi K3.1 models | [CONFIGURATION.md](CONFIGURATION.md) |
  105. | Alerts | Fail-soft webhook for high-priority jobs (Slack, Discord, custom) | [CONFIGURATION.md](CONFIGURATION.md) |
  106. | Career toolkit | 175+ offline, human-in-the-loop helpers (fit, salary bands, interview prep, offer and benefit gap advisors) | [Use-case catalog](docs/USE_CASE_CATALOG.md) |
  107. | Operations | Health probes, Alembic migrations, CI (ruff, mypy, pytest), weekly security scan | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |
  108. ## LLM enrichment (current model stack)
  109. Provider integration is built into the code path and is optional: deterministic scoring
  110. and decision traces work without any key. Each default is a provider's cost-efficient
  111. current model (line-ups verified 2026-11-12 on the linked provider pages):
  112. | Provider | `LLM_PROVIDER` | Default model | Request shape |
  113. |---|---|---|---|
  114. | [OpenAI](https://developers.openai.com/api/docs/models) | `gpt` | `gpt-6-luna` | Chat Completions; `reasoning_effort` from `OPENAI_REASONING_EFFORT` (`none`, so `temperature` is allowed); `gpt-6.1-sol` / `gpt-6-astra` need `low` or higher |
  115. | [Anthropic](https://platform.claude.com/docs/en/models/overview) | `claude` | `claude-haiku-5-5` | Messages API; `output_config.effort` from `CLAUDE_EFFORT` (`low`); no sampling parameters (Claude 5.5 and Fable 5.2 return 400 for custom values) |
  116. | [Google](https://aistudio.google.com/docs/models) | `gemini` | `gemini-3.8-flash` | `generateContent`; `thinkingLevel: LOW` on Gemini 3+ (required on Gemini 4); Gemini 4 keeps Google's default output limit; no sampling parameters |
  117. | [Moonshot Kimi](https://platform.kimi.ai/docs/api/models-overview.md) | `kimi` | `kimi-k3.1-pro` | OpenAI-compatible; `reasoning_effort: low`; `temperature` is fixed at 1.0 by K3 and never sent |
  118. Other current models:
  119. - OpenAI: `gpt-6.1-terra`, `gpt-6.1-sol`, `gpt-6-astra` (flagship).
  120. - Anthropic: `claude-sonnet-5-5`, `claude-opus-5-5` (Anthropic's recommended starting
  121. point), `claude-fable-5-2` (demanding reasoning and long-horizon agentic work; needs
  122. 30-day data retention).
  123. - Google: `gemini-3.5-flash-lite` (cheapest),
  124. [`gemini-4-hydrogen`](https://aistudio.google.com/docs/whats-new-gemini-4-hydrogen)
  125. (released 2026-11-12; Google's recommended upgrade from Gemini 3.8 Flash, at twice its
  126. price until the 3.8 Flash introductory rate ends on 2026-12-31), `gemini-4-argon`,
  127. `gemini-4-carbon` (strongest reasoning).
  128. - Kimi: `kimi-k3.1-pro-highspeed` (same intelligence, about 2-3x the speed).
  129. Kimi K2 models are retiring by the end of December 2026 and closed to new users on
  130. 2026-10-31 ([Moonshot](https://platform.kimi.ai/docs/models)).
  131. See each provider's page for pricing.
  132. Enable provider enrichment:
  133. ```env
  134. LLM_ENABLE_ENRICHMENT=true
  135. LLM_PROVIDER=gemini # or kimi / claude / gpt
  136. ```
  137. Then set matching API keys in `.env` (see `CONFIGURATION.md`).
  138. ## API at a glance
  139. - `POST /source-configs` create source adapter configs
  140. - `GET /source-configs` list enabled sources
  141. - `POST /runs` enqueue autonomous run
  142. - `GET /runs/{run_id}` inspect run state
  143. - `GET /runs/{run_id}/events` inspect event timeline
  144. - `POST /runs/{run_id}/cancel` request cancellation
  145. - `GET /jobs` search normalized, scored, and enriched outputs (`q`, `company`, `location`, `remote`, `min_score`, `source_config_id`, `run_id`, `created_after`, `hours_old`, `sort`, `dedupe`, `limit`/`offset`)
  146. - `GET /jobs/{job_id}` inspect one job
  147. - `GET /jobs/export?format=csv|jsonl` stream filtered results as a download
  148. - `GET /jobs/feed.atom` subscribe to new matches (Atom 1.0)
  149. - `POST /jobs/match` rank jobs against resume text (JSON body: `resume_text` + the `GET /jobs` filters, `sort=match|blend`, `limit`, `min_match`); matched/missing skills; `?format=csv`
  150. - `GET /health/live` and `GET /health/ready`
  151. MCP (stdio, read-only): `career-search-mcp` / `python -m autoapply_agent.mcp` — see the
  152. [MCP server guide](docs/guides/MCP_SERVER_GUIDE.md).
  153. ## Documentation
  154. | Document | What it covers |
  155. |---|---|
  156. | [QUICKSTART.md](QUICKSTART.md) | Local setup and a first run |
  157. | [docs/guides/PORTFOLIO_WALKTHROUGH.md](docs/guides/PORTFOLIO_WALKTHROUGH.md) | One real job search, end to end |
  158. | [docs/guides/JOB_SEARCH_EXPORT_GUIDE.md](docs/guides/JOB_SEARCH_EXPORT_GUIDE.md) | Filters, CSV/JSONL export, Atom feed |
  159. | [docs/guides/MCP_SERVER_GUIDE.md](docs/guides/MCP_SERVER_GUIDE.md) | Read-only MCP server for AI assistants: client setup, tools, privacy |
  160. | [docs/guides/RESUME_JOB_MATCH_GUIDE.md](docs/guides/RESUME_JOB_MATCH_GUIDE.md) | Resume-to-job match: API + MCP reference, skill lexicon, ranking, privacy |
  161. | [ARCHITECTURE.md](ARCHITECTURE.md) | Components, run lifecycle, events |
  162. | [docs/API.md](docs/API.md) | HTTP API reference |
  163. | [CONFIGURATION.md](CONFIGURATION.md) | Environment variables and provider profiles |
  164. | [docs/SUPPORTED_SOURCES.md](docs/SUPPORTED_SOURCES.md) | Every source adapter |
  165. | [docs/USE_CASE_CATALOG.md](docs/USE_CASE_CATALOG.md) | Advisor and use-case catalog, demo gallery |
  166. | [SAFETY.md](SAFETY.md) | Scope boundaries and guardrails |
  167. | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Deployment and migrations |
  168. | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common failures |
  169. | [CONTRIBUTING.md](CONTRIBUTING.md) | Development workflow |
  170. | [CHANGELOG.md](CHANGELOG.md) | Release history |
  171. ## License
  172. MIT © [Francis1998](https://github.com/Francis1998)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.