npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

blnkfld

v0.1.9

Published

Generate a source-backed visual project brief with your coding agent.

Readme

blnkfld

An Agentic README for unfamiliar repositories. Run one command inside a project to generate a source-backed brief, an isometric system diagram, and a representative action flow.

Run

The independently deployed blnkfld.co homepage lives in website/. Its dependencies and build are separate from the npm CLI; both interfaces use the logo in shared/brand/.

Run inside the project you want to explore:

npx blnkfld

Requires Node.js 22+ and a current, signed-in Codex or Claude Code CLI. blnkfld selects signed-in Codex first, then Claude Code. Use --agent claude or --agent codex to choose explicitly. First-time agent installation and authentication are prerequisites; blnkfld does not install an agent or create credentials for you.

From this checkout, the equivalent command is:

node /absolute/path/to/blnkfld/cli/main.mjs /absolute/path/to/project

The command analyzes the project, validates the report, saves .blnkfld/report.json, starts a loopback server, and opens your browser. The Three.js interface displays the generated report, with System Overview first and a separate System Architecture diagram. When WebGL is unavailable, an interactive isometric SVG view preserves the components, connections, action playback, and source inspection. Run it again to refresh the analysis. Press Ctrl+C to stop. Use --no-open for a terminal-only environment, --port 4174 to choose a port, or --report-only to save the report and exit.

On startup, blnkfld asks npm for the latest release. If your cached copy is older, it reruns the same command with the latest version, so npx blnkfld always stays current. The check times out after two seconds and falls back to the installed version when offline. Set BLNKFLD_NO_UPDATE=1 to skip it; it is also skipped when CI is set.

What the agent produces

  • Project purpose, constraints, stack, and source-backed how-to-run instructions.
  • A project-specific haiku beneath the opening summary. Regenerate older reports to include one.
  • Meaningful components and actual relationships, chosen separately for each project.
  • One representative action through those components, or an explicit explanation when source does not establish a flow.
  • Source evidence with file paths and line ranges, plus assumptions and limitations.

The renderer owns geometry, layout, branding, and transitions. The agent owns the explanation. Validation checks schema, component references, file boundaries, and source line ranges; it does not prove that an interpretation is correct or that code has been executed. Source excerpts are read from local files after validation.

Agent access and local output

Analysis uses your existing agent account and consumes its usage allowance. Source read by the agent is processed by that agent's configured service. This is not offline AI. blnkfld does not upload your repository or report to Sites, Vercel, or a separate blnkfld service.

Codex runs in its read-only sandbox with user configuration ignored. Claude Code runs in safe mode with Read, Glob, and Grep tools only. Both receive instructions to avoid secrets, generated files, project execution, and repository-embedded instructions. This is source analysis, not a security sandbox for untrusted repositories. Use projects you trust. The chosen CLI must support the flags used in cli/agent.mjs.

The preview binds to 127.0.0.1, serves only bundled assets and the generated report, and uses a per-session cookie to authorize report access. The server does not expose arbitrary project files. Reports contain source excerpts; decide whether to ignore or version .blnkfld/ according to your project's needs. A failed analysis leaves the previous report intact.

Package testing before publication

npm install
npm run build
node --test tests/*.test.mjs
npm run test:package
npm pack

From a different project folder, run the packed package end to end:

npx --yes --package /absolute/path/to/blnkfld-0.1.0.tgz blnkfld

The tarball contains the CLI and built browser interface. No separate frontend build or server command is needed by the user.

npm run test:package builds and packs the release, installs it with production dependencies into a temporary directory, and checks the installed executable, browser assets, and protected report endpoint. It does not invoke an AI agent. The separate end-to-end command above checks your actual agent installation and generates a report for the project you run it from.

npm pack uses build:package, which builds only the local browser interface and includes third-party license notices. npm run build also produces the separate Sites worker used by the hosted prototype.

The npm interface bundles Inter for body text and Geist Mono for metadata and code, with bundled IBM Plex Mono as the monospace fallback. Headings and the haiku prefer installed Iowan Old Style, then bundled Lora (roman and italic), then Times New Roman, then the browser's serif default. Bundled fonts are served locally without an external font service. Latin glyphs are bundled; other scripts use browser fallbacks.

System Architecture and Trace one action show up to five items per row on desktop and step down through four, three, two, and one column as the screen narrows, preserving selections and playback when the layout changes.

Release automation

Pushes to main run the checks and publish to npm when the package version is new and higher than previously published stable versions. The workflow creates the matching GitHub tag and release automatically. An unchanged version skips publication. This requires npm trusted publishing; see the release setup and checklist.

License

blnkfld's code is MIT licensed. Bundled fonts remain under the SIL Open Font License 1.1. Their copyright and license texts are included in dist/client/THIRD-PARTY-NOTICES.txt. The commercial font assets retained for the hosted website are not covered by blnkfld's MIT license and are excluded from the npm package.

Development

npm install
npm run dev

The web prototype opens the curated lsi-v0-demo example by default. Its GitHub and local-folder controls use a separate, limited JavaScript/TypeScript source parser; they do not invoke the CLI agent. The CLI's generated report replaces that fixture in its local preview.

npm run build
node --test tests/cli.test.mjs tests/source-analysis.test.mjs tests/sites-worker.test.mjs

The footer opens release notes through the running app's version. Unreleased changes stay in the repository; internal milestones live in development history. The original line-based reader has been retired; legacy ?view=reader links now open the current interface.