Mine a repo's PR-review history and current code into a portable AGENTS.md conventions file
Mines a repository's pull-request discussion history, reconciles it against the current codebase, and emits a portable AGENTS.md-style conventions file with a provenance sidecar. Runs either as an MCP server or as a standalone terminal command.
prlore has two entry points from the same installed binary: prlore with no
arguments runs the MCP server; prlore mine <owner/repo> runs the full
pipeline directly in a terminal, with an interactive preview-and-confirm step
before anything is written.
Either way, prlore always operates against a local checkout of the target
repo — it runs git grep/git log against repoPath to corroborate what the
PR discussion says against what the code actually does. Point repoPath (or,
for the CLI, --repo-path) at a clone, not a bare owner/name reference.
npx prlore mine octo/repo --intent "onboard an AI coding agent"
This runs the mining pipeline in-process: it starts the job, polls progress to
stderr every 5 seconds, then once the draft is ready prints it to stdout along
with any contested rules (listed on stderr — v1's CLI never auto-resolves
them; use the MCP write tool's resolveContested, or edit the file by hand,
to keep one). It then asks before touching disk: Write AGENTS.md? [y/N] when
it will write the target directly, or Write .prlore/AGENTS.md and add a pointer block to AGENTS.md? [y/N] when an existing hand-authored AGENTS.md means it
adopts pointer mode instead (see "Adaptive pointer mode" below).
usage: prlore mine <owner/repo> [options]
--intent <text> what the resulting doc should help with
--since <ISO-datetime> only PRs updated at/after this timestamp
--days <n> only PRs updated in the last <n> days
(--since and --days are mutually exclusive)
--author <login> only mine PRs authored by this login
(case-insensitive; repeat --author for multiple
logins). When set and --intent is not given, the
default intent switches to documenting the
review feedback these authors received.
--budget <usd> max USD to spend on model calls (default: 10)
--model <id> model id override
--provider <anthropic|claude-cli|github-models|ollama|openai|auto>
which model backend to use (default: auto)
--base-url <url> base URL for --provider openai (or
OPENAI_BASE_URL); ignored by other providers
--repo-path <path> local checkout to mine against (default: cwd)
--target <file> output file (default: AGENTS.md)
--max-rules <n> cap on rules rendered in full detail; the rest
render as compact one-liners in a trailing
section (default: 60; must be a positive
integer — pass a large number for "no cap")
--yes skip the write confirmation prompt
--dry-run preview only; never writes, even with --yes
Exit codes: 0 on success (including a confirmed-no / --dry-run "not
written" outcome), 1 if the mining job itself failed or the write was
refused (a target file whose managed block is damaged: a corrupt/reversed
marker pair, or a lone stray marker. An existing file with no prlore markers is
not a refusal; it adopts pointer mode, see "Adaptive pointer mode" below), 2
for a usage or configuration error (bad flags, invalid MineConfig, no model
provider available).
The CLI draws model calls from whichever provider --provider/model.model
resolves to (see "Budget and model notes" below) — with --provider claude-cli or the auto fallback, that's your local Claude Code CLI running
headless against your subscription, so prlore mine works with zero API
credentials on a machine that already has claude authenticated.
If you're an outside contributor rather than a maintainer, --author narrows
mining down to PRs you authored, so the resulting doc becomes a record of the
review feedback you've gotten and the standing lessons from it, rather than a
general conventions guide. Authority weighting already does the rest here —
maintainer comments on your own PRs already drive rule scoring, so no scoring
changes are needed for this to work; --author is purely a client-side filter
over which PRs get mined at all (GitHub's GraphQL API has no server-side
author filter on the pullRequests connection, so every PR is still fetched
and paid for at the same rate cost — only the kept, and therefore
model-processed, set gets smaller).
prlore mine owner/repo --author yourlogin --days 730
--author is repeatable (--author alice --author bob) and matches
case-insensitively. When --author is given and --intent isn't, the
default intent switches from the general onboarding phrasing to documenting
the review feedback these authors received.
prlore never rewrites hand-authored prose. How it writes the mined conventions depends on the target file's existing state, chosen automatically from what's on disk (there is no flag):
AGENTS.md, inside a
<!-- prlore:begin --> / <!-- prlore:end --> block. Bytes outside that block
are preserved exactly. This is the original behavior and is unchanged.AGENTS.md that prlore doesn't manage, i.e. one
with no prlore markers). The full mined doc lands in a separate, prlore-owned
file, .prlore/AGENTS.md, and your existing AGENTS.md is only ever appended
to with a small managed pointer block (markers plus a one-line "the mined
conventions live in .prlore/AGENTS.md, read that first" note). The prose you
wrote above that block stays byte-for-byte identical, and re-running mine
replaces just the pointer block in place. prlore also enters pointer mode
whenever .prlore/AGENTS.md already exists, so once a repo adopts it the
layout stays put.With a non-default --target, the same rule applies with that filename
substituted throughout (.prlore/<target>, and the pointer references
.prlore/<target>).
Pointer mode is exactly the case that used to refuse. An existing unmarked
AGENTS.md is now adopted, not rejected (see the exit-code note above for what
still refuses).
Point an MCP host (Claude Code, Claude Desktop, or any other MCP client) at it:
{
"mcpServers": {
"prlore": {
"command": "npx",
"args": ["-y", "prlore"],
"env": {
"GITHUB_TOKEN": "ghp_...",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}
GITHUB_TOKEN — a GitHub token with read access to the target repo. If
unset, prlore falls back to gh auth token (requires the gh CLI to be
authenticated).ANTHROPIC_API_KEY — used by the Anthropic model provider (the
@anthropic-ai/sdk client reads this directly; no prlore-specific wiring
needed). This remains the documented default for CI and servers, where
there's no interactive Claude Code session to draw on.| Tool | Purpose |
|---|---|
mine | Starts (or resumes) a mining job. Only required inputs are repo (owner/name) and intent (free text describing what the doc is for) — everything else defaults. Rejects while a job is already running. |
status | Reports job state, stage, progress counters, and spend so far. Poll it after mine. |
cancel | Requests a graceful stop; the job checkpoints at the next stage boundary so a later mine call resumes instead of restarting. |
preview | Once a job reaches ready-for-preview, returns the rendered markdown, any contested rules, summary stats, and a one-time confirmToken. |
write | Writes the previewed draft to disk. Requires the confirmToken from the immediately preceding preview call — prlore never writes without one. Accepts resolveContested to keep or drop specific contested rules. |
The interview MCP prompt is a conversational script for gathering mine
inputs (repo, intent, focus areas, output preferences) instead of asking the
user to fill in a MineConfig by hand. It's optional — mine({ repo, intent })
works cold.
mine's model config controls spend:
model.model — which Anthropic model to use (defaults to prlore's built-in
default; see src/model/anthropic.ts for the current price table).model.maxBudgetUsd — a hard USD cap across the whole run (default 10).
Once tripped during extraction, the run degrades to a partial-corpus draft
with a warning; once tripped during synthesis (the highest-value calls), the
job fails outright rather than emitting a truncated conventions doc.model.provider selects which model backend runs the mining calls:
"auto" (the default): uses the Anthropic API if ANTHROPIC_API_KEY is
set; otherwise falls back to the local claude CLI if it's on PATH;
otherwise falls back to GitHub Models if GITHUB_TOKEN/GH_TOKEN is set
(present automatically in GitHub Actions, Codespaces, and Copilot); errors
naming all remedies if none is available. "ollama" is never chosen by
auto, since it depends on a local server being up; pass --provider ollama explicitly."anthropic": always uses the Anthropic API. Requires
ANTHROPIC_API_KEY; fails immediately with a clear error if it's unset
(rather than failing deep inside the pipeline on the first call)."claude-cli": always uses your locally installed, already-authenticated
Claude Code CLI in headless mode. No API key needed, but usage draws on
your Claude subscription's usage limits, not billed API credits. Its
default model is whatever the claude CLI itself defaults to (prlore
doesn't override it unless model.model is set); the Anthropic provider's
default is claude-sonnet-5 (see src/model/anthropic.ts for the current
price table)."github-models": uses GitHub Models (https://models.github.ai/inference),
an OpenAI-compatible endpoint. Requires GITHUB_TOKEN or GH_TOKEN;
default model is openai/gpt-4o-mini. Free tier, but rate-limited (roughly
50-150 model calls per day, depending on model), so it realistically only
covers a small mine; see "Running inside GitHub Copilot / Codespaces" below."ollama": uses a local Ollama server at http://localhost:11434/v1 (or
OLLAMA_BASE_URL), no API key needed. Default model is qwen2.5:7b. No
rate limits, so this is the option for a full mine with no billed API."openai": generic OpenAI-compatible endpoint for any other provider.
Requires --base-url (or OPENAI_BASE_URL), OPENAI_API_KEY, and
--model/model.model."sampling" also exists in the config schema (MCP sampling as a fallback
when no API key is configured), but that path isn't wired yet. mine
rejects provider: "sampling" with a tool error rather than silently
running another provider in its place.For "github-models", "ollama", and "openai", cost tracking is disabled
(these endpoints are free-tier or arbitrarily priced), so --budget/
model.maxBudgetUsd does not gate them.
prlore auto-detects the environment's GITHUB_TOKEN and uses GitHub Models, so
npx prlore mine <owner/repo> works with no extra setup. Note the free-tier
rate limits (roughly 50-150 model calls per day, depending on model), which
realistically only cover a small mine; scope it down with --days or a small
window. For a full mine, run a local model with --provider ollama (no rate
limits) or set ANTHROPIC_API_KEY.
npm install
npm test # vitest
npm run typecheck # tsc --noEmit
npm run build # tsc
No live network or LLM calls happen in the test suite — GitHub's GraphQL API
and the model provider are faked throughout, including in the end-to-end test
(test/e2e.test.ts), which runs the real mining pipeline against a
script-built fixture git repo.
git commands against repoPath; it does
not fetch or shallow-clone the repo itself.<!-- prlore:begin --> / <!-- prlore:end --> block (or a fresh file if the
target doesn't exist). It never merges into hand-written prose: an existing
unmarked AGENTS.md is adopted via pointer mode (the mined doc goes to
.prlore/AGENTS.md and only a small pointer block is appended to the human
file, see "Adaptive pointer mode"), and a target whose managed block is
damaged (a corrupt/reversed pair or a lone stray marker) is refused rather
than guessed at.write accepts. Re-running mine
re-synthesizes over the (cached) extraction corpus.contested, not in the emitted draft — it only appears in the written file
if the caller explicitly resolves it with resolveContested: [{ id, action: "keep" }] on write.provenance.dropped with
droppedReason: "recurrence-floor" even if it would otherwise clear the
score threshold — this filters out single-PR trivia (a one-off nit that
happened to get said with confidence) without needing a config knob.
Synthetic code-only rules (derived purely from codebase patterns, with no
PR evidence) are exempt. Nothing is silently discarded: floored rules stay
in the provenance sidecar with their reason, just not in the rendered doc.layout: "auto" switches from a single file to per-area files once the
draft exceeds 400 lines OR 24,000 bytes (~6k tokens), whichever trips
first — a handful of very long rule lines can blow past a reasonable doc
size while staying under the line-count check alone.output.maxRules (default 60, by score — rules already arrive score-sorted)
render in full inside their planned sections. Anything beyond the cap still
ships, just compressed: one line each (- statement _(citations)_, no
rationale) in a single trailing ## Additional conventions (lower signal)
section, before the contested section. Nothing is dropped from the doc by
this — provenance.rules still carries full records for every rule,
tagged with renderedTier: "full" | "compact". Set --max-rules (CLI) or
output.maxRules (MCP config) to change the cutoff; it must be a positive
integer, so "no cap" means passing a large number, not 0.FAQs
Mine a repo's PR-review history and current code into a portable AGENTS.md conventions file
We found that prlore demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Ten malicious OpenAPI React Query Codegen versions were published to npm in the Mini Shai-Hulud attack, all with valid provenance.
Security News
Socket joins more than 100 technology, cybersecurity, and financial organizations calling for a global surge in cyber defense.
Product
Enterprise security teams can now detect malware, credential theft, suspicious network activity, and risky updates across Microsoft Edge extensions.