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

@omsimos/stackmap

v0.7.0

Published

Interactive system diagrams your coding agent writes, as one offline HTML file

Readme

Ask your coding agent to diagram a codebase, a system, a process or a request. It writes a small typed JSON, stackmap validates it with repair hints the agent acts on, lays it out, and delivers one self-contained HTML viewer. No server, no account, nothing to install to open it.

Five kinds of diagram: architecture (components and what they call), dataflow (data moving through stages), workflow (steps across owner lanes), lifecycle (the states of one thing) and sequence (messages over time).

https://github.com/user-attachments/assets/4dd05dfc-fa5a-42e7-ad1a-6150aeb9ad9f

Quick start

Install the skill into your agent (Claude Code, Cursor, Codex and others):

npx skills add omsimos/stackmap

Then ask:

Make an architecture diagram of this repository, backed by evidence from the code.

The agent writes .stackmap/<name>/diagram.json, validates and repairs it, and delivers .stackmap/<name>/diagram.html, opening it in your browser. It opens in any browser later too. To change the diagram, ask again: the agent edits the JSON and delivers it again. The viewer itself is read-only.

The viewer

  • Explore: select a card to light its connections and dim the rest, with its details and source evidence in the inspector. Trace keeps a node's upstream and downstream; Route lights every path between two nodes.
  • Find: search titles, ids and types; the lens dims the node types you don't need.
  • Guided views: tabs the agent defines, like "Checkout path", that focus one part of the diagram. Present steps through them full screen.
  • Flow: Play sends pulses along whatever you're looking at: the whole diagram, a view, a trace or a route, hop by hop.
  • Share: the URL keeps the view, selection, route and playback. Export PNG, JPEG, WebP, SVG, a short video of the flow, or the diagram again as one offline HTML file.
  • Keyboard: / search, R route, F present, P play, M minimap, Esc clear; Tab and the arrow keys reach everything else.
  • Themes: dark and light, and animations respect reduced motion.

The diagram

{
  "$schema": "https://unpkg.com/@omsimos/[email protected]/dist/stackmap.schema.json",
  "kind": "architecture",
  "title": "Bookshop",
  "direction": "DOWN",
  "groups": [{ "id": "data", "label": "Data tier" }],
  "nodes": [
    { "id": "api", "type": "service", "card": { "title": "shop-api", "subtitle": "REST API" },
      "evidence": [{ "file": "services/api/src/server.ts", "line": 12 }] },
    { "id": "db", "type": "database", "group": "data", "card": { "title": "Orders DB", "subtitle": "PostgreSQL", "brand": "postgresql" } }
  ],
  "edges": [{ "id": "api-db", "from": "api", "to": "db" }],
  "views": [{ "id": "state", "label": "State", "nodes": ["db"] }]
}
  • Nodes: nine types set the colour (client, gateway, service, database, cache, queue, storage, external, security), and lifecycles have seven state types. Cards can add rows, stats, a footer, a link and one of 146 Simple Icons logos.
  • Edges can be async or a return, with a tone for the main path, security crossings and failure paths.
  • No coordinates: stackmap lays everything out, with ELK for architecture and dataflow and its own layout for lanes and sequences.

Full reference: skill/references/schema.md, or the schema reference on the website. Modelling guidance: authoring contract.

The CLI

The skill runs the CLI for you, and it works on its own too (Node 22.12 or later):

npx @omsimos/stackmap validate diagram.json [--json]                # diagnostics with fixes; exit 1 on errors
npx @omsimos/stackmap deliver  diagram.json [-o out.html] [--open]  # validate → layout → one offline HTML file
npx @omsimos/stackmap serve    diagram.json [--port 4400]           # live viewer that reloads on every save
  • validate lists every problem with a code, its evidence and the allowed fixes, including card text that won't fit. It exits 1 when the diagram has errors and 2 on usage, IO or internal errors.
  • deliver is deterministic: the same JSON always gives the same file, byte for byte.
  • serve binds 127.0.0.1 only, keeps the last good version on screen when a save is invalid, and keeps your camera and selection across reloads.

Development

Bun workspaces monorepo; tests run on Node via Vitest and Playwright.

bun install
bun run test && bun run typecheck && bun run build   # unit tests, types, viewer template + CLI bundle

CONTRIBUTING.md covers the packages, the e2e and visual regression tests, branches, commit messages and how releases work. The mark, lockups, icons and social card are in assets/brand/, with the rules for using them.

Credits

stackmap is a successor to archify by tt-a1i, itself based on Cocoon AI's architecture-diagram-generator. It keeps archify's agent → JSON → validate → single-HTML model and its repair loop, with a new renderer and visual language. Layout by Eclipse ELK (elkjs, EPL-2.0), fonts Geist (OFL-1.1), logos Simple Icons (CC0).

License

MIT. Third-party components and their licenses: THIRD_PARTY_NOTICES.md.