@albinocrabs/feynman 0.2.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "feynman",
+  "version": "0.2.0",
+  "description": "Auto-inject ASCII diagram rules into Codex and Claude Code prompts.",
+  "author": {
+    "name": "apolenkov",
+    "url": "https://github.com/apolenkov/feynman"
+  },
+  "homepage": "https://github.com/apolenkov/feynman",
+  "repository": "https://github.com/apolenkov/feynman",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "claude-code",
+    "ascii",
+    "diagrams",
+    "hooks",
+    "productivity"
+  ],
+  "hooks": "./hooks.json",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "feynman",
+    "shortDescription": "Draw ASCII diagrams when structure appears.",
+    "longDescription": "feynman injects concise diagram rules on every prompt so flows, hierarchies, comparisons, priorities, and status summaries render as readable ASCII diagrams.",
+    "developerName": "apolenkov",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/apolenkov/feynman",
+    "privacyPolicyURL": "https://github.com/apolenkov/feynman/blob/main/README.md",
+    "termsOfServiceURL": "https://github.com/apolenkov/feynman/blob/main/LICENSE",
+    "defaultPrompt": [
+      "Use feynman diagrams for structured answers.",
+      "Explain this architecture visually.",
+      "Compare these options with ASCII columns."
+    ],
+    "brandColor": "#10B981",
+    "screenshots": []
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apolenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+<p align="center">
+  <img src="https://em-content.zobj.net/source/apple/391/pencil_270f-fe0f.png" width="120" />
+</p>
+
+<h1 align="center">feynman</h1>
+
+<p align="center">
+  <strong>why explain in words when diagram do trick</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@albinocrabs/feynman"><img src="https://img.shields.io/npm/v/@albinocrabs/feynman?style=flat&color=blue" alt="npm version"></a>
+  <a href="https://github.com/apolenkov/feynman/actions/workflows/ci.yml"><img src="https://github.com/apolenkov/feynman/workflows/CI/badge.svg" alt="CI"></a>
+  <a href="https://github.com/apolenkov/feynman/blob/main/.github/coverage-badge.json"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/apolenkov/feynman/main/.github/coverage-badge.json" alt="Coverage"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/apolenkov/feynman?style=flat" alt="License"></a>
+  <a href="https://github.com/apolenkov/feynman/stargazers"><img src="https://img.shields.io/github/stars/apolenkov/feynman?style=flat&color=yellow" alt="Stars"></a>
+  <a href="https://github.com/apolenkov/feynman/commits/main"><img src="https://img.shields.io/github/last-commit/apolenkov/feynman?style=flat" alt="Last Commit"></a>
+</p>
+
+<p align="center">
+  <a href="#why-feynman">Why</a> •
+  <a href="#before--after">Before/After</a> •
+  <a href="#install">Install</a> •
+  <a href="#intensity-levels">Levels</a> •
+  <a href="#lint">Lint</a> •
+  <a href="#examples">Examples</a> •
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Codex
+plugin that automatically injects ASCII diagram rules into every prompt via the
+`UserPromptSubmit` hook.
+
+<!-- TODO: GIF after v0.3.0 visual capture -->
+
+## Why feynman
+
+Structured information explained in prose forces you to rebuild the structure
+in your head before you can reason about it. feynman intercepts every Claude
+Code or Codex prompt and injects rules that turn flows into arrows,
+hierarchies into trees, comparisons into columns, and status into frames. The
+structure is visible before you have to think about it.
+
+## Before / After
+
+<table>
+<tr>
+<td width="50%">
+
+### Without feynman
+
+> "The deployment pipeline has three stages: first the code is built, then tests run, then it deploys to prod."
+
+</td>
+<td width="50%">
+
+### With feynman
+
+```
+[Build] --> [Test] --> [Deploy]
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+### Without feynman
+
+> "Option A is fast but stateless. Option B is slower but persists data. Option C gives you both at higher cost."
+
+</td>
+<td>
+
+### With feynman
+
+```
+Option A       | Option B      | Option C
+---------------|---------------|----------
+fast startup   | slow startup  | medium
+stateless      | persistent    | persistent
+free           | free          | $$$
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+### Without feynman
+
+> "Fix the auth bug first since it's a security issue, then the memory leak, then the slow query."
+
+</td>
+<td>
+
+### With feynman
+
+```
+▲ high
+  auth bug (security)
+  memory leak
+▼ low
+  slow query
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+### Without feynman
+
+> "The auth service talks to Redis for rate limiting and Postgres for user data."
+
+</td>
+<td>
+
+### With feynman
+
+```
+[Auth Service]
+     ├── [Redis]    rate limiter
+     └── [Postgres] user data
+```
+
+</td>
+</tr>
+</table>
+
+## Install
+
+**Claude Code via npx:**
+
+```bash
+npx @albinocrabs/feynman install --target claude
+```
+
+**Codex via npx:**
+
+```bash
+npx @albinocrabs/feynman install --target codex
+```
+
+**Both clients:**
+
+```bash
+npx @albinocrabs/feynman install --target both
+```
+
+The install command is idempotent: running it again updates the existing
+feynman hook instead of adding duplicates.
+
+**Claude Code via bash one-liner:**
+
+```bash
+git clone https://github.com/apolenkov/feynman && bash feynman/install.sh
+```
+
+Restart Claude Code or Codex. Done.
+
+**Verify:** `npx @albinocrabs/feynman doctor --target claude` or `npx @albinocrabs/feynman doctor --target codex`
+
+**Uninstall:** `npx @albinocrabs/feynman uninstall --target claude|codex|both`
+
+**Plugin manifests:** this repo also ships `.claude-plugin/plugin.json`,
+`hooks/hooks.json`, `.codex-plugin/plugin.json`, and `hooks.json` so plugin
+marketplaces can discover feynman. The npx installer remains the production
+fallback because both clients still support direct user hook registration.
+
+<details>
+<summary>Manual install</summary>
+
+Add to `~/.claude/settings.json` — use the absolute path, not `~/`
+([bug #8810](https://github.com/anthropics/claude-code/issues/8810)):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
+            "timeout": 5,
+            "statusMessage": "Injecting diagram rules..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+For Codex, add the same shape to `~/.codex/hooks.json` and set
+`FEYNMAN_HOME` so state lives under `~/.codex`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.codex\" node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
+            "timeout": 5,
+            "statusMessage": "Injecting diagram rules..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+</details>
+
+## Intensity Levels
+
+| Level | What draws | Use when |
+|-------|-----------|----------|
+| **lite** | Flows + trees only | Minimal, subtle |
+| **full** | All 5 diagram types (default) | Normal use |
+| **ultra** | Force diagram even for short answers | Maximum visual structure |
+
+Toggle via `/feynman`:
+
+```
+/feynman lite    — flows and trees only
+/feynman full    — all diagram types
+/feynman ultra   — force diagrams always
+/feynman off     — disable
+/feynman on      — re-enable
+/feynman status  — show current state
+```
+
+## Lint
+
+feynman includes a linter for ASCII diagrams. It catches structural errors
+before they reach readers: unclosed boxes, wrong tree characters, mixed arrow
+styles, inconsistent column counts, and more.
+
+```bash
+npx @albinocrabs/feynman lint response.md
+```
+
+See [docs/lint-rules.md](docs/lint-rules.md) for the full L01-L08 reference.
+
+## Examples
+
+Domain-specific examples showing feynman in practice:
+
+- [Architecture review](examples/architecture-review.md) — auth service topology
+- [API flow](examples/api-flow.md) — POST /api/login request lifecycle
+- [Database schema](examples/db-schema.md) — e-commerce entity model
+- [Algorithm walkthrough](examples/algorithm-explain.md) — token-bucket rate limiter
+- [Deploy pipeline](examples/deploy-pipeline.md) — monorepo CI/CD
+- [Code review](examples/code-review.md) — priority + comparison diagrams
+
+## How it works
+
+The `UserPromptSubmit` hook fires on every Claude prompt. The hook reads
+`~/.claude/.feynman/state.json`, extracts the rules for the active intensity
+level, and injects them as `additionalContext` — invisible to you, visible to
+Claude on every message.
+
+```
+[your prompt]
+      +
+[feynman rules]    ← injected by hook, ~2KB
+      │
+      ▼
+  [Claude]
+      │
+      ▼
+[structured response with ASCII diagrams]
+```
+
+State is stored at `~/.claude/.feynman/state.json`. First run bootstraps
+automatically. See [docs/architecture.md](docs/architecture.md) for internals.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR checklist, and
+rules-authoring guidelines.
+
+## License
+
+MIT

package/bin/feynman-lint.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// bin/feynman-lint.js — feynman diagram linter CLI
+// Usage: feynman-lint <file.md>
+//        feynman-lint -          (stdin)
+//        feynman-lint --json <file>
+//        feynman-lint --strict <file>
+//        feynman-lint --help
+// Exit codes: 0 = pass, 1 = lint failure, 2 = usage error
+// Zero deps. CJS only.
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { lint, format } = require('../lib/lint');
+
+const USAGE = `Usage: feynman-lint <file.md>
+       feynman-lint -          (read from stdin)
+       feynman-lint --json <file>
+       feynman-lint --strict <file>
+       feynman-lint --help
+
+Options:
+  --json    Output issues as JSON object
+  --strict  Treat warnings as errors (exit 1 on any issue)
+  --help    Show this help message
+
+Exit codes:
+  0   No errors (or no issues in default mode)
+  1   Lint failure (errors found, or warnings in --strict mode)
+  2   Usage error (bad arguments, file not found)
+`;
+
+// Parse arguments
+const argv = process.argv.slice(2);
+let useJson   = false;
+let useStrict = false;
+let filePath  = null;
+let useStdin  = false;
+
+for (const arg of argv) {
+  if (arg === '--json')   { useJson   = true; continue; }
+  if (arg === '--strict') { useStrict = true; continue; }
+  if (arg === '--help')   { process.stdout.write(USAGE); process.exit(0); }
+  if (arg === '-')        { useStdin  = true; continue; }
+  if (arg.startsWith('-') && arg !== '-') {
+    process.stderr.write(`feynman-lint: unknown flag '${arg}'\n${USAGE}`);
+    process.exit(2);
+  }
+  if (filePath) {
+    process.stderr.write(`feynman-lint: too many file arguments\n${USAGE}`);
+    process.exit(2);
+  }
+  filePath = arg;
+}
+
+if (!filePath && !useStdin) {
+  process.stderr.write(USAGE);
+  process.exit(2);
+}
+
+function run(markdown, displayName) {
+  const result = lint(markdown);
+  const { issues } = result;
+
+  if (useJson) {
+    const out = {
+      file: displayName,
+      passed: useStrict ? issues.length === 0 : result.passed,
+      issues,
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    const failed = useStrict ? issues.length > 0 : !result.passed;
+    process.exit(failed ? 1 : 0);
+  }
+
+  // gcc mode
+  const isTTY = process.stdout.isTTY;
+  const output = format(issues, 'gcc', displayName, isTTY);
+
+  if (output) {
+    process.stdout.write(output + '\n');
+  }
+
+  // Determine pass/fail
+  const failed = useStrict
+    ? issues.length > 0
+    : !result.passed;
+
+  if (failed) {
+    const errCount  = issues.filter(i => i.severity === 'error').length;
+    const warnCount = issues.filter(i => i.severity === 'warn').length;
+    const parts = [];
+    if (errCount)  parts.push(`${errCount} error${errCount  !== 1 ? 's' : ''}`);
+    if (warnCount) parts.push(`${warnCount} warning${warnCount !== 1 ? 's' : ''}`);
+    process.stderr.write(`${displayName}: ${parts.join(', ')}\n`);
+    process.exit(1);
+  } else {
+    process.exit(0);
+  }
+}
+
+// Read input
+if (useStdin) {
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { buf += chunk; });
+  process.stdin.on('end', () => run(buf, '<stdin>'));
+} else {
+  // File mode
+  const absPath = path.resolve(filePath);
+  if (!fs.existsSync(absPath)) {
+    process.stderr.write(`feynman-lint: file not found: ${filePath}\n`);
+    process.exit(2);
+  }
+  let markdown;
+  try {
+    markdown = fs.readFileSync(absPath, 'utf8');
+  } catch (e) {
+    process.stderr.write(`feynman-lint: cannot read file: ${filePath}: ${e.message}\n`);
+    process.exit(2);
+  }
+  run(markdown, filePath);
+}