Hiring Agent Setup Guide: Gemini, Codex and Claude Code

Understand the features, copy one setup prompt, or install manually on Windows, macOS and Linux.

What is Hiring Agent?

[Hiring Agent](https://github.com/interviewstreet/hiring-agent) is an open-source Python project from interviewstreet that turns a resume PDF into structured information and a role-based evaluation. It can add public GitHub evidence and explain category scores, strengths and areas to improve.

A resume review aid, not an ATS The upstream project explicitly says it is not an applicant tracking system or a HackerRank customer product. A score is a model's assessment against a particular rubric, not a universal ATS score, hiring recommendation or guarantee of an interview.

From PDF to review

1. Choose a resume PDF
2. Extract text and structured sections
3. Enrich with GitHub evidence when available
4. Evaluate against a selected role
5. Read evidence and review the result

This guide was checked against upstream source on 7 September 2026. Installation and paid model execution have not been tested by RexxuLabs for this guide. Check the current provider catalogue before spending API credits.

Features and practical limits

The repository is MIT licensed. That permits reuse with the license notice retained; dependency licenses and model/service terms still need separate review for a hosted product.

Choose your installation route

The one-prompt route is assisted installation, not a guaranteed unattended installer. Your coding assistant subscription does not include Gemini API usage. No Gemini key is needed just to read this guide.

One-prompt installation with Codex or Claude Code

Open Codex or Claude Code in an empty working folder. Copy the complete prompt below. The assistant should check your machine and guide you through entering the key locally. Do not paste a real key into chat.

Set up https://github.com/interviewstreet/hiring-agent in a new local folder.
Use Gemini as the backend. This is a local resume evaluation setup, not a web deployment.

1. Check my OS, Git and Python. Prefer Python 3.11, matching the repository's
   documented version. Inspect the current README, requirements.txt, config.py,
   providers.json, .env.example and score.py before choosing commands.
2. Clone the official repository without overwriting an existing folder.
   Record git rev-parse HEAD in the setup report.
3. Create an isolated .venv and install requirements with that environment's
   Python. Do not install packages globally or change system security settings.
4. Copy .env.example to .env only if .env does not already exist.
   Choose a Gemini model present in providers.json and available to my account.
   Use gemini-2.5-flash only if it is still supported; otherwise explain the change.
5. Ask me to enter my Gemini API key directly into the local .env file using
   my editor. Never ask me to paste the key into this chat, print it, commit it,
   or include it in logs. Ensure .env is ignored by Git.
6. Run pip check and python score.py --help using .venv's Python.
7. Ask for a synthetic or redacted test PDF path and explain that extracted
   resume content is sent to Google Gemini. Run only after I provide that PDF
   for this test. Use --role software_engineering_intern if the role exists.
8. Before the test, explain DEVELOPMENT_MODE caching and CSV output. For a
   privacy-first test set DEVELOPMENT_MODE = False in config.py; preserve the
   previous value in the report. Do not delete existing caches or user data.
9. Check actual output for category scores and evidence. An exit code alone
   does not prove evaluation succeeded. Report provider errors honestly.
10. Give me the exact command to run again, installed versions, commit ID,
    files changed and test status. Do not call a score an ATS pass probability
    or use it to automatically reject a candidate.

Do not install Ollama or download a local model unless I choose that route.
Do not send resumes anywhere except the Gemini service configured for this test.
Stop on an unresolved error and explain the smallest practical fix.

Manual installation: Windows PowerShell

Install Git and Python 3.11 first if missing. These commands deliberately use the virtual environment's executable so PowerShell activation-policy changes are unnecessary. Run one line at a time and stop if it fails. Choose a parent folder where hiring-agent does not already exist.

git --version
py -3.11 --version
git clone https://github.com/interviewstreet/hiring-agent.git
cd hiring-agent
git rev-parse HEAD
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip check
if (!(Test-Path .env)) { Copy-Item .env.example .env }
notepad .env

Manual installation: macOS or Linux

Use Python 3.11 where available. If python3.11 is missing, install it using the official Python installer or your OS package manager. On Linux the matching venv package may also be needed. Start in a directory without an existing hiring-agent clone.

git --version
python3.11 --version
git clone https://github.com/interviewstreet/hiring-agent.git
cd hiring-agent
git rev-parse HEAD
python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
[ -f .env ] || cp .env.example .env

Open .env in your local text editor. Keep the recorded commit ID so you can tell which version produced a result.

Configure Gemini securely

Create a key in [Google AI Studio](https://aistudio.google.com/apikey). In your local .env, replace the placeholder with your own key and select a supported model that also exists in providers.json. The example below is a configuration example, not a promise that the model is available to every account.

DEFAULT_MODEL=gemini-2.5-flash
GEMINI_API_KEY=replace_locally_with_your_own_key

Check [Gemini model availability](https://ai.google.dev/gemini-api/docs/models) and [API pricing](https://ai.google.dev/gemini-api/docs/pricing). One evaluation can make multiple model calls. If the model is unavailable, choose a currently supported option and ensure its ID is configured in providers.json.

git check-ignore .env

Check where resume data goes With Gemini, extracted resume content is sent to Google for inference. Use a synthetic or redacted PDF first. DEVELOPMENT_MODE in config.py enables local caching and CSV export; set it to False to disable those development outputs. This does not remove old files or guarantee that terminal output contains no personal data.

Run your first evaluation

Save your test file as resume/my-resume.pdf, or replace that path with the actual PDF path. The current CLI requires --role. First check help, then run the evaluation.

.\.venv\Scripts\python.exe score.py --help
.\.venv\Scripts\python.exe score.py "resume/my-resume.pdf" --role software_engineering_intern

.venv/bin/python score.py --help
.venv/bin/python score.py "resume/my-resume.pdf" --role software_engineering_intern

A successful result should contain an evaluation with category scores and evidence. Review the extracted facts against the PDF. With development mode enabled, look for resume_evaluations_software_engineering_intern.csv and files under cache/. A zero exit code or an empty cache is not proof of a successful evaluation.

Alternative: local inference with Ollama

Install [Ollama](https://ollama.com/) from its official site and ensure its service is running. Select a model listed in providers.json that your machine can support. For example, gemma3:1b is a smaller listed option; its output quality can differ substantially from a hosted model.

ollama pull gemma3:1b
ollama list

DEFAULT_MODEL=gemma3:1b

Run the same scoring command for your operating system. If Ollama is not already running, start ollama serve in a separate terminal. Local inference does not mean zero network activity: model downloads and GitHub enrichment can still access the internet.

Custom roles and interpreting results

The supplied software_engineering_intern role evaluates open source, personal projects, production experience and technical skills, with bonus points and deductions. Inspect roles/software_engineering_intern/role.json for exact weights in your checkout.

.venv/bin/python score.py --init-role backend_engineer

Edit roles/backend_engineer/role.json, criteria.jinja and system_message.jinja before using --role backend_engineer. The scaffold is not a finished rubric. Treat repeated-score differences as uncertainty, and avoid presenting the result as a validated measure of employability. Missing public GitHub work is not evidence that a person lacks engineering ability.

Troubleshooting

Can this become a RexxuLabs website tool?

Yes. A proposed first version would let a signed-in user upload their own PDF, choose a role, add their Gemini key, and receive an evidence-based report. This guide is available now; the hosted evaluator and saved-key feature are not yet available.

• Use the existing account system and a private upload route with PDF size/type limits.
• Process evaluations as background jobs with progress, timeouts and per-user rate limits.
• Offer an explicit Save key for future use choice. Encrypt the key on the backend with a managed encryption key before storing ciphertext in the database.
• Bind saved keys to the authenticated user. Return only a masked status; provide replace and delete actions. Never put a Gemini key in page code, analytics or logs.
• Keep each job's files and cache separate. Record the model and rubric version with the report.
• Explain Google processing before upload, define retention, and allow users to delete stored reports and files.
• Use the report for personal feedback and human review. Do not add automatic hiring rejection based on a model score.

The upstream CLI needs adaptation for concurrent website users: its local cache and CSV conventions are not a multi-user storage design. Production validation must cover cross-account access, invalid keys, quotas, malformed PDFs and deletion before launch.

Sources and verification

Primary source: [Hiring Agent repository](https://github.com/interviewstreet/hiring-agent). Installation and CLI details: [README](https://github.com/interviewstreet/hiring-agent/blob/main/README.md), [score.py](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), [configuration](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), [provider mapping](https://github.com/interviewstreet/hiring-agent/blob/main/providers.json), [environment template](https://github.com/interviewstreet/hiring-agent/blob/main/.env.example), [role rubric](https://github.com/interviewstreet/hiring-agent/blob/main/roles/software_engineering_intern/role.json), and [MIT license](https://github.com/interviewstreet/hiring-agent/blob/main/LICENSE).

Verification scope: source review and guide publication checks. A clean-machine installation and a live Gemini resume evaluation are not certified by this article.