Starlog

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 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 " 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 ; 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 , 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

Want your coding agent to do the setup? starlog init --agent-prompt prints a ready-to-paste prompt (preview → optional key → apply → doctor → restart → demo) that walks Claude Code, Cursor, Copilot, or Codex through it non-interactively. It writes nothing.

Want a live dependency scanner next to Starlog's dated facts? starlog init --with-socket also wires Socket's free hosted MCP server (depscore), so your agent can catch anything disclosed after a fact's "as of" date. It's opt-in because your agent then sends the package names it checks to socket.dev. An existing socket entry you configured yourself is never overwritten, and --uninstall removes only the entry Starlog wrote.

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 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

## ua-parser-js (npm)

Effect surface: Parses User-Agent strings; pure data transformation, in-process. Capabilities: parsing Maintenance: active License: MIT (risk: none) Known vulnerabilities / incidents:

• INCIDENT:ua-parser-js-2021 [critical] affected: 0.7.29, 0.8.0, 1.0.0 — Maintainer account hijacked (Oct 2021); these versions shipped a password stealer and cryptominer. Treat installs as account-compromise.

Transitive risk: Frequently a transitive dep — pin away from the three bad versions. Source: GitHub Security Advisory; CISA alert Oct 2021 (hand) Verified: as of 2026-06-01

A package with no record returns an honest "No facts on file" — not a guess. Add --format json for machine-readable output with the independent l1 / l2 / l3 layers.

Discover candidates for a capability, then vet the named pick with facts:

starlog search "auth for a Next.js app"

#   Library             Category          Score   Solves

1 Auth0 Next.js SDK authentication 71.36 Implements user authentication in Next.js applications using Auth0 ... 2 Clerk authentication 60.64 Provides a fully managed authentication and user management platfor...

Search ranks locally with the keyword ranker — scores are absolute (a strong match lands in the 70s–80s), so a query outside the indexed cat