HookStack
Back to catalogue
DocumentationSessionStart

OKF bundle staleness reminder on session start

Never let your project knowledge base go stale and lie to you

On every session start, checks the freshness of an OKF knowledge bundle (okf/). Silent when fresh (zero noise). If the last log entry is older than 14 days, injects a short enrichment directive so the bundle is refreshed before the session ends. No-op when scripts/okf.mjs or okf/log.md are absent.

What does the OKF bundle staleness reminder on session start hook do?

OKF bundle staleness reminder on session start is a Claude Code SessionStart hook. It fires automatically at that lifecycle event — outside the model, so it can't be skipped or forgotten. Never let your project knowledge base go stale and lie to you.

As a SessionStart hook it runs after the action, reacting to what just happened rather than blocking it. Because it is a deterministic Node.js script, it executes on every matching event without relying on the model to remember — the guarantee that makes agentic workflows safe to automate.

Use cases

  • Keep an agent-readable knowledge base (OKF) from rotting
  • Force periodic enrichment of project context without external cron

Tags

#documentation#okf#knowledge-management#session-start

settings.json fragment

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/okf-staleness-check.mjs"
          }
        ]
      }
    ]
  }
}

Script · .claude/hooks/okf-staleness-check.mjs

#!/usr/bin/env node
// @hookstack session-start-okf-staleness
// Auto-bonification OKF : à chaque démarrage de session, vérifie la fraîcheur du bundle.
// Silencieux si frais (zéro bruit, zéro token). Si périmé, injecte une consigne d'enrichissement.
import { execSync } from "node:child_process";
import { existsSync } from "node:fs";
import { fileURLToPath } from "node:url";

function defaultExec(cmd) {
	try {
		return execSync(cmd, { encoding: "utf8", timeout: 5_000 }).trim();
	} catch (e) {
		// okf.mjs stale sort en code 2 quand STALE → execSync throw mais stdout est dans e
		return e?.stdout?.toString().trim() || "";
	}
}

export function run({ exec = defaultExec, exists = existsSync } = {}) {
	if (!exists("scripts/okf.mjs") || !exists("okf/log.md")) return null;
	const out = exec("node scripts/okf.mjs stale");
	if (!out.includes("STALE")) return null; // frais → rien injecter
	return [
		"## OKF — bundle de connaissance périmé",
		out,
		"",
		"**Avant de clore cette session**, lancer la passe d'enrichissement OKF :",
		"déléguer au sous-agent `okf-librarian` (mode ENRICHISSEMENT) ou suivre",
		"`okf/meta/self-improvement.md`. Terminer par `node scripts/okf.mjs validate`",
		"et une entrée datée dans `okf/log.md`.",
		"",
	].join("\n");
}

/* v8 ignore next 4 */
if (process.argv[1] === fileURLToPath(import.meta.url)) {
	const result = run();
	if (result) process.stdout.write(result);
}

Learn more

Related hooks