Starlog

Vet a package before your AI coding agent uses it — authoritative facts (CVEs, license, maintenance), free, local, no account.

Vet a package in one command — nothing to install, no API key, no account:

npx starloghq facts ua-parser-js

Then wire it into your coding agent (Claude Code, Cursor, Copilot, Codex):

npx starloghq init

Source-available under BUSL-1.1 — free to use, modify, and self-host; converts to Apache-2.0 in 2030. Details ↓

Why

AI coding agents (Claude Code, Cursor, Copilot) pick libraries from training recall — a snapshot of scraped code, frozen at a cutoff date and ranked by how often an option appeared, not by what fits your task or what's safe now. That recall can't know about a CVE disclosed last week, and it has never seen your company's internal libraries. The agent recommends anyway, with the same confidence either way.

The failure modes are measurable: research finds ~49% of AI-suggested dependencies carry known vulnerabilities and ~34% are hallucinated outright — the package doesn't exist. And for whole categories — most dangerously auth — agents default to hand-rolling custom code instead of reaching for a vetted library.

You can't fix recall by prompting harder. Starlog puts authoritative, dated facts in front of your agent at decision time. Its hero surface is vetting by name — starlog facts <package> returns known CVEs/incidents, SPDX license + risk, and maintenance status (or an honest "no facts on file") — so the install/avoid/pick call rides on facts, not recall. It runs entirely on your machine as an MCP server and a package-install hook, no API key, no sign-up. A companion starlog_search finds candidate packages for a capability; facts vet the pick.

Does it actually change what the agent decides? Yes — measured before/after, on the venue that matters (private libraries and post-cutoff advisories). → the validated result.

What you get

• starlog_facts MCP tool — your agent looks up authoritative facts about a specific package before recommending it: known CVEs/supply-chain incidents, SPDX license and license risk, maintenance status (active/deprecated/abandoned/compromised), and effect surface. In a 4-model benchmark, agents called this tool unprompted on package decisions (100% recall, 98% specificity) and it moved them toward the correct install/avoid/pick call. Every record is sourced, verified, and dated — each result shows an "as of <date>" line so a stale "no known vulns" is never mistaken for a fresh one. A package with no record returns an honest "no facts on file." Facts are three independent layers, composed at query time: L1 capability/effect-surface (immutable), L2 reputation/vuln/license/maintenance (mutable — carries the as of recency), L3 org policy (your suitability verdict). Override or extend any layer locally: point STARLOG_PRIVATE_FACTS at a JSON file with independent l1/l2 arrays (internal packages, license rulings) and STARLOG_POLICY at an org policy ({ org, rules }) for allow/deny/flag verdicts. With STARLOG_API_KEY set, org-private overlays and policy come from the hosted facts API (local corpus is the offline fallback); starlog facts push uploads your org's overlays + policy. See docs/FACTS-CONTRACT.md.
• Package-install hook — fires the moment your agent runs npm install / pnpm add / yarn add / pip install and surfaces that package's facts (known incidents, license, maintenance) before the agent builds on it. Advisory — it informs the next move, it doesn't block the install. Packages with no record are queued for coverage.
• starlog_search MCP tool — discovery: find candidate packages for a capability (org-sanctioned options first), then vet the named pick with starlog_facts. Discovery surfaces what exists; facts vet it.
• starlog_advise MCP tool — when your agent sees DIY or repeated capability code, advises MIGRATE to a safe library (e.g. Clerk/Auth0/Supabase over DIY auth) or PACKAGEIZE only when no safe corpus alternative exists. Tracks patterns in .starlog/patterns.json.
• starlog facts / starlog search / starlog advise / starlog patterns CLI — the same facts, discovery, and migrate-or-packageize advisories from your terminal.
• Runs on your machine — the engine and corpus are local; the default (keyless) path needs no account, no API key, and no network. Setting STARLOG_API_KEY opts into the hosted facts/search tiers (with local fallback) — get a key at starlog.dev and wire it with starlog init --api-key <key>; anonymous, opt-out usage telemetry is the only thing sent otherwise — see Telemetry.

This repo ships the engine plus a curated facts corpus and a discovery corpus of 26 capability manifests across 7 categories (including authentication playbooks for migration).

Quick start

npx starloghq init

This wires Starlog into Claude Code (and drops instruction files for Cursor, Copilot, Codex):

• MCP server added to ~/.claude/settings.json — exposes starlog_facts (vet a package by name), starlog_search (discover candidates), and starlog_advise (migrate-or-packageize for DIY patterns), and wires your per-project private overlays (${CLAUDE_PROJECT_DIR}/.starlog/*) into the agent so internal-package facts + discovery work automatically in each project
• PostToolUse hook installed — surfaces a package's facts on install
• Previews every change and asks before writing; idempotent and safe to re-run

Prefer a bare starlog command over typing npx? Install it globally:

npm install -g starloghq
starlog init

If starlog then reports command not found, your npm global bin directory isn't on your PATH (a common npm setup gap — not a Starlog issue). Either run export PATH="$(npm prefix -g)/bin:$PATH" (add it to your shell profile to persist), or just keep using npx starloghq init / npx starloghq facts <pkg>, which always work without any PATH setup. If the install itself printed an EACCES/permission error, it didn't complete — fix your npm prefix or use npx.

Add --project to also drop Starlog guidance into your project's CLAUDE.md; preview without writing, or remove cleanly:

starlog init --project
starlog init --dry-run
starlog init --uninstall

Onboard a whole org at once

Don't hand-author facts for every internal repo — point Starlog at a directory of checkouts and it derives them in one pass:

starlog org sync ~/code/my-org

For each published package it finds (npm package.json and Python pyproject.toml), it derives:

• L2 facts → .starlog/private-facts.json — license + license risk (from the manifest, or detected from the LICENSE file), maintenance from git last-commit recency, stamped source: analyzer with a dated as of. Your agent vets these by name.
• Discovery corpus → .starlog/private-corpus.json — captures each manifest's description + keywords so your agent can find internal packages by capability via starlog_search, not just vet them by name.
• Suggested policy → .starlog/policy.suggested.json — flag candidates (e.g. strong-copyleft, no declared license) derived from the signals. These are proposals the agent does not read — review them, then adopt the ones you trust with starlog facts policy <pkg> flag.

Source never leaves your machine; only derived facts are written. Re-run anytime to refresh (it merges over existing facts and regenerates suggestions). Repos with no published name — or no description — are reported, never fabricated. Known-vulnerability scanning and remote GitHub-org enumeration are on the roadmap.

From source

git clone https://github.com/starloghq/index.git starlog-index
cd starlog-index && npm install
npx tsx src/cli.ts facts ua-parser-js

Manual MCP setup

starlog init writes this for you automatically. To configure by hand, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "starlog": {
      "command": "npx",
      "args": ["-y", "starloghq", "mcp"]
    }
  }
}

This is the same launch command MCP registries use. (From a local source clone instead, point node at dist/mcp.js — $(npm root -g)/starloghq/dist/mcp.js for a global install, or your clone's path.) The server exposes two tools: starlog_facts (an authoritative per-package fact lookup — CVEs, license, maintenance) and starlog_search (a natural-language capability query with optional category, stack, and top_k filters).

CLI usage

Vet a package by name — the hero. Local, no key, no network:

starlog facts ua-parser-js