Avaliador — Development agent for Claude Code
../../subagents/avaliador.md.
How to install Avaliador
Installs to ~/.claude/agents/byna1-job_hunter-avaliador.md
mkdir -p ~/.claude/agents && curl -fsSL https://raw.githubusercontent.com/byna1/job_hunter/HEAD/.claude/agents/avaliador.md -o ~/.claude/agents/byna1-job_hunter-avaliador.md Restart Claude Code, or start a new session, for it to be picked up.
What Avaliador does
A [Claude Code](https://claude.com/claude-code) agent that runs your job search end to end: it scrapes LinkedIn and Indeed for the roles you care about, scores every posting against your own profile with a
Alternatives in Development
- Avaliador Severidade — Triagem de severidade da auditoria NIST — recebe os achados confirmados e prováveis do validador-falsos-positi 1 ★
- Avaliador De Cobertura — Avaliador independente do grill temcomo
- Django Build Resolver — Django/Python build, migration, and dependency error resolution specialist 243.5k ★
Repository README
This is the README for byna1/job_hunter, shared by 4 entries
in this directory. It describes the repository, not this entry specifically.
job-hunter
A [Claude Code](https://claude.com/claude-code) agent that runs your job search end to end: it scrapes LinkedIn and Indeed for the roles you care about, scores every posting against your own profile with a fixed, auditable formula, and then writes a tailored CV (ATS-safe `.docx`) and a cover letter for each job that clears the bar. Every job becomes a markdown note you track in Obsidian. When you edit a generated CV or letter, the next run reads your edits and proposes what it should have learned — nothing enters your profile without your approval. The design goal is cheap, not clever: rules live in Python scripts (zero tokens, zero variance), and only the parts that genuinely need judgement are handed to an isolated subagent, one job at a time.
**This repository is a template.** `perfil/`, `termos.txt` and the caches ship empty or filled with clearly-marked placeholders. Fill them in with your own data before the first run.
🇧🇷 Portuguese documentation: [LEIA-ME.md](LEIA-ME.md) — same project, more detail on the internals.
**A note on languages in this repo.** `README.md`, `CLAUDE.md` and the three `perfil/` files are in English. The agent's own prompt files are still in Portuguese: `skills/*/SKILL.md`, `skills/cv/worker.md`, `skills/cv/estilo.md`, `skills/avaliacao/detalhe.md`, `skills/fonte-indeed/mcp-contrato.md`, `subagents/*.md` and `LEIA-ME.md`. They are prompts, not code, so you can translate them freely — with one exception: if you translate a heading, check first whether a script parses it (see the header comment in `perfil/criterios.md`).
Requirements
| What | Why | Notes |
|---|---|---|
| Claude Code CLI | runs the orchestrator and the headless subagents | the scripts shell out to claude -p |
| An Anthropic API key or Claude subscription | the agents cost money to run | see Costs |
| Python 3.11+ | every stage script | deps: requests, beautifulsoup4, pyyaml |
| Node 18+ | builds the .docx CV |
dep: `docx` |
| An Indeed MCP server | the Indeed source | optional — run /pipeline false to skip Indeed entirely |
| Obsidian (optional) | reading the job notes and the Controle.base tracking table |
the notes are plain markdown; Obsidian is only for comfort |
LinkedIn is scraped over plain HTTP with no MCP and no login. Be gentle: keep your term list short, or LinkedIn will rate-limit you (the scraper backs off on HTTP 429 automatically).
Installation
The project expects to live **inside a parent folder** (an Obsidian vault, in the original setup) that holds the Python environment, the Node modules and the Claude Code settings. Paths throughout the scripts are relative to that layout:
/
├── .claude/
│ ├── settings.json permissions + status line
│ ├── skills/ symlinks → agents/job_hunter/skills/{pipeline,cv}
│ └── agents/ symlinks → agents/job_hunter/subagents/*.md
├── .conda/ Python env (requests, beautifulsoup4, pyyaml)
├── package.json
├── node_modules/ docx
└── agents/
└── job_hunter/ ← this repository
1. Clone
mkdir -p /agents
git clone https://github.com/byna1/job_hunter.git /agents/job_hunter
2. Python environment
Any Python 3.11+ interpreter works; the scripts are pure stdlib except for three packages. The shipped commands assume `/.conda/bin/python`:
cd
python3 -m venv .conda # or: conda create -p .conda python=3.12
.conda/bin/pip install requests beautifulsoup4 pyyaml
If you put the interpreter somewhere else, update the three places that name it: the `allowed-tools` line in `skills/pipeline/SKILL.md`, the one in `skills/cv/SKILL.md`, and the `permissions.allow` list in `/.claude/settings.json` (step 5).
3. Node dependency (for the DOCX writer)
cd
npm init -y
npm install docx
4. Register the skills and the subagents
Claude Code discovers slash commands and subagents from the `.claude/` directory of the folder you open it in. Symlink them from the vault root so a session opened there sees `/pipeline` and `/cv`:
cd
mkdir -p .claude/skills .claude/agents
ln -s ../../agents/job_hunter/skills/pipeline .claude/skills/pipeline
ln -s ../../agents/job_hunter/skills/cv .claude/skills/cv
for a in avaliador cv-worker pesquisador-indeed revisor-cv; do
ln -s "../../agents/job_hunter/subagents/$a.md" ".claude/agents/$a.md"
done
`agents/job_hunter/.claude/agents/` already contains the same symlinks, relative to this repository. Those are the ones the **headless** `claude -p` calls use, since they run with `cwd = agents/job_hunter`. Do not delete them.
5. Settings and status line
There are **two** settings files, and they are not interchangeable — the permission patterns are matched against the command string as typed, which depends on the working directory:
agents/job_hunter/.claude/settings.json(ships with the repo, leave it alone) is the headless copy. Theclaude -psubagents run withcwd = agents/job_hunter, so its patterns are relative to that folder (Bash(../../.conda/bin/python skills/*))./.claude/settings.json(you create this) is for your interactive session, which runs from the vault root. It needs the same permissions rewritten with vault-root-relative paths — exactly the form the skills declare in theirallowed-tools. Do not copy the shipped file verbatim: none of its patterns would match, and you would be prompted on every single script call.
Create `/.claude/settings.json` with:
{
"enableArtifact": false,
"disableBundledSkills": true,
"deniedMcpServers": [
{ "serverName": "claude.ai Gmail" },
{ "serverName": "claude.ai Google Drive" },
{ "serverName": "claude.ai Google Calendar" },
{ "serverName": "claude.ai Notion" }
],
"permissions": {
"allow": [
"Bash(.conda/bin/python agents/job_hunter/skills/*)",
"Edit(agents/job_hunter/raw/**)",
"Edit(agents/job_hunter/output/**)",
"Edit(agents/job_hunter/vagas/**)",
"mcp__claude_ai_Indeed__search_jobs",
"mcp__claude_ai_Indeed__get_job_details"
]
},
"statusLine": {
"type": "command",
"command": "/.conda/bin/python /agents/job_hunter/shared/statusline.py"
}
}
The status line shows progress, tokens and cost without spending a single token.
`deniedMcpServers` matters more here than in the headless copy: this is the session that reads your real profile with you sitting in front of it, so it is the one that should *not* also hold your mail, drive, calendar and notes. Keep the block even if you trim the rest.
Drop the two `mcp__...Indeed...` entries if you are not using the Indeed source, and rename them if your MCP server registers under a different name.
Note there is deliberately **no** `Bash(node ...)` entry: the DOCX writer `gerar_cv.js` is spawned by `finalizar.py` through `subprocess.run(["node", ...])`, which never goes through the permission system. You only need such an entry if you want to run the DOCX writer by hand.
6. Indeed MCP (optional)
No Indeed MCP server ships with this repo — you configure one in Claude Code. The original setup uses the claude.ai Indeed connector (`mcp__claude_ai_Indeed__search_jobs` / `..._get_job_details`).
The parser is **text-based, not JSON**: the subagent writes the MCP's raw response to disk unedited, and `skills/fonte-indeed/scripts/indeed.py` picks out markdown lines of the exact form `**Label:** value`. Everything else in the response is ignored. So a replacement server must emit those labels:
| Tool | Arguments sent | Response must contain |
|---|---|---|
search_jobs |
search, location, country_code |
one **Job Title:** line per job (it is what separates one job from the next, so it must come first), plus **Job Id:**, **Company:**, **Location:**, **Posted on:**, **Job Type:**, **Compensation:**, **View Job URL:** |
get_job_details |
job_id (the **Job Id:** value) |
the same labels if you have them, then the full job description — the description is taken as everything after the last labelled line |
Two details that silently lose data if you get them wrong: `**Posted on:**` must be `September 15, 2026` (English month name — any other format just disables the `--dias` filter for that job, it is not dropped), and `**Job Id:**` is mandatory for any job that survives filtering. `N/A` and `None` are accepted as "field absent".
The full contract — including the `{"result": "..."}` wrapper the reader also accepts, the job-id fingerprinting, a minimal working example, and an explicit list of what the code does *not* pin down — is in [`skills/fonte-indeed/mcp-contrato.md`](skills/fonte-indeed/mcp-contrato.md). The `pesquisador-indeed` subagent is the only thing that touches the MCP. Skip this step entirely and always call `/pipeline false`.
Fill in your profile
Four files hold everything about *you*. Each ships with inline comments explaining what goes where, and with `{{PLACEHOLDERS}}` you must replace.
⚠️ **Before you push your fork anywhere public.** Once filled in, `perfil/perfil.md` and `perfil/cv-base.md` contain your home address, phone number, email and salary floor — and git will happily publish them. `.gitignore` ships with the three `perfil/` lines **commented out**, because the template needs to track them. If your fork is public, uncomment them before your first commit:
sed -i 's|^# perfil/|perfil/|' .gitignore git rm --cached perfil/perfil.md perfil/cv-base.md perfil/criterios.md # if already committedKeeping the repo private is the other valid answer. Note that `git rm --cached` does not erase anything already pushed — rewrite history or start a fresh repo if that has happened.
| File | What goes in it | When it is loaded |
|---|---|---|
perfil/perfil.md |
Compact profile: where you can work, contract, salary floor, languages, target roles, honest skill levels, one line per job, education, portfolio links. This is the source of truth — the agent may never claim a skill or a level beyond it. | Every run, in the evaluator's system prompt |
perfil/criterios.md |
The screening rules, the scoring weights and the technology vocabulary. Keep the rules; change the personal parts: your target region, your job-title categories, and the vocabulary table that maps tools to your honest level (forte / media / conhece / pv). |
Every run, and by somar.py as code |
perfil/cv-base.md |
The long version: every bullet you could ever put on a CV, one ### block per employer, plus "Angles by area" — which of those facts sell you for a finance job, a health job, a data job. The CV writer selects and rephrases from here and is forbidden from inventing anything. |
CV/letter phase only |
termos.txt |
Your search terms, one per line. Add @indeed at the end of a line to also search it on Indeed. |
Collection phase |
Profile-shaped constants elsewhere in the code
The four files above are the ones you *must* edit, but they are not the only place the example profile shows through. These four lists are tuned for a data/BI profile with a pharmacovigilance background, and still carry that domain's vocabulary. None of them will break if you leave them alone — a term that is not in a list simply is not detected — but tuning them to your field makes the output noticeably better. Each is flagged by an `AJUSTE` comment in the source:
| Where | What it does |
|---|---|
shared/comum.py → IDF_DEPARTAMENTOS, IDF_CIDADE, FORA_IDF_CIDADE |
target-region detection (ships targeting Île-de-France, France) |
shared/comum.py → EXCLUIR_CARGO |
job titles dropped on sight (ships excluding software/data engineering) |
skills/cv/scripts/briefing.py → GATILHOS |
requirement phrases highlighted in the CV briefing |
skills/fonte-linkedin/scripts/buscar_linkedin.py → TECNOLOGIAS |
technologies tagged in collected job text |
One more file is worth a look once you are running:
skills/cv/estilo.md— how your CVs should read (voice, bullet formula, structure). The "Regras aprendidas" section at the bottom is filled by the agent from your own edits, with your approval. This file is in Portuguese.
Usage
Open Claude Code **in the vault root**, not inside `agents/job_hunter`, then:
/model sonnet
The `model: sonnet` in a skill's frontmatter only applies to the turn that invokes it — set the session model yourself. The status line shows a ⚠ if a task is running under Opus.
`/pipeline [days] [indeed true|false]`
A full round: learn from your edits → collect → screen → score → you approve → write CVs.
/pipeline # jobs posted in the last day, Indeed included
/pipeline 3 # last 3 days
/pipeline 3 false # last 3 days, LinkedIn only
The round stops twice and waits for you:
- STOP 1 — you get the ranking table (top 10, score ≥ 50), the low-confidence jobs to review, any source that failed, the cost so far, and — if you edited CVs since last time — a proposal of what the agent should learn. You answer two questions: create the notes? (all / drop X) and apply the learning? Nothing is written until you do.
- STOP 2 — one
.docxCV and one cover letter per new job, each with a line saying what was adapted for that posting. You review and send.
Everything up to STOP 1 is a **single background call** (`rodada.py preparar`). The orchestrator never reads job text and never dispatches subagents itself — the scripts run them headless. Do not ask for progress in the chat: each question makes the orchestrator re-read its whole context. Watch the status line instead:
Sonnet · █████████░░░░░░░░░░░ 45% Avaliação · triagem: lote 3/7 · 4 min · tokens 312k (saída 41k) · US$ 0.84
The script prints in Portuguese: *Avaliação* = evaluation stage, *triagem: lote 3/7* = screening, batch 3 of 7, *saída* = output tokens.
`/cv [url] `
For a job you found yourself. Paste the full posting text; the URL is optional (with a LinkedIn or Indeed URL, the job is added to the cache so it will not come back in future searches). You get a note in `vagas/` with no score, plus a CV and a cover letter. A job you already have a note for is refused and nothing is created.
After a round
.conda/bin/python agents/job_hunter/skills/pipeline/scripts/auditar.py
Reads the session transcript and checks it against the design: orchestrator model, subagent types and models, one job per cv-worker, forbidden reads/edits, estimated cost. Costs nothing. It prints `OK: seguiu o desenho` ("followed the design") when the session behaved, or lines starting with `PROBLEMA:` ("problem") when it did not — fix those in a fresh chat. If you use Claude Code across many projects, set `JOB_HUNTER_SESSOES` to a glob that matches your vault's transcript folder.
If something breaks mid-round
Stop. Do not fix it in the running session — that is the single most expensive thing you can do (a round that turned into a repair session under Opus cost US$ 5.24, versus US$ 1.2 for the evaluation itself). Fix it in a fresh chat, then resume the evaluation without re-collecting:
.conda/bin/python agents/job_hunter/skills/avaliacao/scripts/avaliar.py # only evaluates what is missing
Do not re-run `/pipeline`: it wipes `raw/rodada/`.
How the folders map to the flow
/pipeline [days] [indeed] ── orchestrator (sonnet), routes only
│
1. Prepare ─── ONE background script (rodada.py preparar)
│ ├─ Start caches ← note statuses · clears the previous round
│ │ edited CVs/letters? → headless revisor-cv proposes what to learn
│ ├─ Collect LinkedIn (script) · Indeed (1 headless pesquisador-indeed per term)
│ ├─ Consolidate drops duplicates, known jobs, hard cuts, internships, out-of-region-no-remote,
│ │ and the seniority pre-cut — before any job text enters a context
│ └─ Evaluate avaliar.py: headless evaluators, batches of 5, 4 at a time
│ phase 1 triagem (facts for all) → somar.py (score) → phase 2 detalhe (prose,
│ only for the jobs that become notes)
│
⏸ STOP 1 ── you approve the notes and the learning → criar_notas.py · rodada.py marcar
│
2. CV ──────── ONE background script (gerar_cvs.py)
│ one briefing per job → 1 headless cv-worker (opus) per job, 4 at a time
│ → DOCX + letter + note · checks for near-identical letters and redoes one
│
⏸ STOP 2 ── you review and send
| Folder | Role |
|---|---|
perfil/ |
Your profile, your criteria, your CV material. The only files you must fill in. |
skills// |
One folder per stage: SKILL.md (the prompt) + scripts/ (the rules). pipeline, cv, avaliacao, fonte-linkedin, fonte-indeed, aprendizado, and fonte-wttj (stub, not implemented — the orchestrator skips it). |
subagents/ |
The four subagent definitions: pesquisador-indeed (haiku), avaliador (sonnet), revisor-cv (sonnet), cv-worker (opus). |
shared/ |
comum.py (paths, cuts, dedup, headless calls, progress) and statusline.py. |
templates/vaga.md |
The job-note template the pipeline instantiates. |
vagas/ |
One markdown note per job. example-company-data-analyst.md shows the frontmatter schema. |
output/ |
One folder per job: briefing, cv.json, the DOCX, carta.md, and .gerado/ (the generated version, used to diff your edits). |
cache/ |
consultadas.json (seen) and enviadas.json (applied). Scripts only — never read these into a context. |
raw/ |
textos/ (full job texts, the CV briefing reads from here), rodada/ (current round, wiped each /pipeline), progresso.json (the status line). |
The split is deliberate: **anything that is a rule lives in a script** — it costs no tokens and never varies. **Anything that needs judgement goes to a subagent**, one job at a time, in a clean context. That isolation is what stops the system from producing ten near-identical cover letters.
Costs
Measured on real rounds, at list prices. Your mileage depends on how many jobs your terms return.
| Stage | Cost |
|---|---|
| Prepare, through STOP 1 (collection + evaluation + learning reviewer) | ~US$ 1.20 |
| CV, first worker of the phase (writes the prompt cache) | US$ 0.31 |
| CV, every worker after that | US$ 0.21 each |
A single /cv |
~US$ 0.31 |
The token discipline that gets it there, in case you fork and change things:
- Filter before reading. Duplicates, known jobs, hard cuts and the seniority pre-cut are removed by
rodada.py consolidarbefore a single job description enters any context. - One background call per phase. Subagents launched with the
Agenttool always run in the background, and every completion notification wakes the orchestrator to re-read its whole context (16 wake-ups, ~US$ 0.05 each, on one 10-CV round). Running them headless inside a script means the orchestrator wakes once per phase instead. - Two-phase evaluation. Free prose was 71% of the evaluation bill, and ~85% of jobs are discarded without anyone reading it. Phase 1 extracts only the facts the score needs; phase 2 writes prose only for the jobs that actually become notes.
- Stable prompt cache. The fixed block (instructions + criteria + profile) goes in the system prompt
via
--append-system-prompt, byte-identical across batches; the jobs go in the message. The first batch runs alone to write the cache. Put anything batch-specific in that block and the cache dies. - Keep the evaluator's thinking on. It is the largest single line of the evaluation bill (78% of
output tokens on one batch) and it is still worth it: with thinking off, the model swaps specific
tools for generic words that miss the
criterios.mdvocabulary, and flips the job category and the language field — 30 points on a 50-point cutoff, for US$ 0.009 saved per job. - Never change the rules mid-round. Stop, fix in a fresh chat, resume.
- Build the CV by editing, not rewriting.
cv-base.md+ targeted edits (summary line, skill order, 2–3 bullets). Never from scratch.
Models: orchestrator `sonnet` · evaluator and learning reviewer `sonnet` · Indeed researcher `haiku` · CV writer `opus`.
Language
**CVs and cover letters are always written in English**, including for French-language postings. That is a deliberate default for the original user, who did not yet interview in French: the agent extracts keywords from a French posting and uses their natural English equivalents, keeping company, tool and product names exact.
To change it, edit the rule in all three places that state it, or they will fight each other:
CLAUDE.md→ "Writing rules (CV + letters)"skills/cv/worker.md→ "Regras do CV" and "Regras da carta"skills/cv/estilo.md→ if you also want a different voice or structure
The **evaluation** language is independent: `perfil/criterios.md` scores a posting on whether it demands the local language, using the levels you declare in `perfil/perfil.md`. Set those to your own languages and the scoring follows.
License
MIT — see [LICENSE](LICENSE).
Related Agents
Src/agents/ — 11 Agent Definitions
Generated: 2026-04-11
Cavecrew Builder
Cavecrew Investigator
Gitnexus Branch Hygiene Reviewer
GitNexus branch hygiene and mergeability reviewer. Use to classify merge state, conflicts, stale branches, mer
Gitnexus Docs Dod Reviewer
GitNexus docs and Definition-of-Done reviewer. Use to translate repo guidance, linked issues, changed domains,
Ccxt PR Reviewer
End-to-end review of a CCXT pull request. Reads the diff, transpiles and builds in all six languages (TS/JS, P