@albinocrabs/feynman 0.2.4 → 0.2.5

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feynman",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Auto-inject ASCII diagram rules into Codex and Claude Code prompts.",
   "author": {
     "name": "apolenkov",

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented here.
 
+## 0.2.5 - 2026-05-08
+
+### Features
+
+- add SessionStart hook priming alongside UserPromptSubmit reinforcement
+- keep full diagram rules enabled by default for Claude Code and Codex
+
+### Fixes
+
+- preserve explicit /feynman off behavior with silent hooks
+- keep feynman hooks quiet by omitting status messages
+
+### Maintenance
+
+- bump package and plugin manifest versions to 0.2.5
+- expand tests for SessionStart registration and runtime behavior
+
 ## 0.2.4 - 2026-05-07
 
 Changes since v0.2.2.

package/README.md

@@ -199,8 +199,7 @@ Add to `~/.claude/settings.json` — use the absolute path, not `~/`
           {
             "type": "command",
             "command": "node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }
@@ -221,8 +220,7 @@ For Codex, add the same shape to `~/.codex/hooks.json` and set
           {
             "type": "command",
             "command": "FEYNMAN_HOME=\"$HOME/.codex\" node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }
@@ -232,6 +230,10 @@ For Codex, add the same shape to `~/.codex/hooks.json` and set
 ```
 </details>
 
+After install, feynman starts in `full` mode by default. Disable or change it
+explicitly with `/feynman off`, `/feynman lite`, `/feynman full`, or
+`/feynman ultra`.
+
 ## Intensity Levels
 
 | Level | What draws | Use when |
@@ -481,11 +483,11 @@ from day one.
 
 ## How it works
 
-The `UserPromptSubmit` hook fires on every Claude Code or Codex prompt. The
-hook reads the target-local state file (`~/.claude/.feynman/state.json` or
-`~/.codex/.feynman/state.json`), extracts the rules for the active intensity
-level, and injects them as `additionalContext` — invisible to you, visible to
-the model on every message.
+The `SessionStart` hook primes fresh Claude Code or Codex sessions with the
+active rules, and the `UserPromptSubmit` hook reinforces them on every prompt.
+Both hooks read the target-local state file
+(`~/.claude/.feynman/state.json` or `~/.codex/.feynman/state.json`), extract
+the rules for the active intensity level, and inject them into model context.
 
 ```
 [your prompt]

package/bin/feynman.js

@@ -29,6 +29,7 @@ const HOME = os.homedir();
 
 // Hook script lives relative to this file
 const HOOK_PATH = path.resolve(__dirname, '..', 'hooks', 'feynman-activate.js');
+const SESSION_HOOK_PATH = path.resolve(__dirname, '..', 'hooks', 'feynman-session-start.js');
 const RULES_PATH = path.resolve(__dirname, '..', 'rules', 'feynman-activate.md');
 
 const DEFAULT_STATE = { enabled: true, intensity: 'full', injections: 0 };
@@ -425,11 +426,11 @@ Claude creates:
   ~/.claude/.feynman-active        — presence flag
 
 Codex creates:
-  ~/.codex/hooks.json              — UserPromptSubmit hook registration
+  ~/.codex/hooks.json              — SessionStart + UserPromptSubmit hook registration
   ~/.codex/.feynman/state.json     — feynman state (enabled, intensity, injections)
   ~/.codex/.feynman-active         — presence flag
 
-Idempotent by default: skips if feynman-activate.js entry already exists.
+Idempotent by default: skips if feynman hook entries already exist.
 `;
 
 const UNINSTALL_HELP = `${c.bold('feynman uninstall')} — remove feynman hook
@@ -451,11 +452,11 @@ ${c.bold('Usage:')}
 
 Checks:
   1. target hook config present
-  2. UserPromptSubmit hook references feynman-activate.js
-  3. Hook script file exists and is readable
+  2. SessionStart and UserPromptSubmit hooks reference feynman scripts
+  3. Hook script files exist and are readable
   4. Rules file exists and is non-empty
   5. state.json valid JSON with enabled field
-  6. .feynman-active flag present
+  6. .feynman-active flag matches enabled state
   7. (INFO) lint hook registered (optional)
 
 Exit code: always 0 (advisory only).
@@ -507,23 +508,31 @@ function writeSettings(target, settings) {
 }
 
 function hasFeynmanHook(settings) {
-  return ((settings.hooks && settings.hooks.UserPromptSubmit) || []).some(g =>
+  const promptHook = ((settings.hooks && settings.hooks.UserPromptSubmit) || []).some(g =>
     g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-activate.js'))
   );
+  const sessionHook = ((settings.hooks && settings.hooks.SessionStart) || []).some(g =>
+    g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-session-start.js'))
+  );
+  return promptHook && sessionHook;
 }
 
 function removeFeynmanHooks(settings) {
-  if (!settings.hooks || !Array.isArray(settings.hooks.UserPromptSubmit)) return settings;
-  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(g =>
-    !(g.hooks && g.hooks.some(h =>
-      h.command && (
-        h.command.includes('feynman-activate.js') ||
-        h.command.includes('feynman-lint.js')
-      )
-    ))
-  );
-  if (settings.hooks.UserPromptSubmit.length === 0) {
-    delete settings.hooks.UserPromptSubmit;
+  if (!settings.hooks) return settings;
+  for (const eventName of ['SessionStart', 'UserPromptSubmit', 'Stop']) {
+    if (!Array.isArray(settings.hooks[eventName])) continue;
+    settings.hooks[eventName] = settings.hooks[eventName].filter(g =>
+      !(g.hooks && g.hooks.some(h =>
+        h.command && (
+          h.command.includes('feynman-session-start.js') ||
+          h.command.includes('feynman-activate.js') ||
+          h.command.includes('feynman-lint.js')
+        )
+      ))
+    );
+    if (settings.hooks[eventName].length === 0) {
+      delete settings.hooks[eventName];
+    }
   }
   if (Object.keys(settings.hooks).length === 0) {
     delete settings.hooks;
@@ -534,10 +543,21 @@ function removeFeynmanHooks(settings) {
 function bootstrapState(target) {
   const cfg = targetConfig(target);
   fs.mkdirSync(cfg.feynmanDir, { recursive: true });
+  let state = DEFAULT_STATE;
   if (!fs.existsSync(cfg.statePath)) {
     fs.writeFileSync(cfg.statePath, JSON.stringify(DEFAULT_STATE, null, 2) + '\n');
+  } else {
+    try {
+      state = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(cfg.statePath, 'utf8')) };
+    } catch (_) {
+      fs.writeFileSync(cfg.statePath, JSON.stringify(DEFAULT_STATE, null, 2) + '\n');
+    }
+  }
+  if (state.enabled) {
+    fs.writeFileSync(cfg.flagPath, state.intensity || DEFAULT_STATE.intensity);
+  } else if (fs.existsSync(cfg.flagPath)) {
+    fs.unlinkSync(cfg.flagPath);
   }
-  fs.writeFileSync(cfg.flagPath, DEFAULT_STATE.intensity);
 }
 
 function installClaudeCommand() {
@@ -561,6 +581,7 @@ function installOne(target, opts) {
   // Read or create settings
   const cfg = readSettings(target);
   cfg.hooks = cfg.hooks || {};
+  cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
   cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
 
   // Idempotency check
@@ -572,20 +593,36 @@ function installOne(target, opts) {
     return { target, already: true };
   }
 
-  // If force + already, remove old entry first
+  // If force or partial legacy install, remove old feynman entries first.
   if (already && force) {
     removeFeynmanHooks(cfg);
     cfg.hooks = cfg.hooks || {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
+    cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
+  } else if (!already) {
+    removeFeynmanHooks(cfg);
+    cfg.hooks = cfg.hooks || {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
     cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
   }
 
-  // Append hook entry
+  // Append hook entries
+  const sessionEntry = {
+    hooks: [{
+      type: 'command',
+      command: hookCommandFor(target).replace(HOOK_PATH, SESSION_HOOK_PATH),
+      timeout: 5,
+    }]
+  };
+  if (target === 'codex') {
+    sessionEntry.matcher = 'startup|resume';
+  }
+  cfg.hooks.SessionStart.push(sessionEntry);
   cfg.hooks.UserPromptSubmit.push({
     hooks: [{
       type: 'command',
       command: hookCommandFor(target),
       timeout: 5,
-      statusMessage: 'Injecting diagram rules...',
     }]
   });
 
@@ -623,7 +660,7 @@ function cmdInstall(opts) {
   }
   console.log('└──────────────────────────────────────────────────────────────┘');
   console.log('');
-  console.log('Restart Claude Code or Codex to activate feynman.');
+  console.log('Restart Claude Code or Codex to activate feynman full mode.');
 
   process.exit(0);
 }
@@ -684,11 +721,24 @@ function cmdDoctor(opts = {}) {
   const settingsExists = fs.existsSync(tc.settingsPath);
   check(`${tc.settingsPath.replace(HOME, '~')} present`, settingsExists);
 
-  // 2. UserPromptSubmit hook references feynman-activate.js
+  // 2. SessionStart and UserPromptSubmit hooks reference feynman scripts
+  let sessionHookRegistered = false;
   let hookRegistered = false;
+  let sessionHookAbsPath = null;
   let hookAbsPath = null;
   if (settingsExists) {
     const cfg = readSettings(target);
+    const sessionEntries = (cfg.hooks && cfg.hooks.SessionStart) || [];
+    const feynmanSessionEntry = sessionEntries.find(g =>
+      g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-session-start.js'))
+    );
+    sessionHookRegistered = !!feynmanSessionEntry;
+    if (feynmanSessionEntry) {
+      const hookCmd = feynmanSessionEntry.hooks.find(h => h.command && h.command.includes('feynman-session-start.js')).command;
+      const match = hookCmd.match(/"([^"]+feynman-session-start\.js)"/);
+      if (match) sessionHookAbsPath = match[1];
+    }
+
     const entries = (cfg.hooks && cfg.hooks.UserPromptSubmit) || [];
     const feynmanEntry = entries.find(g =>
       g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-activate.js'))
@@ -701,9 +751,24 @@ function cmdDoctor(opts = {}) {
       if (match) hookAbsPath = match[1];
     }
   }
+  check('hook registered (feynman-session-start.js in SessionStart)', sessionHookRegistered);
   check('hook registered (feynman-activate.js in UserPromptSubmit)', hookRegistered);
 
-  // 3. Hook script file exists + readable
+  // 3. Hook script files exist + readable
+  let sessionHookFileOk = false;
+  if (sessionHookAbsPath) {
+    try {
+      fs.accessSync(sessionHookAbsPath, fs.constants.R_OK);
+      sessionHookFileOk = true;
+    } catch (_) {}
+  } else if (sessionHookRegistered) {
+    try {
+      fs.accessSync(SESSION_HOOK_PATH, fs.constants.R_OK);
+      sessionHookFileOk = true;
+    } catch (_) {}
+  }
+  check('session hook script file exists and is readable', sessionHookFileOk);
+
   let hookFileOk = false;
   if (hookAbsPath) {
     try {
@@ -717,7 +782,7 @@ function cmdDoctor(opts = {}) {
       hookFileOk = true;
     } catch (_) {}
   }
-  check('hook script file exists and is readable', hookFileOk);
+  check('prompt hook script file exists and is readable', hookFileOk);
 
   // 4. Rules file exists + non-empty
   let rulesOk = false;
@@ -729,15 +794,20 @@ function cmdDoctor(opts = {}) {
 
   // 5. state.json valid JSON + has enabled field
   let stateOk = false;
+  let stateEnabled = false;
   try {
     const state = JSON.parse(fs.readFileSync(tc.statePath, 'utf8'));
     stateOk = 'enabled' in state;
+    stateEnabled = state.enabled === true;
   } catch (_) {}
   check('state.json valid (has enabled field)', stateOk);
 
-  // 6. .feynman-active flag present
+  // 6. .feynman-active flag matches state
   const flagPresent = fs.existsSync(tc.flagPath);
-  check('.feynman-active flag present', flagPresent);
+  check(
+    stateEnabled ? '.feynman-active flag present when enabled' : '.feynman-active flag absent when disabled',
+    stateEnabled ? flagPresent : !flagPresent
+  );
 
   // 7. (INFO) lint hook registered
   let lintHookRegistered = false;

package/docs/architecture.md

@@ -6,16 +6,18 @@ Three independent layers: hook lifecycle, lint pipeline, and state schema.
 
 ## Layer 1: Hook Lifecycle
 
-The `UserPromptSubmit` hook fires before every Claude Code or Codex prompt.
-feynman intercepts the event, reads the active rules, and injects them as
-`additionalContext`.
+The `SessionStart` hook primes fresh Claude Code or Codex sessions with the
+active rules. The `UserPromptSubmit` hook fires before every prompt and
+reinforces the same rules as `additionalContext`.
 
 ```
 ~/.claude/settings.json       ~/.codex/hooks.json
          │
-         │  hooks.UserPromptSubmit fires on every prompt
+         ├─ hooks.SessionStart primes new sessions
+         │
+         └─ hooks.UserPromptSubmit reinforces every prompt
          ▼
-hooks/feynman-activate.js
+hooks/feynman-session-start.js + hooks/feynman-activate.js
          │
          ├─ [0] FEYNMAN_HOME selects client state root
          │        unset              → ~/.claude (backward compatible)
@@ -25,9 +27,10 @@ hooks/feynman-activate.js
          ├─ [1] validate session_id (path-traversal guard)
          │
          ├─ [2] $FEYNMAN_HOME/.feynman-active  ← flag file
-         │        absent + no state.json   → bootstrap first run
-         │        absent + state.json      → exit 0 (user disabled)
-         │        present                  → continue
+         │        absent + no state.json      → bootstrap first run
+         │        absent + state.enabled=true → recreate flag
+         │        absent + state.enabled=false → exit 0 (user disabled)
+         │        present                     → continue
          │
          ├─ [3] $FEYNMAN_HOME/.feynman/state.json
          │        enabled: false           → exit 0
@@ -121,7 +124,7 @@ All runtime state lives in two files under the selected client root:
 ~/.claude/ or ~/.codex/
 ├── .feynman-active          ← presence flag
 │     present  = feynman active
-│     absent   = user disabled (state.json preserved)
+│     absent   = user disabled only when state.enabled=false
 │     content  = current intensity string (informational)
 │
 └── .feynman/

package/hooks/feynman-activate.js

@@ -31,18 +31,25 @@ process.stdin.on('end', () => {
     if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
 
     // Step 2: flag file + first-run bootstrap (D-05, D-07, bug #35713)
-    // True first run: neither flag nor state exists → bootstrap both, then fall through
-    // Intentionally disabled: flag absent but state exists → exit 0 (user ran /feynman off)
+    // True first run: neither flag nor state exists -> bootstrap default full mode.
+    // Intentionally disabled: flag absent + state.enabled=false -> exit 0.
     const flagExists  = fs.existsSync(FLAG_PATH);
     const stateExists = fs.existsSync(STATE_PATH);
     if (!flagExists) {
       if (!stateExists) {
-        // First install — bootstrap everything and activate
+        // First install: bootstrap and activate full mode.
         fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
         fs.writeFileSync(STATE_PATH, JSON.stringify(DEFAULT_STATE, null, 2));
         fs.writeFileSync(FLAG_PATH, DEFAULT_STATE.intensity);
       } else {
-        process.exit(0); // disabled intentionally by user
+        let existingState;
+        try {
+          existingState = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+        } catch (_) {
+          process.exit(0);
+        }
+        if (!existingState.enabled) process.exit(0);
+        fs.writeFileSync(FLAG_PATH, existingState.intensity || DEFAULT_STATE.intensity);
       }
     }
 

package/hooks/feynman-session-start.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// feynman — SessionStart hook — injects active diagram rules at session start.
+// UserPromptSubmit still reinforces rules every turn; this primes fresh sessions.
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const HOME        = os.homedir();
+const CLIENT_HOME = process.env.FEYNMAN_HOME || path.join(HOME, '.claude');
+const FEYNMAN_DIR = path.join(CLIENT_HOME, '.feynman');
+const STATE_PATH  = path.join(FEYNMAN_DIR, 'state.json');
+const FLAG_PATH   = path.join(CLIENT_HOME, '.feynman-active');
+const RULES_PATH  = path.join(__dirname, '..', 'rules', 'feynman-activate.md');
+
+const DEFAULT_STATE = { enabled: true, intensity: 'full', injections: 0 };
+const VALID_INTENSITIES = ['lite', 'full', 'ultra'];
+
+function readState() {
+  try {
+    return { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+  } catch (_) {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+function writeState(state) {
+  fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+
+function readRules(intensity) {
+  const rulesContent = fs.readFileSync(RULES_PATH, 'utf8');
+  const selected = VALID_INTENSITIES.includes(intensity) ? intensity : 'full';
+  const openMarker  = '<!-- ' + selected + ' -->';
+  const closeMarker = '<!-- /' + selected + ' -->';
+  const i1 = rulesContent.indexOf(openMarker);
+  const i2 = rulesContent.indexOf(closeMarker, i1);
+  if (i1 === -1 || i2 === -1) return '';
+  return rulesContent.slice(i1 + openMarker.length, i2).trim();
+}
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (input.trim()) {
+      const data = JSON.parse(input);
+      const sessionId = data.session_id || '';
+      if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
+    }
+
+    const stateExists = fs.existsSync(STATE_PATH);
+    const flagExists = fs.existsSync(FLAG_PATH);
+    const state = readState();
+
+    if (!stateExists) {
+      writeState(state);
+    }
+
+    if (!state.enabled) {
+      try { fs.unlinkSync(FLAG_PATH); } catch (_) {}
+      process.exit(0);
+    }
+
+    if (!flagExists) {
+      fs.writeFileSync(FLAG_PATH, state.intensity || DEFAULT_STATE.intensity);
+    }
+
+    const rulesText = readRules(state.intensity);
+    if (!rulesText) process.exit(0);
+
+    // SessionStart accepts plain stdout as context, matching caveman's hook shape.
+    process.stdout.write(rulesText);
+  } catch (_) {
+    process.exit(0);
+  }
+});

package/hooks/hooks.json

@@ -1,14 +1,24 @@
 {
   "description": "Inject feynman ASCII diagram rules before each Claude Code prompt.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }

package/hooks.json

@@ -1,13 +1,24 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@albinocrabs/feynman",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Claude Code and Codex plugin that auto-injects ASCII diagram rules into every AI request via UserPromptSubmit hook",
   "license": "MIT",
   "author": "apolenkov",

package/skills/feynman/SKILL.md

@@ -28,7 +28,7 @@ node -e "
 const fs = require('fs'), os = require('os'), path = require('path');
 const stateFile = path.join(os.homedir(), '.claude', '.feynman', 'state.json');
 const flagFile  = path.join(os.homedir(), '.claude', '.feynman-active');
-let st = {enabled: false, intensity: 'full', injections: 0};
+let st = {enabled: true, intensity: 'full', injections: 0};
 try { st = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch(e) {}
 console.log('enabled:', st.enabled, '| intensity:', st.intensity, '| injections:', (st.injections ?? st.count ?? 0), '| flag:', fs.existsSync(flagFile));
 "
@@ -43,7 +43,7 @@ const stateFile = path.join(os.homedir(), '.claude', '.feynman', 'state.json');
 const flagFile  = path.join(os.homedir(), '.claude', '.feynman-active');
 const arg = (process.argv[1] || '').trim().toLowerCase();
 const normalized = arg === 'start' ? 'on' : arg === 'stop' ? 'off' : arg;
-let st = {enabled: true, intensity: 'full', injections: 0};
+let st = {enabled: false, intensity: 'full', injections: 0};
 try { st = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch(e) {}
 if (normalized === 'on')  { st.enabled = true;  fs.writeFileSync(flagFile, st.intensity); }
 if (normalized === 'off') { st.enabled = false; try { fs.unlinkSync(flagFile); } catch(e) {} }