@nemus-cli/nemus 0.2.12 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-27
+
+### Added
+
+- **`nemus reflect` (alias `retro`) — LLM-as-a-judge retrospective.** Analyzes
+  your most recent workspaces (default 10) by reading their agent session
+  transcripts, distilling the human prompts + tool failures + tools used, and
+  asking your own configured agent (claude/pi/opencode — no API key of ours) to
+  recommend concrete setup improvements: which **skills** to add and where,
+  missing **AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+  **prompt/workflow** habits to change — each with a priority and a concrete
+  example snippet. Reads both Claude and pi transcript formats. Flags:
+  `--limit <n>`, `--json` (structured report, same `{ok:false,error}` failure
+  contract as the other JSON commands), and `--dry-run` (print the assembled
+  corpus + judge prompt without calling the agent). Idea courtesy of
+  **@lightpriest** — thank you for the great suggestion!
+
+## [0.2.13] - 2026-08-27
+
+### Added
+
+- **Shell completions**: `nemus completion bash|zsh|fish` prints a completion
+  script for that shell. Completes subcommands (names + aliases) and, for a
+  workspace-scoped command, live **workspace names** — the script calls back
+  into `nemus completion --workspaces`, so completions stay fresh without
+  regenerating. Registered for both the `nemus` and `nem` binaries. Install e.g.
+  `nemus completion zsh > "${fpath[1]}/_nemus"` (see README).
+
 ## [0.2.12] - 2026-08-27
 
 ### Added

package/README.md

@@ -243,6 +243,24 @@ The workspace-scoped ones (`status`/`doctor`/`analyze-deps`) need an explicit
 workspace name with `--json` (they never prompt). On failure, `--json` prints a
 parseable `{ "ok": false, "error": … }` to stdout and exits non-zero.
 
+### Shell completions
+
+Tab-complete subcommands and workspace names. `nemus completion <shell>` prints
+a script for `bash`, `zsh`, or `fish` (works for both the `nemus` and `nem`
+binaries):
+
+```bash
+# bash
+nemus completion bash > /etc/bash_completion.d/nemus     # or >> ~/.bashrc
+# zsh (a directory on your $fpath)
+nemus completion zsh > "${fpath[1]}/_nemus"
+# fish
+nemus completion fish > ~/.config/fish/completions/nemus.fish
+```
+
+Workspace names are resolved live (the script calls back into the CLI), so they
+stay current without regenerating.
+
 ### Suites (reusable repo collections)
 
 ```bash
@@ -262,6 +280,23 @@ nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
 nemus snapshot restore <id>   # (sr)
 ```
 
+### Reflect — improve your setup over time
+
+```bash
+nemus reflect                 # (retro) analyze your last 10 workspaces' sessions
+nemus reflect --limit 5       # narrow the window
+nemus reflect --json          # structured report for tooling
+nemus reflect --dry-run       # show what the judge sees, without calling the agent
+```
+
+`reflect` reads your recent agent **session transcripts** (Claude + pi), distills
+the prompts you sent, the failures the agent hit, and the tools it used, then asks
+**your own configured agent** (LLM-as-a-judge — no extra API key) to recommend
+concrete improvements: which **skills** to add and where, missing
+**AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+**prompt/workflow** habits — each with a priority and an example snippet. It's a
+fast retrospective on *how you drive the agent*, so next time works better.
+
 ### AI assistant
 
 ```bash

package/dist/cli/ai-prompt.js

@@ -41,6 +41,7 @@ exports.extractIntent = extractIntent;
 exports.run = run;
 exports.main = main;
 const child_process_1 = require("child_process");
+const agent_judge_1 = require("../utils/agent-judge");
 const util_1 = require("util");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -267,35 +268,22 @@ async function extractIntent(prompt) {
         ];
         result = runExtraction('pi', [...piLean, ...piCore], piCore);
     }
-    // Strip markdown code fences if present (Pi may wrap JSON in ```json...```)
-    let jsonStr = result.trim();
-    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
-    if (fenceMatch) {
-        jsonStr = fenceMatch[1].trim();
-    }
-    const parsed = JSON.parse(jsonStr);
-    // Handle different output formats:
-    // - Claude: { structured_output: {...} } or { result: "..." }
-    // - Pi: may return the object directly or wrap it
+    // Unwrap the agent's reply (code fences + the structured_output / result-string
+    // / result-object / bare-object envelopes) with the shared parser, so this and
+    // the reflect judge can't drift when a new agent shape is learned. The
+    // extraction-specific INVOCATION (lean flags + tailored timeout/auth errors)
+    // deliberately stays here — those messages are part of the `nemus --` UX.
     let intent;
-    if (parsed.structured_output) {
-        intent = parsed.structured_output;
-    }
-    else if (typeof parsed.result === 'string' && parsed.result) {
-        try {
-            intent = JSON.parse(parsed.result);
-        }
-        catch { /* ignore */ }
-    }
-    else if (typeof parsed.result === 'object' && parsed.result !== null) {
-        intent = parsed.result;
+    try {
+        const parsed = (0, agent_judge_1.parseAgentJson)(result);
+        if (parsed && typeof parsed === 'object')
+            intent = parsed;
     }
-    else if (parsed.workspaceName || parsed.repos || parsed.remainingIntent !== undefined) {
-        // Pi may return the extracted object directly
-        intent = parsed;
+    catch {
+        throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
     }
     if (!intent) {
-        throw new Error(`Could not extract intent from agent response. Parsed: ${JSON.stringify(parsed).slice(0, 200)}`);
+        throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
     }
     // Coerce/validate field types so malformed model output can't crash the
     // downstream .trim()/sanitize path (a stringly-typed workspaceName or a

package/dist/commands/completion.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_BINS = void 0;
+exports.generateCompletion = generateCompletion;
+exports.specsFromProgram = specsFromProgram;
+exports.registerCompletionCommand = registerCompletionCommand;
+const workspace_meta_1 = require("../utils/workspace-meta");
+const logger_1 = require("../utils/logger");
+/** Binaries that get completion registered (the CLI's bins). */
+exports.COMPLETION_BINS = ['nemus', 'nem'];
+/** Every token (name + aliases) that should complete as a subcommand. */
+function allTokens(cmds) {
+    return cmds.flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Tokens (names + aliases) of the commands that take a workspace argument. */
+function workspaceTokens(cmds) {
+    return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Escape a description for a fish single-quoted string. */
+function fishDesc(s) {
+    return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
+}
+/**
+ * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
+ * generated script completes subcommands at position 1, and for a subcommand
+ * that takes a workspace it completes workspace names by calling back into the
+ * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
+ * regenerating the script.
+ */
+function generateCompletion(shell, cmds, bins = exports.COMPLETION_BINS) {
+    const commands = allTokens(cmds).join(' ');
+    const wsCommands = workspaceTokens(cmds).join(' ');
+    if (shell === 'bash') {
+        return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
+#   (or: nemus completion bash >> ~/.bashrc)
+_nemus_complete() {
+  local cur bin sub
+  # bash does not clear COMPREPLY between completions; reset so a stale result
+  # from a previous TAB can't leak when we return without setting it.
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  bin="\${COMP_WORDS[0]}"
+  local commands="${commands}"
+  local ws_commands="${wsCommands}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "\$commands" -- "\$cur") )
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    sub="\${COMP_WORDS[1]}"
+    if [[ " \$ws_commands " == *" \$sub "* ]]; then
+      local names
+      names="\$("\$bin" completion --workspaces 2>/dev/null)"
+      COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
+      return 0
+    fi
+  fi
+  return 0
+}
+${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
+`;
+    }
+    if (shell === 'zsh') {
+        // Autoloaded form: save as a file named `_nemus` on your $fpath.
+        return `#compdef ${bins.join(' ')}
+# nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
+local -a _nemus_commands
+_nemus_commands=(${allTokens(cmds).map((t) => `'${t}'`).join(' ')})
+local _nemus_ws_commands="${wsCommands}"
+if (( CURRENT == 2 )); then
+  compadd -- $_nemus_commands
+  return
+fi
+if (( CURRENT == 3 )); then
+  local sub=\${words[2]}
+  if [[ " $_nemus_ws_commands " == *" $sub "* ]]; then
+    local -a _nemus_names
+    _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
+    compadd -- $_nemus_names
+  fi
+fi
+`;
+    }
+    // fish
+    const lines = ['# nemus fish completion. Install: nemus completion fish > ~/.config/fish/completions/nemus.fish'];
+    for (const bin of bins) {
+        lines.push(`complete -c ${bin} -f`);
+        for (const c of cmds) {
+            for (const tok of [c.name, ...c.aliases]) {
+                lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
+            }
+        }
+        const wsToks = workspaceTokens(cmds).join(' ');
+        if (wsToks) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/** Distill the program's top-level commands into CommandSpecs. */
+function specsFromProgram(program) {
+    return program.commands
+        .map((c) => {
+        const args = c.registeredArguments ?? [];
+        const firstArg = args[0]?.name?.();
+        return {
+            name: c.name(),
+            aliases: c.aliases(),
+            takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
+            description: c.description() ?? '',
+        };
+    })
+        // The completion command itself and any hidden helper needn't clutter, but
+        // keeping them is harmless; only drop entries with no name.
+        .filter((s) => s.name);
+}
+function registerCompletionCommand(program) {
+    program
+        .command('completion [shell]')
+        .description('Output a shell completion script (bash|zsh|fish)')
+        .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
+        .action(async (shell, opts) => {
+        // Data helper the generated scripts call back into.
+        if (opts.workspaces) {
+            try {
+                const workspaces = await (0, workspace_meta_1.listWorkspaces)(false);
+                for (const ws of workspaces)
+                    process.stdout.write(ws.name + '\n');
+            }
+            catch {
+                // Silent: completion must never error out the user's shell.
+            }
+            return;
+        }
+        const shells = ['bash', 'zsh', 'fish'];
+        if (!shell || !shells.includes(shell)) {
+            (0, logger_1.logError)(`completion: specify a shell — one of ${shells.join(', ')}`);
+            (0, logger_1.logError)('e.g. nemus completion bash');
+            process.exit(1);
+        }
+        process.stdout.write(generateCompletion(shell, specsFromProgram(program)));
+    });
+}

package/dist/commands/reflect.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReflectCommand = registerReflectCommand;
+const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
+const colors_1 = require("../utils/colors");
+const reflect_1 = require("../utils/reflect");
+const agent_judge_1 = require("../utils/agent-judge");
+function registerReflectCommand(parent) {
+    parent
+        .command('reflect')
+        .alias('retro')
+        .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
+        .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+        .option('--json', 'Output the report as JSON')
+        .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
+        .action(async (opts) => {
+        await handleReflect(opts);
+    });
+}
+async function handleReflect(opts) {
+    const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
+    try {
+        if (!opts.json && !opts.dryRun) {
+            (0, logger_1.logStep)(`Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
+            (0, logger_1.logInfo)('Reading sessions and distilling prompts + failures…');
+        }
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit);
+        const withSessions = corpus.workspaces.filter((w) => w.session).length;
+        const prompt = (0, reflect_1.buildJudgePrompt)(corpus);
+        if (opts.dryRun) {
+            // No LLM call — surface exactly what the judge would see.
+            if (opts.json)
+                (0, output_1.outputJson)({ corpus, prompt });
+            else {
+                process.stdout.write(prompt + '\n');
+            }
+            return;
+        }
+        if (withSessions === 0) {
+            const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+            if (opts.json)
+                (0, output_1.outputJsonError)(msg);
+            else
+                (0, logger_1.logError)(msg);
+            process.exit(1);
+        }
+        if (!opts.json)
+            (0, logger_1.logInfo)(`Judging ${withSessions} session(s) with your configured agent…`);
+        const parsed = (0, agent_judge_1.runAgentJson)(prompt, { schema: reflect_1.REFLECT_SCHEMA });
+        const report = (0, reflect_1.parseReflectionReport)(parsed);
+        if (opts.json) {
+            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+            return;
+        }
+        printReport(report, corpus.workspaces.length, withSessions);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'reflect failed';
+        if (opts.json)
+            (0, output_1.outputJsonError)(msg);
+        else {
+            (0, logger_1.logError)('Failed to analyze sessions');
+            (0, logger_1.logError)(msg);
+        }
+        process.exit(1);
+    }
+}
+const KIND_LABEL = {
+    skill: 'Skill',
+    context: 'Context/AGENTS.md',
+    test: 'Test',
+    prompt: 'Prompt',
+    connectivity: 'Connectivity',
+    workflow: 'Workflow',
+    other: 'Other',
+};
+function priorityBadge(p) {
+    if (p === 'high')
+        return (0, colors_1.colorize)('● high', 'red');
+    if (p === 'medium')
+        return (0, colors_1.colorize)('● med', 'yellow');
+    return (0, colors_1.colorize)('● low', 'gray');
+}
+function printReport(report, workspaces, analyzed) {
+    console.log('');
+    console.log((0, colors_1.colorize)('  Reflection', 'bright') + (0, colors_1.colorize)(`  (${analyzed} sessions across ${workspaces} workspaces)`, 'dim'));
+    console.log((0, colors_1.colorize)('  ' + '─'.repeat(56), 'dim'));
+    if (report.summary) {
+        console.log('\n  ' + report.summary.replace(/\n/g, '\n  '));
+    }
+    if (report.recommendations.length === 0) {
+        console.log('\n  ' + (0, colors_1.colorize)('No specific recommendations — looks solid.', 'green') + '\n');
+        return;
+    }
+    // High priority first.
+    const order = { high: 0, medium: 1, low: 2 };
+    const recs = [...report.recommendations].sort((a, b) => order[a.priority] - order[b.priority]);
+    console.log('');
+    for (const r of recs) {
+        const target = r.target ? (0, colors_1.colorize)(`  [${r.target}]`, 'cyan') : '';
+        console.log(`  ${priorityBadge(r.priority)}  ${(0, colors_1.colorize)(KIND_LABEL[r.kind], 'bright')}  ${r.title}${target}`);
+        if (r.detail)
+            console.log(`      ${r.detail.replace(/\n/g, '\n      ')}`);
+        if (r.example) {
+            console.log((0, colors_1.colorize)('      example:', 'dim'));
+            console.log((0, colors_1.colorize)(r.example.replace(/^/gm, '        '), 'dim'));
+        }
+        console.log('');
+    }
+}

package/dist/program.js

@@ -88,6 +88,8 @@ const ghq_status_1 = require("./commands/ghq-status");
 const save_context_1 = require("./commands/save-context");
 const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
+const completion_1 = require("./commands/completion");
+const reflect_1 = require("./commands/reflect");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -111,6 +113,8 @@ const report_bug_1 = require("./commands/report-bug");
 (0, save_context_1.registerSaveContextCommand)(exports.program);
 (0, migrate_1.registerMigrateCommand)(exports.program);
 (0, report_bug_1.registerReportBugCommand)(exports.program);
+(0, completion_1.registerCompletionCommand)(exports.program);
+(0, reflect_1.registerReflectCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/dist/utils/agent-judge.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentRaw = runAgentRaw;
+exports.runAgentJson = runAgentJson;
+exports.parseAgentJson = parseAgentJson;
+const child_process_1 = require("child_process");
+const agent_config_1 = require("./agent-config");
+const DEFAULT_TIMEOUT_MS = 180000; // judging N transcripts is heavier than extraction
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+ * Invoke the agent with `prompt` and return the raw stdout. Throws a clear error
+ * on timeout / non-zero exit. Kept separate from parsing so callers can inspect
+ * raw output (e.g. `--dry-run`, debugging).
+ */
+function runAgentRaw(prompt, opts = {}) {
+    const agentType = opts.agentType ?? (0, agent_config_1.getPrimaryAgent)().type;
+    const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const exec = opts.exec ??
+        ((cmd, args, o) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
+    const attempt = (cmd, args) => exec(cmd, args, { timeout, maxBuffer });
+    try {
+        if (agentType === 'claude') {
+            const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+            if (opts.schema)
+                preferred.push('--json-schema', opts.schema);
+            try {
+                return attempt('claude', preferred);
+            }
+            catch {
+                // Older claude may reject the newer flags — fall back to the plainest form.
+                return attempt('claude', ['-p', prompt]);
+            }
+        }
+        if (agentType === 'opencode') {
+            return attempt('opencode', ['run', prompt]);
+        }
+        // pi (and any other): run as lean as possible so a bloated env can't hang it.
+        const piLean = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-tools', '--no-session'];
+        try {
+            return attempt('pi', [...piLean, '-p', prompt]);
+        }
+        catch {
+            return attempt('pi', ['-p', prompt]);
+        }
+    }
+    catch (err) {
+        const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
+        throw new Error(`agent judge failed (${agentType}): ${detail}`);
+    }
+}
+/**
+ * Run the agent and parse its reply as JSON, tolerating the shapes different
+ * agents emit: `{ structured_output }`, `{ result: "<json>" }`, a ```json fence,
+ * or a bare object. Returns `unknown`; callers validate/normalize their shape.
+ */
+function runAgentJson(prompt, opts = {}) {
+    const raw = runAgentRaw(prompt, opts);
+    return parseAgentJson(raw);
+}
+/** Extract a JSON object from an agent's raw stdout. Exported for tests. */
+function parseAgentJson(raw) {
+    let text = raw.trim();
+    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (fence)
+        text = fence[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Last resort: grab the outermost {...} span.
+        const span = text.match(/\{[\s\S]*\}/);
+        if (!span)
+            throw new Error('agent did not return JSON');
+        parsed = JSON.parse(span[0]);
+    }
+    // Unwrap the common agent envelopes.
+    if (parsed && typeof parsed === 'object') {
+        if (parsed.structured_output && typeof parsed.structured_output === 'object')
+            return parsed.structured_output;
+        if (typeof parsed.result === 'string') {
+            try {
+                return JSON.parse(parsed.result);
+            }
+            catch {
+                /* fall through — result was plain text, return the envelope */
+            }
+        }
+        if (parsed.result && typeof parsed.result === 'object')
+            return parsed.result;
+    }
+    return parsed;
+}