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.
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
Markdown
[](/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
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/readyThen 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
- # agentic-career-search
-    
- **An agentic job-discovery backend that explains every decision.** Point it at public
- career boards (119 ATS and job-board adapters: Greenhouse, Lever, Workday, Ashby,
- SmartRecruiters, schema.org JSON-LD and more). A worker runs cancellable discovery runs
- that score every posting and record why, then you search, export and subscribe to the
- results.
- 
- ## Why this exists
- Job-search automation usually fails in practice because it:
- - **can't explain its ranking** → every job stores a deterministic score, priority tier,
- matched terms, rationale and plan steps (`raw.agent_decision`);
- - **breaks silently** → one adapter contract with timeouts, bounded scope and per-source
- `source.failed` events instead of a crashed script;
- - **can't be steered** → runs follow a `queued → running → completed / cancelled / failed`
- state machine with cooperative cancellation and an ordered event log;
- - **leaves results in a terminal** → JobSpy-style search, CSV/JSONL export and an Atom
- feed for Slack, Teams or any feed reader;
- - **can't tell what fits *you*** → `POST /jobs/match` ranks the captured feed against your
- resume text with matched and missing skills — deterministic, and the resume is never stored;
- - **can't be asked about** → a read-only MCP server lets Claude Desktop, Claude Code,
- VS Code or Cursor search your feed and explain any score;
- - **depends on one LLM** → enrichment is optional and works with the current OpenAI,
- Anthropic, Google and Kimi models, while the deterministic core runs offline.
- ## How it works
- ```mermaid
- flowchart LR
- SC["Source configs<br/>POST /source-configs"] --> RUN["Runs<br/>POST /runs"]
- RUN --> W["InProcessWorker<br/>claims queued runs"]
- W --> AD["119 source adapters<br/>Greenhouse · Lever · Workday · JSON-LD …"]
- AD --> SCORE["Deterministic scoring<br/>+ planning"]
- SCORE --> DT["Decision trace<br/>agent_decision + run events"]
- SCORE -. optional .-> LLM["LLM enrichment<br/>GPT-6 · Claude 5.5 / Fable 5.2<br/>Gemini 3.8 / 4 · Kimi K3.1"]
- LLM -.-> DT
- DT --> DB[("Jobs + run events")]
- DB --> API["Search · export · Atom feed<br/>GET /jobs …"]
- DB --> MCP["Read-only MCP server<br/>career-search-mcp (stdio)"]
- DB --> MATCH["Resume match<br/>POST /jobs/match"]
- ```
- Every step is observable through `GET /runs/{run_id}/events`, and every stored job carries
- its decision trace. See [ARCHITECTURE.md](ARCHITECTURE.md) for the state machine and
- event types.
- ## 60-second quickstart
- ```bash
- 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:
- ```bash
- 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):
- ```bash
- 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:
- ```bash
- 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.
- ## Ask your AI assistant (MCP)
- `career-search-mcp` is a read-only [Model Context Protocol](https://modelcontextprotocol.io)
- server (stdio; protocol 2026-07-28 plus the 2025-11-25 / 2025-06-18 handshake). Assistants
- get seven tools — `search_jobs`, `get_job`, `explain_job_score`, `list_runs`, `get_run`,
- `list_sources`, `match_resume_to_jobs` — over the jobs your runs already captured, scored
- and deduplicated, so *"show me this week's best-fit remote roles and why the top one ranks
- first"* needs no scraping, keys or writes. For example, in Claude Code:
- ```bash
- claude mcp add --transport stdio career-search -- \
- /abs/path/agentic-career-search/.venv/bin/career-search-mcp \
- --database-url sqlite+aiosqlite:////abs/path/agentic-career-search/autoapply_agent.db
- ```
- [MCP_SERVER_GUIDE.md](docs/guides/MCP_SERVER_GUIDE.md) covers Claude Desktop, VS Code and
- Cursor configuration examples, every tool, the audit log and a recorded session.
- ## Feature map
- | Area | What you get | Docs |
- |---|---|---|
- | Sources | 119 adapters (ATS, job boards, vendor-neutral JSON-LD) behind one `CareerSourceAdapter` contract | [Supported sources](docs/SUPPORTED_SOURCES.md) |
- | Runs | Queue, worker, cooperative cancel, ordered run events | [ARCHITECTURE.md](ARCHITECTURE.md) |
- | Decisions | Deterministic score, priority tier, matched terms, rationale, plan steps per job | [ARCHITECTURE.md](ARCHITECTURE.md) |
- | 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) |
- | 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) |
- | 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) |
- | 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) |
- | Alerts | Fail-soft webhook for high-priority jobs (Slack, Discord, custom) | [CONFIGURATION.md](CONFIGURATION.md) |
- | 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) |
- | Operations | Health probes, Alembic migrations, CI (ruff, mypy, pytest), weekly security scan | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |
- ## LLM enrichment (current model stack)
- Provider integration is built into the code path and is optional: deterministic scoring
- and decision traces work without any key. Each default is a provider's cost-efficient
- current model (line-ups verified 2026-11-12 on the linked provider pages):
- | Provider | `LLM_PROVIDER` | Default model | Request shape |
- |---|---|---|---|
- | [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 |
- | [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) |
- | [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 |
- | [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 |
- Other current models:
- - OpenAI: `gpt-6.1-terra`, `gpt-6.1-sol`, `gpt-6-astra` (flagship).
- - Anthropic: `claude-sonnet-5-5`, `claude-opus-5-5` (Anthropic's recommended starting
- point), `claude-fable-5-2` (demanding reasoning and long-horizon agentic work; needs
- 30-day data retention).
- - Google: `gemini-3.5-flash-lite` (cheapest),
- [`gemini-4-hydrogen`](https://aistudio.google.com/docs/whats-new-gemini-4-hydrogen)
- (released 2026-11-12; Google's recommended upgrade from Gemini 3.8 Flash, at twice its
- price until the 3.8 Flash introductory rate ends on 2026-12-31), `gemini-4-argon`,
- `gemini-4-carbon` (strongest reasoning).
- - Kimi: `kimi-k3.1-pro-highspeed` (same intelligence, about 2-3x the speed).
- Kimi K2 models are retiring by the end of December 2026 and closed to new users on
- 2026-10-31 ([Moonshot](https://platform.kimi.ai/docs/models)).
- See each provider's page for pricing.
- Enable provider enrichment:
- ```env
- LLM_ENABLE_ENRICHMENT=true
- LLM_PROVIDER=gemini # or kimi / claude / gpt
- ```
- Then set matching API keys in `.env` (see `CONFIGURATION.md`).
- ## API at a glance
- - `POST /source-configs` create source adapter configs
- - `GET /source-configs` list enabled sources
- - `POST /runs` enqueue autonomous run
- - `GET /runs/{run_id}` inspect run state
- - `GET /runs/{run_id}/events` inspect event timeline
- - `POST /runs/{run_id}/cancel` request cancellation
- - `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`)
- - `GET /jobs/{job_id}` inspect one job
- - `GET /jobs/export?format=csv|jsonl` stream filtered results as a download
- - `GET /jobs/feed.atom` subscribe to new matches (Atom 1.0)
- - `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`
- - `GET /health/live` and `GET /health/ready`
- MCP (stdio, read-only): `career-search-mcp` / `python -m autoapply_agent.mcp` — see the
- [MCP server guide](docs/guides/MCP_SERVER_GUIDE.md).
- ## Documentation
- | Document | What it covers |
- |---|---|
- | [QUICKSTART.md](QUICKSTART.md) | Local setup and a first run |
- | [docs/guides/PORTFOLIO_WALKTHROUGH.md](docs/guides/PORTFOLIO_WALKTHROUGH.md) | One real job search, end to end |
- | [docs/guides/JOB_SEARCH_EXPORT_GUIDE.md](docs/guides/JOB_SEARCH_EXPORT_GUIDE.md) | Filters, CSV/JSONL export, Atom feed |
- | [docs/guides/MCP_SERVER_GUIDE.md](docs/guides/MCP_SERVER_GUIDE.md) | Read-only MCP server for AI assistants: client setup, tools, privacy |
- | [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 |
- | [ARCHITECTURE.md](ARCHITECTURE.md) | Components, run lifecycle, events |
- | [docs/API.md](docs/API.md) | HTTP API reference |
- | [CONFIGURATION.md](CONFIGURATION.md) | Environment variables and provider profiles |
- | [docs/SUPPORTED_SOURCES.md](docs/SUPPORTED_SOURCES.md) | Every source adapter |
- | [docs/USE_CASE_CATALOG.md](docs/USE_CASE_CATALOG.md) | Advisor and use-case catalog, demo gallery |
- | [SAFETY.md](SAFETY.md) | Scope boundaries and guardrails |
- | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Deployment and migrations |
- | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common failures |
- | [CONTRIBUTING.md](CONTRIBUTING.md) | Development workflow |
- | [CHANGELOG.md](CHANGELOG.md) | Release history |
- ## License
- MIT © [Francis1998](https://github.com/Francis1998)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.