Quick Start

Source access and prerequisites

Use the public repository at the reviewed commit below. This revision removes tracked per-user output, reconciles the CLI instructions, and adds a retention note. Use a new checkout for the synthetic walkthrough.

git clone https://github.com/Golenspade/devhunt.git
cd devhunt
git checkout --detach 0d97c50756cb74ebf868946e181d48835e09e3bf

You'll need Bun and GitHub CLI (gh). The local report and prompt workflow below was verified with Bun 1.3.14 on 2026-09-06. It doesn't require a GitHub token or model API key. GitHub CLI and authentication are needed when you later run scan.

Install in the checkout root

bun --version
gh --version
bun install --frozen-lockfile
bun ./bin/devhunt.ts

That last command intentionally omits a subcommand—it prints usage and exits 1. That's the current CLI's usage behavior, not an installation failure. The actual entry point is bin/devhunt.ts; the root dev.sh and build.sh mentioned in older instructions are absent. Keep the lockfile and run from the checkout root so relative query and output paths resolve correctly.

First result using synthetic data

Create a new file named fixture.ts in the checkout root with the following contents. It creates one fictional repository and one fictional Pull Request under out/docs-demo/raw/; it's not a scan of an actual person. Use a fresh checkout so an existing out/docs-demo/ directory isn't overwritten.

import { mkdir, writeFile } from 'node:fs/promises';
const raw = 'out/docs-demo/raw';
await mkdir(raw, { recursive: true });
const repo = {
  name: 'example-project', owner: { login: 'docs-demo' },
  isFork: false, isArchived: false,
  primaryLanguage: { name: 'TypeScript' },
  stargazerCount: 10, forkCount: 0,
  createdAt: '2024-01-01T00:00:00Z', pushedAt: '2024-01-03T00:00:00Z',
  languages: { edges: [{ size: 1000, node: { name: 'TypeScript' } }] },
};
const pr = {
  createdAt: '2024-01-02T08:00:00Z', mergedAt: '2024-01-03T08:00:00Z',
  closedAt: '2024-01-03T08:00:00Z', isCrossRepository: true,
  additions: 10, deletions: 2, changedFiles: 1,
  repository: { name: 'example-upstream', owner: { login: 'example-owner' } },
  url: '', // Synthetic record: no public evidence URL.
};
await writeFile(`${raw}/repos.jsonl`, JSON.stringify(repo) + '\n');
await writeFile(`${raw}/prs.jsonl`, JSON.stringify(pr) + '\n');
await writeFile(`${raw}/commits.jsonl`, '');
console.log('Synthetic fixture ready: out/docs-demo/raw');

Run the fixture, report, and prompt commands in a POSIX shell:

bun fixture.ts
bun ./bin/devhunt.ts report docs-demo --tz +00:00
OPENAI_API_KEY= bun ./bin/devhunt.ts narrate docs-demo --lang en --style brief

The explicit empty OPENAI_API_KEY keeps this invocation on the local prompt path, including when a .env file contains a key. An empty value is deliberate. After success, inspect:

• out/docs-demo/profile.json — Parseable profile built from the synthetic inputs.
• out/docs-demo/top_repos.json — One representative repository entry.
• out/docs-demo/charts/languages.svg — Language distribution chart.
• out/docs-demo/charts/hours.svg — PR-hour chart.
• out/docs-demo/narrate_prompt.txt — System and user prompts; no provider-generated narrative.

Missing user metadata and commits are intentional in this fixture. Null or sparse metrics don't say anything about a person's skill or habits. The test proves local analysis, SVG output, and prompt generation; it doesn't verify GitHub scanning or a live model response.

Continue with an authorized scan

Choose a login and review the scope visible to your GitHub credentials first. Configure authentication through your environment or GitHub CLI rather than pasting a token into the command. GITHUB_TOKEN and GH_TOKEN can affect which credentials are used. Keep the interactive confirmation enabled on the first run.

bun ./bin/devhunt.ts scan LOGIN --window quarter
bun ./bin/devhunt.ts report LOGIN --tz Asia/Shanghai
OPENAI_API_KEY= bun ./bin/devhunt.ts narrate LOGIN --lang zh --style professional

Replace LOGIN consistently. quarter limits the commit window; it doesn't make every query public-only or give every metric the same time window. Review raw and derived files before copying prompts elsewhere. See CLI reference, AI narrative, and Data handling.

Scanning follows token-visible permissions and has no public-only visibility filter. Use a least-privilege token and treat outputs as sensitive local data.