pwgen Knowledge Hub

WebAssembly password generator compiled for CLI, Custom Elements, ESM, Node.js, and Web App exploration, powered by ShadowClaw.

pwgen-knowledge-hub is an interactive documentation platform and demonstration engine built on top of ShadowClaw. It showcases pwgen—the C-based Unix password generator utility compiled to WebAssembly by Karl Herrick.

This repository details:

• How pwgen was built: Compiling C source code (pwgen.c, pw_phonemes.c, pw_rand.c, sha1.c) with Emscripten into optimized WebAssembly bytecode.
• Why it was built: Providing standard Unix password security directly to browsers, Node.js, CLI, and Custom Elements with zero external network dependencies or native binary compilation requirements.
• Evolution of target ecosystems: Exploring modern ESM + Base64 WASM inlining, Custom Elements (<x-pwgen>), as well as historical targets like Chrome Web Bundles (.wbn) and Wasmer WAPM.
• Interactive AI Agent Integration: Exposing pwgen generation controls directly to AI agents via declarative JSON tools and WebMCP BroadcastChannel inter-process communication.

Run the pwgen Knowledge Hub locally using the shadow-claw CLI with zero installation:

Start the local server and automatically open the site in your default browser:

npx shadow-claw dev --open -y

• 🌐 Serves the interactive knowledge hub and live password generator on http://127.0.0.1:8888
• --open: Automatically opens your default web browser on launch
• -y: Accepts the default cache directory (.cache) without interactive prompts

# Run on a custom port
npx shadow-claw dev 3000 --open -y

# Run headlessly without opening a browser
npx shadow-claw dev -y

# Build the static distribution into ./dist/public
npx shadow-claw build

# Serve pre-built static distribution
npx shadow-claw serve

View the live interactive demo and complete documentation on GitHub Pages:

• pwgen
• pwgen Knowledge Hub

Generate passwords instantly on any terminal:

npx pwgen -sy 20 1

Embed zero-dependency password generation directly in HTML:

<x-pwgen flags="-sy" length="20" number="1"></x-pwgen>

<script type="module">
  import "https://unpkg.com/pwgen";

  document.addEventListener("x-pwgen-handle-password", ({ detail }) => {
    console.log("Generated Password:", detail.msg);
  });
</script>

pwgen-knowledge-hub exposes three declarative tools and slash commands (/pwgen, /pwgen-help, /pwgen-entropy):

1. pwgen: Generates custom passwords via WASM engine. Accepts flags, length, and count.
2. pwgen_help: Provides human-readable breakdowns of CLI options.
3. pwgen_entropy: Calculates exact bits of mathematical entropy, pool size, and strength classification.

• Core Engine Script (pwgen.js): Portable ES module containing pure computation, parameter parsing, and tool execution without DOM dependencies.
• Custom Element Factory (pwgen-element.js): Portable <x-pwgen> component factory, attribute syncing, and BroadcastChannel bridge installer.
• Host Presentation Adapter (.agents/scripts/main/pwgen-adapter.js): Manages <x-pwgen> DOM synchronization and UI controls.
• BroadcastChannel Bridge: Inter-process communication over pwgen-commands and pwgen-results channels.

Exposed over HTTP per the Agent Skills Discovery RFC:

/.well-known/agent-skills/index.json