Repository avatar
Other Tools
v0.3.1
active

repo-interview

io.github.Blhasn-Sehli/repo-interview

Interview questions about your own repo or PR, each verified to cite real code.

Documentation

repo-interview

Website and demo · npm

Can you explain your own code? repo-interview reads your repository or pull request and asks you the questions an interviewer or reviewer would: what it does, why it is built this way, and how specific code works. Then it grades your answers and tells you what to study.

Every question cites a real file and symbol. A verifier checks each citation and drops any question about code that does not exist, so the model cannot quiz you on something it made up. It runs on a free local model, so your code stays on your machine.

Who it is for

  • Students and job seekers preparing to explain a portfolio project, especially one built with AI help.
  • Developers who want to check they really understand a codebase before they own it.
  • Teams who want authors to explain their own pull requests (advisory, never blocking).

Quick start (terminal)

ollama pull qwen2.5-coder:3b
npx repo-interview interview . --provider ollama --model qwen2.5-coder:3b

You get 8 questions (3 big-picture, 3 about specific code, 2 asking you to predict what a function does). Answer each on one line; a weak answer gets one follow-up. At the end interview-report.md shows your score and links to the files to study.

Needs Node.js 22+ and Ollama. Package: repo-interview on npm.

Three kinds of questions

  • Big picture: what the project does, its main parts, and why it is built this way.
  • Code: how and why a specific function works: control flow, error handling, trade-offs.
  • Predict: what a specific function returns, throws or does for a given input. These come from your own tests first: t.is(getBodySize('hello'), 5) becomes "getBodySize is called with 'hello'. What will the output be?", and the answer is the test's assertion, not a model's guess. When too few tests fit, the rest become code questions. With --predict-from tests+model the model also writes predictions from the code, quoting the lines its answer relies on; use that only with a large model, because a small local model got most of them wrong in testing.

Choose with --kinds overview,code,predict (default all three).

Inside Claude (MCP): no Ollama needed

Let Claude (or any MCP client) run the interview with its own model, while repo-interview keeps it honest:

claude mcp add repo-interview -- npx -y repo-interview mcp

Then, in your project, ask Claude to "interview me about this repo", or use the interview prompt (pr_interview for the current branch). Claude reads the code and writes and grades the questions; repo-interview's tools list what exists (scan_repo), show the cited code (read_code), list a branch's changes (pr_changes), offer predict questions taken from your tests (test_cases) and drop any question about code that does not exist (check_questions). The tools only read files, never run them, and refuse paths outside the project.

On pull requests (GitHub Action)

Posts one comment with 3 questions about the PR's own change: what it adds, how the changed code works, and what it will do for a given input. It runs a small model with Ollama on the GitHub runner: free, no API key, and the code stays on the runner. It is advisory and never fails the PR.

name: PR questions
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  questions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 2
      - uses: Blhasn-Sehli/repo-interview@main

On this repo's first run the whole step, including installing Ollama and downloading the model, took 86 seconds, of which the model took 45. Pull requests from forks get a read-only token, so their questions go to the job summary instead of a comment.

To score the author's answers, add a second workflow. When the PR's author replies with numbered answers (1., 2., 3.), it grades each one 0-3 against the cited code and posts one scores comment, edited again if they reply again. The PR's code is fetched into a separate folder and only read, never run.

name: PR answers
on:
  issue_comment:
    types: [created]
permissions:
  contents: read
  pull-requests: write
jobs:
  score:
    if: github.event.issue.pull_request && github.event.comment.user.login == github.event.issue.user.login
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Blhasn-Sehli/repo-interview@main

Commands

CommandWhat it does
interview <path>Questions in your terminal, each answer graded 0-3, one follow-up after a weak answer, then a report
questions <path>Just the questions; --kinds, --overview <n> and --predict <n> set the mix
pr <path> --base main3 questions about only the code changed since main (1 about what it adds, 1 about code, 1 predict)
scan <path>The files and symbols questions can cite
mcpRun as an MCP server for Claude and other MCP clients

Providers: --provider ollama (local, free), anthropic (ANTHROPIC_API_KEY) or openai (any OpenAI-compatible server, OPENAI_API_KEY). --record <dir> and --replay <dir> save and replay model replies, so runs can be checked offline.

How well it works (measured)

On 10 public repositories in 10 languages, with the small local model qwen2.5-coder:3b, big-picture and code questions only, an average of 3 runs has 90.7% of generated questions citing real code under the strict check (runs ranged 86.3-95.8%) and 92.8% under the fair check. The verifier removes the rest before you see them. Every number comes with its recorded model replies, so you can recheck it offline: see the test corpus.

Not measured yet: how well grading agrees with a human, how useful testers find the questions, and how often a model-written prediction's expected answer is right (predictions taken from tests use the test's own answer). All are in progress.

How it is different

Other tools also ask authors about their code or pull requests, for example comprehension-gate, PR Guard, CCG, Gater, churn interview and PathFinder. repo-interview's focus:

  • Checked citations. A question reaches you only if the file and symbol it cites exist (and, for a PR, were changed by it), and the rate is measured and published.
  • Local and free by default. Ollama on your machine or on the GitHub runner; no account, no API key, no code sent anywhere.
  • For learning, not only gating. The terminal interview ends with a report of what to study, which suits students and job interview practice.

Status

Early: expect rough edges. Symbols come from tree-sitter for TypeScript, JavaScript and Python and from patterns for Go, Rust, Java, Kotlin, C#, C/C++, Ruby and PHP. Answers in the terminal are one line each. See SECURITY.md for how it handles untrusted code, and CONTRIBUTING.md to help.

Thanks

Prediction questions, including generating them from your existing tests, were suggested by Jason Gorman (Codemanship).

License

MIT

NPM
repo-interview
Install Command
npm install repo-interview