replen 0.3.0 → 0.4.1

package/README.md

@@ -29,6 +29,9 @@ npx replen logout       # forget saved auth (token stays valid; rotate on /setti
 ```bash
 npx replen run                  # trigger a pipeline run
 npx replen progress             # tail the run live; exits when done
+npx replen check-new            # one-shot: any new actionable matches since
+                                # you last engaged? (also runs automatically
+                                # at every Claude Code session start)
 npx replen feed                 # show recent matches (default 2 days)
 npx replen watch                # keep a terminal open — rings the bell when
                                 # a new match lands. Default poll 5min.
@@ -37,7 +40,9 @@ npx replen starred              # starred matches + handoff PR status
 npx replen handoff <matchId>    # open the handoff PR for a starred match
 ```
 
-`watch` is the calm-utility companion: leave it running in a `tmux` pane and forget about it. The first poll establishes a baseline; existing matches don't ring. Pair with `--no-bell` for a silent log feed, or `--json` to pipe into anything.
+`watch` is the calm-utility companion: leave it running in a `tmux` pane and forget about it. The first poll establishes a baseline; existing matches don't ring.
+
+`check-new` is wired into Claude Code automatically by `npx replen` setup — it installs a SessionStart hook that runs `npx replen check-new --hook` whenever you open Claude Code. The hook is silent unless there's something new since you last engaged (across dashboard, email, or a prior session); when there is, the new matches show up in the agent's opening context without you having to ask. Calm-cadence by design.
 
 Every data command accepts `--json` for scripting.
 

package/dist/commands.js

@@ -2,6 +2,7 @@
 // terminal rather than returning JSON to an agent. `--json` flag on every
 // command dumps raw JSON for piping/scripting.
 import { apiGet, apiPost, loadConfigOrExit } from "./api.js";
+import { configPath } from "./config.js";
 function hasFlag(argv, flag) {
     return argv.includes(flag);
 }
@@ -169,6 +170,111 @@ export async function runStarred(argv) {
         handleApiError(e);
     }
 }
+// One-shot "is there anything new" check. Used in two modes:
+//   1. interactive (`replen check-new`): always prints — useful for ad-hoc
+//      "did anything land?" before opening Claude Code.
+//   2. hook (`replen check-new --hook`): SILENT when nothing's new. Bounded
+//      timeout (5s) so a slow API can't stall every Claude Code session
+//      opening. Uses AbortController to actually cancel the in-flight fetch
+//      on timeout — without that, an aborted hook would still let the server
+//      finish + bump the cursor, "consuming" the matches without ever
+//      surfacing them. Errors are swallowed and never fail the session.
+//      Output is shaped so Claude Code's SessionStart-hook stdout injection
+//      naturally surfaces the matches in the agent's opening context.
+export async function runCheckNew(argv) {
+    const hookMode = hasFlag(argv, "--hook");
+    const json = hasFlag(argv, "--json");
+    const repo = getFlag(argv, "--repo");
+    // Hook mode runs on every Claude Code session for every user — including
+    // users who installed Claude Code but never ran `npx replen`. Silent exit
+    // (not the "Not signed in" prompt loadConfigOrExit prints) is required.
+    const { readConfig } = await import("./config.js");
+    const cfg = await readConfig();
+    if (!cfg) {
+        if (hookMode)
+            return;
+        console.error("Not signed in. Run `npx replen` first.");
+        process.exit(1);
+    }
+    const query = {};
+    if (repo !== undefined)
+        query.repo = repo;
+    let r;
+    try {
+        if (hookMode) {
+            // Direct fetch with AbortController so the timeout actually cancels
+            // the request (apiGet has no signal). Without this, a "timed out"
+            // hook would still let the server complete the call and bump the
+            // cursor, silently consuming the matches.
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), 5000);
+            try {
+                const url = new URL(cfg.base + "/api/mcp/check-new");
+                if (query.repo !== undefined)
+                    url.searchParams.set("repo", query.repo);
+                const res = await fetch(url, {
+                    headers: { "x-digest-token": cfg.token, accept: "application/json" },
+                    signal: ctrl.signal,
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                r = (await res.json());
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        else {
+            r = await apiGet(cfg, "/api/mcp/check-new", query);
+        }
+    }
+    catch (e) {
+        if (hookMode) {
+            // Silent failure: never disrupt a session for a non-critical signal.
+            // Trace goes to a log so we can debug if needed.
+            try {
+                const { appendFile } = await import("node:fs/promises");
+                await appendFile(configPath().replace(/config\.json$/, "check-new-hook.log"), `${new Date().toISOString()} ${e.message ?? String(e)}\n`);
+            }
+            catch {
+                // intentionally ignore — diagnostic only
+            }
+            return;
+        }
+        handleApiError(e);
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(r, null, 2));
+        return;
+    }
+    if (!r.hasNew) {
+        if (!hookMode) {
+            // Interactive: tell the user explicitly. In hook mode silence is the
+            // correct response (calm-cadence principle).
+            const scope = r.scopedTo ? ` for ${r.scopedTo}` : "";
+            console.log(`No new actionable matches${scope} since you last engaged.`);
+        }
+        return;
+    }
+    // hasNew: print a tight block. Same shape in hook + interactive — Claude
+    // Code's SessionStart hook injects stdout verbatim into the agent's
+    // opening context, so the agent sees this and naturally surfaces it.
+    const scope = r.scopedTo ?? "your projects";
+    const banner = `Replen: ${r.count} new actionable match${r.count === 1 ? "" : "es"} for ${scope} since you last engaged.`;
+    console.log(banner);
+    console.log("");
+    for (const m of r.matches ?? []) {
+        const effort = m.effortBand ? ` · ${m.effortBand}` : "";
+        const score = m.relevanceScore != null ? ` ${m.relevanceScore}` : "";
+        const repoName = m.repo ?? "(no repo)";
+        console.log(`  • ${repoName} (${m.relevance}${score}${effort})`);
+        if (m.oneLine)
+            console.log(`    ${m.oneLine}`);
+    }
+    console.log("");
+    console.log("Call replen_today for the full writeups.");
+}
 // Watch for new matches in the background. Polls /api/mcp/today, diffs against
 // the matchIds seen on the previous poll, prints anything new, and rings the
 // terminal bell (\x07). First poll establishes a baseline — existing matches

package/dist/index.js

@@ -3,7 +3,7 @@ import { runInit } from "./init.js";
 import { setupMcp } from "./mcp-setup.js";
 import { readConfig, configPath } from "./config.js";
 import { runProjectInit } from "./project-init.js";
-import { runFeed, runHandoff, runProgress, runRun, runSearch, runStarred, runWatch } from "./commands.js";
+import { runCheckNew, runFeed, runHandoff, runProgress, runRun, runSearch, runStarred, runWatch } from "./commands.js";
 const HELP = `replen: Smarter AI Development workflows
 
 Usage:
@@ -18,6 +18,10 @@ Usage:
 Use replen from a plain shell (no Claude Code / Codex needed):
   npx replen run                       Trigger a fresh pipeline run
   npx replen progress                  Live tail of the current run; exits when done
+  npx replen check-new                 One-shot: any new actionable matches
+                  [--repo OWNER/NAME]  since you last engaged? Used by the
+                                       SessionStart hook to surface new
+                                       matches automatically in Claude Code.
   npx replen feed [--days N]           Today's matches (default 2 days)
                   [--project SLUG]     Limit to one project
                   [--relevance high,medium]
@@ -96,6 +100,8 @@ async function main() {
         return runFeed(argv);
     if (cmd === "watch")
         return runWatch(argv);
+    if (cmd === "check-new")
+        return runCheckNew(argv);
     if (cmd === "search")
         return runSearch(argv);
     if (cmd === "starred")

package/dist/mcp-setup.js

@@ -59,6 +59,39 @@ export async function setupMcp(token, base) {
             DIGEST_TOKEN: token,
         },
     };
-    writeJsonAtomic(CONFIG_PATH, { ...config, mcpServers });
+    const hooks = installSessionStartHook(config.hooks ?? {});
+    writeJsonAtomic(CONFIG_PATH, { ...config, mcpServers, hooks });
     console.log(`  ✓ ${overwrite ? "Updated" : "Added"} "${SERVER_NAME}" in ${CONFIG_PATH}`);
+    console.log(`  ✓ Installed SessionStart hook (surfaces new matches automatically)`);
+}
+// SessionStart hook: on every Claude Code session, runs `replen check-new
+// --hook`, which prints a one-block summary to stdout if (and only if)
+// new actionable matches landed since the user last engaged. Claude Code
+// injects that stdout into the agent's opening context, so the agent
+// surfaces the matches to the user without anyone having to ask.
+//
+// When nothing's new the command prints nothing — silence is the calm-
+// cadence position. The 2-second timeout (handled inside check-new --hook)
+// ensures a slow API can't stall session opening.
+//
+// We use the command string `npx --quiet replen check-new --hook` as our
+// idempotency marker: if a SessionStart entry already contains that
+// substring we replace it; otherwise we append. Any other SessionStart
+// hooks the user has are preserved verbatim.
+const HOOK_COMMAND = "npx --quiet replen check-new --hook";
+const HOOK_MARKER = "replen check-new --hook";
+function installSessionStartHook(existing) {
+    const sessionStart = (existing.SessionStart ?? []).slice();
+    const ours = {
+        matcher: "*",
+        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    };
+    const idx = sessionStart.findIndex((entry) => (entry.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)));
+    if (idx >= 0) {
+        sessionStart[idx] = ours;
+    }
+    else {
+        sessionStart.push(ours);
+    }
+    return { ...existing, SessionStart: sessionStart };
 }

package/dist/project-init.js

@@ -21,7 +21,18 @@ Be specific. Use the project's actual domain vocabulary, not generic abstraction
 
 When you're done, print the draft in chat and ask me to confirm before writing the file. If a CLAUDE.md already exists, don't overwrite it without my explicit say-so.
 
-Total length target: 200-500 words, bullet points over paragraphs.`;
+Total length target: 200-500 words, bullet points over paragraphs.
+
+Also append a short "## Replen integration" section with this exact guidance:
+
+  At the start of every session, if the \`replen_check_new\` tool is
+  available, call it once before asking the user what to work on.
+  If \`hasNew\` is true, summarise the count + repos in 1-2 lines and
+  ask if the user wants the full writeups (which they get via
+  \`replen_today\`). If \`hasNew\` is false, say nothing — silence is
+  the correct response, not "no new matches found".
+
+This instruction is a fallback for AI tools that don't run Claude Code's SessionStart hooks (e.g. Codex, Cursor, Aider). For Claude Code users the hook calls \`replen check-new\` automatically and Claude Code injects the result into the opening context — but the CLAUDE.md guidance is durable across tools and survives hook misconfiguration.`;
 export function runProjectInit() {
     console.log("");
     console.log("Copy the prompt below into your AI coding tool (Claude Code / Codex / Cursor / Aider).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replen",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Smarter AI Development workflows. The AI that asks 'can we do this better?' - replen reads your codebase against the live ecosystem and surfaces drop-in libraries, ideas to port, and patterns to learn from. Calm cadence: 1-3 actionable matches a month. One-command setup: opens a browser to sign in, then wires the MCP server into Claude Code / Codex.",
   "type": "module",
   "bin": {