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

codebook-strategy

v1.1.2

Published

Your AI coding assistant re-reads your whole codebase every session. codebook-strategy builds a small set of notes it reads instead.

Readme

codebook-strategy

Your AI coding assistant re-reads your whole codebase every session. codebook-strategy builds a small set of notes it reads instead — so it gets the right context, not all the context.

⚠️ Run it, don't install it. This is a one-shot scaffolding CLI, not a dependency. Use npx (or pnpm dlx) — do not run npm install codebook-strategy.

npx codebook-strategy init

Then tell your coding assistant:

"Implement the book strategy"

It scans your codebase once and writes a compact "book" that it reads on every future session — instead of re-crawling every file.


The problem

LLM coding assistants waste tokens. Ask one to fix a bug and it often reads dozens of files just to rebuild an understanding of your project it threw away when the last session ended. That is slow, expensive, and the context it gathers is mostly noise for the task at hand.

The solution

A book: four kinds of file that live in your repo and give the assistant a map it can read cheaply, loading deep detail only for the feature it's actually touching.

book/
  PREFACE.md        always read — project-wide patterns
  INDEX.md          always read — every feature and its status
  CONNECTIONS.md    always read — how features depend on each other
  chapters/
    <feature>.md    read on demand — deep context + key files for one feature

The three top-level files are small and always loaded. Chapters are detailed but only read when relevant. The assistant goes:

preface → index → connections → the one or two chapters that matter → the actual source files those chapters point to.

The four files

  • PREFACE.md — Cross-cutting patterns that apply everywhere: tech stack, auth, error handling, logging, API and database conventions, testing. Chapters only note where they deviate from the preface.
  • INDEX.md — A table of every feature/module: name, status, last updated, one-liner. This is how the assistant decides which chapters to open.
  • CONNECTIONS.md — Topic-level relationships between features (auth/tenant → billing/invoices). This is the blast-radius map: what else might break if you change something.
  • chapters/ — One file per feature. Architecture, key files, known issues, recent changes, and a "don't bother reading" list of dead code and fixtures.

The three protocols

The strategy is enforced by instructions injected into your assistant's config file (CLAUDE.md, .cursorrules, or AGENTS.md):

  1. Reading order — Always preface → index → connections → relevant chapters → source. Never crawl the whole codebase.
  2. Mismatch protocol — If the book and the code disagree, stop and surface both to you. A stale book gets updated; wrong code might be the actual bug.
  3. Checkpoint protocol — If a feature or topic isn't in the book, the assistant asks whether to document it after resolving your request — so the book grows as you work.

How the book matures

It starts as structure and becomes knowledge. init lays down empty templates. The bootstrap pass fills them from your current codebase. From then on, every time the assistant touches an undocumented corner, the checkpoint protocol nudges it to write that corner down. Over weeks the book accumulates the hard-won context that normally lives only in senior engineers' heads.

Commands

init

npx codebook-strategy init [--tool <list>] [--force]
  • Confirms you're in a project (looks for package.json, .git, or src/).
  • Injects the strategy into every supported agent by default — CLAUDE.md (Claude Code), .cursorrules (Cursor), and AGENTS.md (Amp / Warp / Codex). That way it doesn't matter which agent — or how many — your team uses; whichever one someone opens, it finds the strategy. The agents it detects in use are marked in the output.
  • Narrow it with --tool if you only want specific agents:
    npx codebook-strategy init --tool claude
    npx codebook-strategy init --tool claude,cursor
    npx codebook-strategy init --tool all        # explicit default
  • Scaffolds book/ with PREFACE.md, INDEX.md, CONNECTIONS.md, and chapters/.
  • Existing config files are appended to, never overwritten (and never double-injected). Existing book files are left untouched unless you pass --force.

status

npx codebook-strategy status

Shows which book files exist, when each was last modified, how many chapters there are, and warns if INDEX.md lists a chapter that has no file.

validate

npx codebook-strategy validate

Checks the book for consistency:

  • every chapter file has an INDEX.md entry, and vice versa
  • CONNECTIONS.md only references chapters that exist

Prints a warning for each mismatch and exits non-zero if any are found, so it fits in CI.

audit

npx codebook-strategy audit [--ci] [--check-mtime]

Scans your code and compares it to the book. It never edits anything — it prints three lists and you decide what to change:

  1. Missing connections — code dependencies absent from CONNECTIONS.md, including reverse edges (e.g. a module that reads a table another module writes).
  2. Stale connections — CONNECTIONS.md edges with no code evidence.
  3. Stale chapters — a chapter's ## Key Files path no longer exists (hard finding), or — with --check-mtime — its source changed after the chapter did (warning).

By default it's report-only (exit 0); --ci exits non-zero on missing connections or missing chapter files. Import resolution is JS/TS only, so dependencies in other languages may be missed. The stale-chapter check reads the ## Key Files section that chapters now carry — chapters written before this format are skipped until regenerated.

Works with

Claude Code, Cursor, Amp, Warp — and any LLM tool that reads a project config file. The book itself is just markdown, so any assistant you point at it can follow along.

Design notes

Zero dependencies. Node.js built-ins only. No build step. The whole tool is plain JavaScript you can read in a few minutes.

License

MIT