# recruiter-lens

[![CI](https://github.com/dani-aisystems/recruiter-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/dani-aisystems/recruiter-lens/actions/workflows/ci.yml)

Audits GitHub repos and profiles for hiring signal — as an MCP server (`audit_repo`, `recruiter_scan` tools) usable from Claude Code, Claude Desktop, or any MCP client, and as a standalone CLI.

Packages the [`repository-auditor`](https://github.com/dani-aisystems/hiring-signal-skills) and [`technical-recruiter-review`](https://github.com/dani-aisystems/hiring-signal-skills) skill methodology as a tool any AI assistant can call directly, instead of a prompt you paste in.

## Design choice worth knowing about

**This tool does not call an LLM itself.** It gathers deterministic, checkable facts from the GitHub API (README presence, CI, license, topics, commit-message patterns, activity recency, bio/pin presence) and applies rule-based severity/verdict logic. The qualitative judgment — actually reading the code, weighing architecture — is left to whatever AI assistant is calling this tool.

This is a deliberate simplicity choice, not a missing feature: the task here is fact-gathering, and a second nested LLM call would add cost and non-determinism without adding real capability the calling assistant doesn't already have. It also means the entire tool is testable without an API key — see `test/`.

## MCP usage

```bash
claude mcp add recruiter-lens -e GITHUB_TOKEN=<your token> -- npx recruiter-lens-mcp
```

Then ask your assistant something like *"use recruiter_scan to check github.com/someuser"* or *"audit_repo on octocat/Hello-World"*.

## CLI usage

```bash
GITHUB_TOKEN=<token> npx recruiter-lens audit-repo <owner>/<repo>
GITHUB_TOKEN=<token> npx recruiter-lens scan <username>
```

`GITHUB_TOKEN` needs at least public read access; a classic PAT with `repo` scope covers private repos too.

## Testing

`npm test` runs the scoring-logic tests (`test/*.test.mjs`) — pure functions, no network, no API key required, runs in CI on every push.

## License

MIT — see [LICENSE](./LICENSE).