HH Applicant Tool

!Publish to PyPI

Группа поддержки в Телеграме (для всех моих утилит и просто для общения)

[!IMPORTANT]

Ищу почасовую или проектную @feedback_s3rgeym_bot (Python, Vue.js, DevOps). Не пишите туда с вопросами по утилите. Для них есть канал!!! Так же буду благодарен, если посоветуете меня в качестве сись-пись админа, погромиста и девжопса своим знакомым, начальству... Имею огромный опыт фриланса (это может и не нравится тупопездым идиотинам, мнящим себя дохуя специалистками по подбору), но наебизнес ценит тех, кто умеет решать проблемы быстро, не задавая лишние вопросы и без надзирателей... С овчарами общаться желания нет (не знаю как другим, но мне тошнит от них).

[!IMPORTANT]

Проект запрещено использовать в коммерческих проектах, а так же любых проектах

с закрытым исходным кодом.

Остерегайтесь мошенников! Существует мошеннический сайт HH Applicant Tool,

который использует название проекта для привлечения клиентов. К проекту

отношения он не имеет!!! Все барыги торгующие моей утилитой прокляты в веках!

Авторские права на изображение принадлежат Кандинскому... нет, не человеку, а боту от сбера

☕ Поддержать проект

• HH Applicant Tool

Установка

Утилиту можно установить из PyPi или скачать из репозитория. Из остальных мест ее скачивать не рекомендуется.

Установка:

# Стандартный pip (в Linux только в виртуальное окружение получится установить)
$ pip install hh-applicant-tool
Чтобы утилита поддерживала команду ui
$ pip install 'hh-applicant-tool[ui]'
Но лучше использовать pipx
$ pipx install hh-applicant-tool
Последнюю версию можно установить через git
$ pipx install "git+https://github.com/s3rgeym/hh-applicant-tool"
Для обновления до новой версии
$ pipx upgrade hh-applicant-tool

pipx добавляет исполняемый файл hh-applicant-tool в ~/.local/bin, делая эту команду доступной. Путь до ~/.local/bin должен быть в $PATH (в большинстве дистрибутивов он добавлен).

Использование виртуальных окружений в Linux/Mac:

mkdir -p ~/.venvs
python -m venv ~/.venvs/hh-applicant-tool
Это придется делать постоянно, чтобы команда hh-applicant-tool стала доступна
.  ~/.venvs/hh-applicant-tool/bin/activate
pip install hh-applicant-tool

Отдельно я распишу процесс установки в Windows в подробностях:

• Для начала поставьте последнюю версию Python 3 любым удобным способом.
• Запустите PowerShell (не CMD.EXE, блять, а именно поверщель) от Администратора и выполните:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

Данная политика разрешает текущему пользователю (от которого зашли) запускать скрипты. Без нее не будут работать виртуальные окружения.

Далее можно поставить pipx и вернуться к инструкции вверху раздела:

• Всё так же от администратора выполните:

python -m pip install --user pipx

А затем:

python -m pipx ensurepath

• Перезапускаем Terminal/Powershell и проверяем:

pipx -h

С использованием вирт. окружений:

• Создайте и активируйте виртуальное окружение:

PS> python -m venv hh-applicant-venv
  PS> .\hh-applicant-venv\Scripts\activate

• Поставьте все пакеты в виртуальное окружение hh-applicant-venv:

(hh-applicant-venv) PS> pip install hh-applicant-tool

• Проверьте, работает ли оно:

(hh-applicant-venv) PS> hh-applicant-tool -h

• В случае неудачи вернитесь к первому шагу.
• Для последующих запусков сначала активируйте виртуальное окружение.

Авторизация

Авторизация по коду:

hh-applicant-tool authorize '<ваш телефон>'

Проверка авторизации:

$ hh-applicant-tool whoami
🆔 27405918 Кузнецов Андрей Владимирович [ 📄 1 | 👁️ +115 | ✉️ +28 ]

В случае успешной авторизации токены будут сохранены в config.toml:

[token]
access_token = "USERAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
refresh_token = "USERBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
access_expires_at = 1799999999

Токен доступа выдается на две недели. Он обновляется автоматически. Для его ручного обновления нужно выполнить:

hh-applicant-tool refresh-token

Помните, что у refresh_token тоже есть время жизни, поэтому может потребоваться полная авторизация.

Описание команд

Примеры команд:

# Общий вид: сначала глобальные настройки, затем команда и её аргументы
$ hh-applicant-tool [options] <operation> [args]
Справка по глобальным флагам и список операций
$ hh-applicant-tool -h
Справка по операции
$ hh-applicant-tool authorize -h
Авторизуемся
$ hh-applicant-tool authorize
Авторизация с использованием другого профиля
$ hh-applicant-tool --profile profile123 authorize
Рассылаем заявки
$ hh-applicant-tool apply-vacancies
Для тестирования поисковой строки и других параметров, используйте --dry-run.
С ним отклики не отправляются, а лишь выводятся сообщения
$ hh-applicant-tool -vv apply-vacancies --search "Python программист" --per-page 3 --total-pages 1 --dry-run
Фильтруем вакансии по исключаемым словам (fullstack, junior, php и т.п.)
$ hh-applicant-tool apply-vacancies --search "Python backend" --excluded-filter "fullstack,junior,php,java" --dry-run
Поднимаем резюме
$ hh-applicant-tool update-resumes
Ответить работодателям
$ hh-applicant-tool reply-employers
Просмотр лога в реальном времени
$ hh-applicant-tool log -f
Посмотреть содержимое конфига
$ hh-applicant-tool config
Редактировать конфиг в стандартном редакторе
$ hh-applicant-tool config -e
Вывести значение из конфига
$ hh-applicant-tool config -k token.access_token
Установить значение в конфиге, например, socks-прокси
$ hh-applicant-tool config -s proxy_url socks5h://localhost:1080
Удалить значение из конфига
$ hh-applicant-tool config -u proxy_url
Утилита все данные об откликах хранит в SQLite
$ hh-applicant-tool query 'select count(*) from vacancy_contacts;'
Экспорт контактов в csv
$ hh-applicant-tool query 'select * from vacancy_contacts' --csv -o
contacts.csv
Выполнение запросов в интерактивном режиме
$ hh-applicant-tool query
Чистим отказы
$ hh-applicant-tool clear-negotiations
При обновлении может сломаться схема БД, для ее починки нужно выполнить
поочерёдно все миграции, добавленные после выхода последней версии
$ hh-applicant-tool migrate
List of migrations:
[1]: 2026-01-07
Choose migration [1] (Keep empty to exit): 1
✅ Success!
Вывести все настройки
$ hh-applicant-tool settings
Получить значение по ключу
$ hh-applicant-tool settings auth.username
Установить email, используемый для автологина
$ hh-applicant-tool settings auth.username '[email protected]'

Глобальные настройки:

• -v используется для вывода отладочной информации. Два таких флага, например, выводят запросы к API.
• -c путь до каталога, где хранятся конфигурации.
• --profile можно указать профиль, данные которого будут храниться в подкаталоге.
• --use-kitty/--use-sixel использовать опр протокол для отображения капчи

• --use-ai/--ai использовать автоматизацию распознания капч и прочих

| Операция | Описание | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | authorize, auth | Авторизация на hh.ru. Введенные логин и пароль "запоминаются" и будут использованы при следующем вызове команды. | | logout | Выйти из профиля (отозвать токен) | | ui | Запуск UI для рассылки и управления откликами | | whoami, id | Выводит информацию об авторизованном пользователе | | list-resumes, list, ls | Список резюме | | update-resumes, update | Обновить все резюме. Аналогично нажатию кнопки «Обновить дату». | | clone-resume | Клонировать резюме | | apply-vacancies, apply | Откликнуться на подходящие вакансии. Если указана строка для поиска (--search), то поиск будет произведен по вакансиям, иначе по списку рекомендованных вакансий. Лимит = 200 в день. На HH есть спам-фильтры, так что лучше не рассылайте отклики со ссылками, иначе рискуете попасть в теневой бан. | | reply-employers, reply | Ответить во все чаты с работодателями, где нет ответа либо не прочитали ваш предыдущий ответ | | autoresponder | ИИ-автоответчик, который отвечает в чатах с работодателями в тч на тесты | | clear-negotiations | Отмена откликов | | clear-skipped | Очистка базы пропущенных вакансий. С флагом --reason можно указать конкретную причину (ai_rejected, excluded_filter). | | call-api, api | Вызов произвольного метода API с выводом результата. | | refresh-token, refresh | Обновляет access_token. | | config | Показывает содержимое конфига. С флагом -e открывает его для редактирования. | | settings | Просмотр и управление настройками в базе данных. Простое key-value хранилище. | | install | Устанавливает зависимости, такие как браузер Chromium, необходимые для авторизации. | | uninstall | Удаляет браузер Chromium, используемый для авторизации. | | check-proxy | Проверяет используемые прокси | | migrate | Починить базу | | query | Выполнение SQL-запросов к базе. Схема БД находится в файле schema.sql. Если скормить ее DeepSeek, то он поможет написать любой запрос. | | log | Просмотр файла-лога. С флагом -f будет следить за изменениями. В логах частично скрыты идентификаторы в целях безопасности. |

[!IMPORTANT]

Почитайте про язык для поисковых запросов. Он позволяет отсеивать мусор при поиске подходящих вакансий, например, (Go OR Golang) NOT PHP NOT JavaScript.

Утилита использует систему плагинов. Все они лежат в operations. Модули, расположенные там, автоматически добавляются как доступные команды. За основу для своего плагина можно взять whoami.py.

Для тестирования запросов к API используйте команду call-api совместно с jq для обработки JSON.

Пример поиска работодателей:

$ hh-applicant-tool call-api /employers text="IT" only_with_vacancies=true | jq -r '.items[].alternate_url'
https://hh.ru/employer/1966364
https://hh.ru/employer/4679771
...

Синтаксис call-api немного похож на httpie или curlie:

hh-applicant-tool call-api [{GET|POST|PUT|DELETE}] <endpoint> [<key=value> ...]

Если используется метод GET или DELETE (или ничего не указано), то параметры будут переданы как query string. Во всех остальных случаях параметры передаются как application/x-www-form-urlencoded в теле запроса.

Для поиска вакансий по региону в apply-vacancies нужно указать параметр area. Можно его указывать как для страны (каз - 40, бел - 2238), так и отдельного города (мск - 1).

Список area id по стране:

hh-applicant-tool -vv api /areas | jq -r '.[] | select(.name == "Беларусь")'

Документация для работы с API соискателей была удалена с ха-ха.сру и его корпоративного репозитория. Можете не искать, они затерли даже историю репозитория. Но я через веб-архив выкачал документацию. Чтобы ее посмотреть, клонируйте этот репозиторий и откройте файл ./docs/hhapi/openapi.yml, например, с помощью Swagger Viewer.

Также существуют CLI-утилиты:

sudo pacman -S openapi-tui
openapi-tui --input docs/hhapi/openapi.yml

Для тех, кто любит просматривать документацию в браузере:

npx @redocly/cli preview -d docs/hhapi

Потом нужно открыть в браузере http://localhost:4000.

[!NOTE]

Отдельные замечания у меня к API HH. Оно пиздец какое кривое. Например, при создании заявки возвращается пустой ответ либо редирект, хотя по логике должен возвращаться созданный объект. Также в ответах сервера нет Content-Length. Из-за этого нельзя узнать, есть ли тело у ответа сервера, нужно его пробовать прочитать. Я так понял, там какой-то прокси оборачивает все запросы и отдает всегда Transfer-Encoding: Chunked. А еще он возвращает 502 ошибку, когда бэкенд на Java падает либо долго отвечает (таймаут).

По сути, никакие дополнительные команды, кроме имеющихся, не нужны. Вы можете сделать что угодно с помощью call-api, но если хочется чего-то особенного, можно добавить свои команды.

Капча

Если вызов какого-то метода API генерирует ошибку капчи, то она перехватывается, а далее происходит следующее:

• при флаге --use-ai капча будет распознаваться нейронкой
• иначе:

Некоторые модели плохо распознают русский язык, английский для можно установить с помощью передачи --captcha-lang EN.

Диалог для ввода капчи

Запуск через Docker

Это рекомендованный разработчиком способ. Если не работает стандартная установка, то используйте его. Также это самый простой способ запуска и использования утилиты, требующий скопипастить 5 команд.

Для начала нужно установить docker и docker-compose:

sudo apt install docker.io docker-compose-v2

Выкачиваем репозиторий и переходим в каталог:

git clone https://github.com/s3rgeym/hh-applicant-tool
cd hh-applicant-tool

[!IMPORTANT]

Команды с docker-compose нужно запускать строго, находясь в данном каталоге!

Теперь авторизуемся:

# Чтобы ввести капчу в терминале укажите флаги --use-sixel/-s или --use-kitty/-k
Это названия протоколов, которые исп-ся терминалом для отображения изображений
Sixel поддерживается большинством терминалов
А вот Windows Terminal поддерживает только Kitty
docker-compose run -u docker -it hh_applicant_tool \
  hh-applicant-tool -s -vv auth <username>

Если использовать флаг --ai, то капча будет разгадана нейронкой и останется только ввести код подтверждения из SMS/Email.

Подробно про авторизацию можно почитать здесь.

В случае успешной авторизации можно запускать рассылку откликов по крону:

docker-compose up -d

Что будет делать?

• Рассылать отклики со всех опубликованных резюме.
• Поднимать резюме.

docker compose logs -f

Чтобы прекратить просмотр логов, нажмите Ctrl-C.

Информацию об ошибках можно посмотреть в файле config/log.txt, а контакты работодателей — в config/data с помощью sqlite3. В config/config.toml хранятся токены, дающие доступ к аккаунту.

Также советую отредактировать файл letter.txt.

Запущенные сервисы докер стартуют автоматически после перезагрузки. Остановить их можно выполнив:

docker-compose down

Чтобы обновить утилиту, в большинстве случаев достаточно в каталоге выполнить:

git pull

В редких случаях нужно пересобрать все:

docker compose up -d --build

Чтобы рассылать отклики с нескольких аккаунтов, нужно переписать docker-compose.yml:

services:
  # Не меняем ничего тут
  hh_applicant_tool:
    # ...
# Добавляем новые строки
# Просто копипастим, меняя имя сервиса, container_name и значение HH_PROFILE_ID
  hh_second:
    extends: hh_applicant_tool
    container_name: hh_second
    environment:
      - HH_PROFILE_ID=second
hh_third:
    extends: hh_applicant_tool
    container_name: hh_third
    environment:
      - HH_PROFILE_ID=third
# Общий шаблон для новых профилей
  уникальное_имя_сервиса:
    extends: hh_applicant_tool
    # может совпадать с именем сервиса
    container_name: уникальное_имя_контейнера
    environment:
      - HH_PROFILE_ID=название_профиля

[!IMPORTANT]

В этом файле важны отступы!

Обратите внимание на HH_PROFILE_ID — его значение указывается при авторизации, если профиль отличен от дефолтного. Далее нужно авторизоваться в каждом профиле:

# Авторизуемся со второго профиля
docker-compose exec -u docker -it hh_applicant_tool \
  hh-applicant-tool --profile-id second -k auth
Авторизуемся с третьего профиля
docker-compose exec -u docker -it hh_applicant_tool \
  hh-applicant-tool --profile-id third -k auth
И так далее

Ну и выполнить docker-compose up -d, чтобы запустить новые сервисы.

Команды можно потестировать в запущенном контейнере:

$ docker-compose exec -u docker -it hh_applicant_tool bash
docker@1897bdd7c80b:/app$ hh-applicant-tool config -p
/app/config/config.toml
docker@1897bdd7c80b:/app$ hh-applicant-tool refresh-token
ℹ️ Токен не истек, обновление не требуется.
docker@1897bdd7c80b:/app$

[!IMPORTANT]

Обратите внимание, что docker-compose exec/docker-compose run запускаются с аргументами -u docker. Только для пользователя docker установлен chromium, необходимый для авторизации, а также это избавляет от проблем с правами, когда созданные файлы для изменения требуют root-права.

Если хотите команду apply-vacancies вызывать с какими-то аргументами, то создайте в корне файл apply-vacancies.sh:

#!/bin/bash
Пример с фильтрацией по исключаемым словам
/usr/local/bin/python -m hh_applicant_tool apply-vacancies \
  -l letter.txt \
  --excluded-filter "fullstack|junior|php" # укажите любые аргументы

В файлах startup.sh и crontab замените /usr/local/bin/python -m hh_applicant_tool apply-vacancies на /bin/sh /app/apply-vacancies.sh.

Использование AI

Конфигурация AI

[!IMPORTANT]

То что тут в примерах были указаны эндпоинты Chat GPT НЕ ОЗНАЧАЕТ, ЧТО УТИЛИТА

НЕ МОЖЕТ РАБОТАТЬ С ДРУГИМИ ПРОВАЙДЕРАМИ! ОНА РАБОТАЕТ С ЛЮБЫМИ!!!

Отредактируйте конфиг:

hh-applicant-tool config -e

Универсальный конфиг AI/OpenAI задается в секции openai с полями api_key, base_url, model, delay и system_prompt. Дополнительные должны начинаться с openai_. Каждая команда использует какие-то свои доп. секции. Настройкт из основной секции наследуются дополнительными и в них могут быть переопределены.

[openai]
api_key = "ВАШ_API_КЛЮЧ"
base_url = "https://api.openai.com/v1/chat/completions"
model = "gpt-4o-mini"
[openai_captcha]
Тут можно задать другие
base_url = ''
api_key = ''
model = ''
temperature = 0.0
max_completion_tokens = 20

OpenAI — это стандарт через который через REST API происходит общение с вашим

хуИИ. Фактически он единственный...

api.openai.com указан в качестве примера. Утилита работает с любыми

провайдерами хуИИ в тч с локальными

При использовании Docker нужно указывать IP хоста вместо localhost, например http://192.168.1.100:11434/v1/chat/completions

Таймауты задаются полями timeout (весь запрос: соединение и чтение ответа, по умолчанию 30 секунд) и connect_timeout (только соединение, по умолчанию 5 секунд), либо флагами --openai-timeout и --openai-connect-timeout. Если модель отвечает медленно, увеличивайте timeout.

AI-фильтрация вакансий

Функция AI-фильтрации позволяет автоматически отсеивать неподходящие вакансии перед откликом. AI анализирует ваше резюме и сравнивает его с требованиями вакансии.

Режимы фильтрации

[!IMPORTANT]

Я эту хуйню выкину, так как никто нейрослоп править не хочет

heavy - должность, навыки, опыт работы, задачи, технологи

light - быстрая оценка по названию резюме и ключевым навыкам

custom - полный контекст вакансии и резюме, но со своим системным промптом через --ai-filter-prompt (резюме добавляется в конец промпта блоком «Кандидат»)

Примеры использования

# Полный анализ вакансий
hh-applicant-tool --ai apply-vacancies --ai-filter heavy
Быстрый анализ
hh-applicant-tool --ai apply-vacancies --ai-filter light
С кастомным rate limit
hh-applicant-tool --ai apply-vacancies --ai-filter heavy --ai-rate-limit 20
С собственным системным промптом
hh-applicant-tool --ai apply-vacancies --ai-filter custom --ai-filter-prompt "Откликайся только на вакансии для Python-разработчика"

Параметры фильтрации

[!CAUTION]

Эти параметры я планирую удалить в рамках борьбы с нейрослопом в коде

• --ai-filter — режим фильтрации: heavy, light или custom
• --ai-rate-limit — ограничение запросов к AI в минуту (по умолчанию 40)
• --ai-filter-prompt — системный промпт для AI-фильтра. Используется только в режиме custom

Решение тестов при отклике

На некоторые вакансии HeadHunter требует пройти тест перед откликом. В REST API нет отдельного метода для решения тестов, поэтому утилита выполняет их через веб-версию сайта: открывает страницу отклика, разбирает встроенный JSON с вопросами и отправляет ответы обратно веб-формой.

Ответы на тест генерируются двумя способами:

• Быстрый (по умолчанию): без AI. Выбирается вариант «Да», если он есть, иначе —

• Через AI: при запуске с --use-ai и настроенной секцией openai_cover_letter

Управление поведением:

• --skip-tests — пропускать вакансии с тестами и не решать их вовсе.
• --dry-run — «решить» тест виртуально, без реальной отправки.

Шаблоны сообщений

Команды apply-vacancies и reply-employers поддерживают специальный формат сообщений.

Также в сообщении можно использовать плейсхолдеры:

• %(vacancy_name)s: Название вакансии.
• %(vacancy_url)s: Ссылка на вакансию.
• %(employer_name)s: Название работодателя.
• %(first_name)s: Имя пользователя.
• %(last_name)s: Фамилия пользователя.
• %(email)s: Email пользователя.
• %(phone)s: Телефон пользователя.
• %(resume_title)s: Название резюме.
• %(resume_hash)s: Идентификатор резюме.
• %(resume_url)s: Ссылка на резюме.

Меня заинтересовала ваша вакансия %(vacancy_name)s. Прошу рассмотреть мою кандидатуру. С уважением, %(first_name)s %(last_name)s.

Также можно делать текст уникальным с помощью {}. Внутри них через | перечисляются варианты, один из которых будет случайно выбран:

Увольте того {идиота|придурка}, который придумал этот {тупой|сраный|дурацкий} вопрос.

В итоге получится что-то вроде:

Увольте того идиота, который придумал этот сраный вопрос.

{} могут быть вложенными.

Данные приложения

Данные приложения хранятся по следующим путям:

| OS | Путь | | ----------- | -------------------------------------------------------- | | Windows | C:\Users\%username%\AppData\Roaming\hh-applicant-tool\ | | macOS | ~/Library/Application Support/hh-applicant-tool/ | | Linux | ~/.config/hh-applicant-tool/ |

Конфигурационный файл

В TOML разрешены multiline strings (в русском line и string переводятся

одинаково, многострочные строки звучит тупо), что делает его удобным для

хранения различных шаблонов

Главный конфиг называется config.toml. Он содержит токены. Полный путь до конфигурационного файла можно вывести с помощью команды:

hh-applicant-tool config -p

Через конфиг можно задать дополнительные настройки. Значения вложенных полей указываются через точку (например, config --set smtp.host smtp.yandex.ru):

| Имя атрибута | Описание

... (README truncated for length)