codeep 2.6.0 → 2.8.0

package/README.md

@@ -217,12 +217,32 @@ AI-powered review of your git diff with `/review`:
 
 If there are no git changes, falls back to static analysis automatically.
 
-#### Custom rules (`.codeep/review.json`)
+#### Custom rules (`.codeep/review.yml` or `.codeep/review.json`)
 
 The static reviewer (`codeep review` / `/review --static`) ships a set of
-built-in rules, but a project can tailor them — check a `.codeep/review.json`
-into the repo and the CLI **and** the [Codeep GitHub Action](https://github.com/VladoIvankovic/codeep-action)
-both pick it up automatically (zero LLM cost):
+built-in rules, but a project can tailor them — check a `.codeep/review.yml`
+(or `.codeep/review.json`) into the repo and the CLI **and** the
+[Codeep GitHub Action](https://github.com/VladoIvankovic/codeep-action) both
+pick it up automatically (zero LLM cost). YAML is preferred when present and is
+nicer for regexes — single-quoted YAML keeps backslashes literal
+(`pattern: '\bfoo\('`) so you avoid JSON's double-escaping:
+
+```yaml
+# .codeep/review.yml
+rules:
+  - id: no-internal-import
+    pattern: "from ['\"]@acme/internal"
+    category: best-practice
+    severity: error
+    message: Don't import from @acme/internal outside the platform team
+    suggestion: Use the public @acme/sdk package
+    extensions: [.ts, .tsx]
+disable: [todo-comment, anonymous-function]
+include: ['src/**']
+exclude: ['**/*.test.ts', 'vendor/**']
+```
+
+The same config as JSON:
 
 ```json
 {
@@ -246,14 +266,28 @@ both pick it up automatically (zero LLM cost):
 - **`rules`** — your own checks. `id`, `pattern` (a regex string), and `message`
   are required; `flags` (default `g`), `category`, `severity`
   (`error|warning|info|suggestion`), `suggestion`, and `extensions` are optional.
-- **`disable`** — turn off built-in rules by id (e.g. `eval-usage`,
-  `hardcoded-password`, `todo-comment`, `any-type`, `console-statement`,
-  `long-file`, `long-function`, …).
+- **`disable`** — turn off built-in rules by id. Run `codeep review --rules` for
+  the live list; the built-in ids are: `eval-usage`, `inner-html`,
+  `dangerously-set-inner-html`, `hardcoded-password`, `hardcoded-api-key`,
+  `foreach-await`, `await-in-loop`, `select-star`, `loose-null-check`,
+  `empty-catch`, `console-statement`, `todo-comment`, `any-type`, `ts-ignore`,
+  `as-any`, `var-usage`, `anonymous-function`, `missing-jsdoc`, `long-file`,
+  `long-function`.
 - **`include` / `exclude`** — glob scoping (`**`, `*`, `?`); `include` empty = all files.
 
 A missing, malformed, or partially-invalid config never breaks a review — bad
 entries are skipped and the run proceeds with whatever is valid.
 
+**More review commands:**
+- `codeep review --rules` — list the built-in rule ids (above) and exit.
+- `codeep review --ai` — after the offline pass, get an advisory AI second
+  opinion on the working-tree diff from your configured provider (needs an API
+  key; never changes the exit code, so CI stays deterministic).
+- `codeep hook install` — install a git pre-commit hook that reviews the
+  working-tree content of your staged files and blocks the commit on failures
+  (`--pre-push` for pre-push, `--fail-on <level>` to set the threshold,
+  `codeep hook uninstall` to remove). Stage changes fully before committing.
+
 ### Interactive Mode
 Agent asks clarifying questions when tasks are ambiguous:
 ```

package/dist/acp/commands.js

@@ -1443,6 +1443,7 @@ function buildHelp() {
         '| `/login <provider> <key>` | Set API key for a provider |',
         '| `/apikey [key]` | Show or set API key |',
         '| `/telemetry [on\\|off]` | Show or toggle automatic cloud telemetry |',
+        '| `/keysync [on\\|off]` | Show or toggle syncing API keys to codeep.dev |',
         '| `/lang [code]` | Set response language (`en`, `hr`, `auto`…) |',
         '| `/grant` | Grant write access for workspace |',
         '',

package/dist/acp/server.js

@@ -973,11 +973,10 @@ export function startAcpServer() {
             });
         };
         resetTokenTracking();
-        // In manual mode, confirm write/edit operations
-        const prevConfirmWrite = config.get('agentConfirmWriteFile');
-        if (session.currentModeId === 'manual') {
-            config.set('agentConfirmWriteFile', true);
-        }
+        // Manual mode gates write/edit for THIS run via a per-call option passed to
+        // runAgentSession (extraDangerousTools, below) — NOT by mutating the global
+        // `agentConfirmWriteFile` config, which leaked the session's mode into the
+        // TUI/other processes and raced on a non-atomic restore.
         const agentResponseChunks = [];
         const sendChunk = (text) => {
             agentResponseChunks.push(text);
@@ -1083,6 +1082,9 @@ export function startAcpServer() {
                         }
                     }
                 },
+                // Manual mode gates write_file/edit_file for this run only (per-call,
+                // no global config mutation).
+                extraDangerousTools: session.currentModeId === 'manual' ? ['write_file', 'edit_file'] : undefined,
                 // Only request permission in Manual mode
                 onRequestPermission: session.currentModeId === 'manual'
                     ? async (toolCall) => {
@@ -1183,7 +1185,6 @@ export function startAcpServer() {
                 if (agentResponse) {
                     session.history.push({ role: 'assistant', content: agentResponse });
                 }
-                config.set('agentConfirmWriteFile', prevConfirmWrite);
                 autoSaveSession(session.history, session.workspaceRoot);
                 // Report token usage to dashboard
                 const projectCtx = getProjectContext(session.workspaceRoot);
@@ -1247,7 +1248,6 @@ export function startAcpServer() {
                     transport.error(msg.id, -32000, err.message);
                 }
             }).finally(() => {
-                config.set('agentConfirmWriteFile', prevConfirmWrite);
                 if (session)
                     session.abortController = null;
                 planEntries.clear();

package/dist/acp/session.d.ts

@@ -11,6 +11,8 @@ export interface AgentSessionOptions {
     onThought?: (text: string) => void;
     onToolCall?: (toolCallId: string, toolName: string, kind: string, title: string, status: 'pending' | 'running' | 'finished' | 'error', locations?: string[], rawOutput?: string) => void;
     onRequestPermission?: (toolCall: ToolCall) => Promise<PermissionOutcome>;
+    /** Tools to force into the per-run dangerous set (ACP manual mode). */
+    extraDangerousTools?: string[];
     onExecuteCommand?: (command: string, args: string[], cwd: string) => Promise<{
         stdout: string;
         stderr: string;

package/dist/acp/session.js

@@ -145,6 +145,7 @@ export async function runAgentSession(opts) {
             }
         },
         onRequestPermission: opts.onRequestPermission,
+        extraDangerousTools: opts.extraDangerousTools,
         onExecuteCommand: opts.onExecuteCommand,
         fs: opts.fs,
         // Route MCP-prefixed tool calls through the per-session registry.

package/dist/config/index.d.ts

@@ -96,10 +96,20 @@ interface ConfigSchema {
     /** True once legacy plaintext keys (providerApiKeys / apiKey) have been
      *  migrated into secure storage and wiped from the config file. */
     keysSecured: boolean;
+    /** Plaintext fallback key map used by utils/keychain.ts ONLY when the OS
+     *  keychain is unavailable. Swept into the keychain once it becomes available
+     *  (see sweepFallbackKeysToKeychain). Empty {} on keychain-capable systems. */
+    apiKeys?: Record<string, string>;
     /** Master switch for automatic cloud uploads (usage stats, session
      *  transcripts, progress, memory notes). Default true; set false to opt out.
      *  The CODEEP_NO_TELEMETRY / DO_NOT_TRACK env vars also force it off. */
     telemetry: boolean;
+    /** Opt-in to syncing API keys to codeep.dev (`codeep account push`/`sync`).
+     *  OFF by default — keys live only in the OS keychain unless you enable this.
+     *  Synced keys are stored server-readable (AES from a server-held secret), so
+     *  this is an explicit consent switch. Enable via `/keysync on` or Settings;
+     *  the CODEEP_NO_KEY_SYNC env var forces it off (org-policy hard switch). */
+    syncKeysToCloud: boolean;
     githubId: string;
     githubUsername: string;
     syncToken: string;
@@ -172,6 +182,13 @@ export declare function isTelemetryEnabled(): boolean;
  * the /telemetry command explain why a toggle had no effect.
  */
 export declare function telemetryForcedOffByEnv(): boolean;
+export declare function isKeySyncEnabled(): boolean;
+/**
+ * True when CODEEP_NO_KEY_SYNC is forcing key sync off — so the `syncKeysToCloud`
+ * flag can't turn it back on. Lets the /keysync command explain why a toggle had
+ * no effect.
+ */
+export declare function keySyncForcedOffByEnv(): boolean;
 /**
  * Clear API key for a specific provider
  */

package/dist/config/index.js

@@ -186,7 +186,9 @@ function createConfig() {
         providerApiKeys: [],
         configuredProviderIds: [],
         keysSecured: false,
+        apiKeys: {},
         telemetry: true,
+        syncKeysToCloud: false,
         githubId: '',
         githubUsername: '',
         syncToken: '',
@@ -359,6 +361,44 @@ async function migrateKeysToSecureStorage() {
         _migrationPromise = null;
     }
 }
+let _sweepPromise = null;
+/**
+ * If the OS keychain is now available but API keys are still sitting in the
+ * plaintext `apiKeys` fallback map (written by utils/keychain.ts while the
+ * keychain was unavailable on a prior run), move each into the keychain. The
+ * keychain write also deletes the entry from the plaintext fallback map, so a
+ * successful sweep leaves no plaintext behind. Cheap no-op when the map is
+ * empty or the keychain is unavailable; deduped for concurrent callers. Runs
+ * independently of `keysSecured` so a key written during a keychain outage is
+ * still swept up later.
+ */
+async function sweepFallbackKeysToKeychain() {
+    if (!_sweepPromise) {
+        _sweepPromise = (async () => {
+            const store = secureKeyStore();
+            // Only sweep when the keychain is actually usable; otherwise leave the
+            // plaintext fallback in place (there's nowhere safer to move it).
+            if (!store.isKeychainAvailable || !(await store.isKeychainAvailable()))
+                return;
+            const plaintext = config.get('apiKeys') || {};
+            for (const [providerId, apiKey] of Object.entries(plaintext)) {
+                if (typeof apiKey !== 'string' || !apiKey)
+                    continue;
+                try {
+                    await store.setApiKey(providerId, apiKey); // writes keychain + deletes from fallback map
+                    addConfiguredProviderId(providerId);
+                }
+                catch { /* keep the plaintext entry on failure — never lose a key */ }
+            }
+        })();
+    }
+    try {
+        await _sweepPromise;
+    }
+    finally {
+        _sweepPromise = null;
+    }
+}
 export const LANGUAGES = {
     'auto': 'Auto-detect',
     'en': 'English',
@@ -417,9 +457,11 @@ export async function loadApiKey(providerId) {
  * Should be called at app startup
  */
 export async function loadAllApiKeys() {
-    // Migrate any legacy plaintext keys, then load all from secure storage using
-    // the non-secret configuredProviderIds index (no need to probe every provider).
+    // Migrate any legacy plaintext keys, then sweep any keychain-fallback plaintext
+    // up into the keychain (no-op when none / keychain unavailable), then load all
+    // from secure storage using the non-secret configuredProviderIds index.
     await migrateKeysToSecureStorage();
+    await sweepFallbackKeysToKeychain();
     const store = secureKeyStore();
     for (const providerId of (config.get('configuredProviderIds') || [])) {
         const key = await store.getApiKey(providerId);
@@ -509,6 +551,30 @@ export function isTelemetryEnabled() {
 export function telemetryForcedOffByEnv() {
     return envForcesTelemetryOff();
 }
+/**
+ * Whether syncing API keys to the cloud is allowed. OFF by default (opt-in):
+ * unlike telemetry, this also gates the EXPLICIT `codeep account push` and the
+ * key-download half of `account sync`, because pushing a key stores it
+ * server-readable. The CODEEP_NO_KEY_SYNC env var forces it off as an
+ * org-policy hard switch the config flag can't override.
+ */
+function envForcesKeySyncOff() {
+    const off = (v) => !!v && !/^(0|false|no|off)$/i.test(v.trim());
+    return off(process.env.CODEEP_NO_KEY_SYNC);
+}
+export function isKeySyncEnabled() {
+    if (envForcesKeySyncOff())
+        return false;
+    return config.get('syncKeysToCloud') === true; // default OFF — must be explicitly true
+}
+/**
+ * True when CODEEP_NO_KEY_SYNC is forcing key sync off — so the `syncKeysToCloud`
+ * flag can't turn it back on. Lets the /keysync command explain why a toggle had
+ * no effect.
+ */
+export function keySyncForcedOffByEnv() {
+    return envForcesKeySyncOff();
+}
 /**
  * Clear API key for a specific provider
  */

package/dist/renderer/App.js

@@ -83,6 +83,7 @@ const COMMAND_DESCRIPTIONS = {
     'tasks': 'Show pending tasks from codeep.dev dashboard',
     'sync': 'Sync learning preferences and profiles to codeep.dev',
     'telemetry': 'Show or toggle automatic cloud telemetry (on/off)',
+    'keysync': 'Show or toggle syncing API keys to codeep.dev (on/off)',
     // 2.0 — surfaced for `/` autocomplete; documented in /help too.
     'compact': 'Summarize older messages to free up context',
     'commands': 'List custom slash commands in .codeep/commands/*.md',

package/dist/renderer/commands.js

@@ -5,7 +5,7 @@
  * decoupled from global state. Import-heavy commands use dynamic imports
  * to keep startup time low.
  */
-import { config, getCurrentProvider, getModelsForCurrentProvider, PROTOCOLS, LANGUAGES, setProvider, setApiKey, clearApiKey, getApiKey, isTelemetryEnabled, telemetryForcedOffByEnv, saveSession, startNewSession, loadSession, listSessionsWithInfo, deleteSession, renameSession, setProjectPermission, saveProfile, loadProfile, applyProfile, listProfiles, deleteProfile, initializeAsProject, isManuallyInitializedProject, } from '../config/index.js';
+import { config, getCurrentProvider, getModelsForCurrentProvider, PROTOCOLS, LANGUAGES, setProvider, setApiKey, clearApiKey, getApiKey, isTelemetryEnabled, telemetryForcedOffByEnv, isKeySyncEnabled, keySyncForcedOffByEnv, saveSession, startNewSession, loadSession, listSessionsWithInfo, deleteSession, renameSession, setProjectPermission, saveProfile, loadProfile, applyProfile, listProfiles, deleteProfile, initializeAsProject, isManuallyInitializedProject, } from '../config/index.js';
 import { getProjectContext } from '../utils/project.js';
 import { getCurrentVersion } from '../utils/update.js';
 import { getProviderList, getProvider } from '../config/providers.js';
@@ -274,6 +274,35 @@ export async function handleCommand(command, args, ctx) {
             ctx.app.addMessage({ role: 'system', content: tLines.join('\n') });
             break;
         }
+        case 'keysync': {
+            const sub = args[0]?.toLowerCase();
+            const envOff = keySyncForcedOffByEnv();
+            if (sub === 'on' || sub === 'off') {
+                if (envOff) {
+                    ctx.app.notify('Cloud key sync is forced OFF by CODEEP_NO_KEY_SYNC — unset that env var to change it.');
+                    break;
+                }
+                config.set('syncKeysToCloud', sub === 'on');
+                ctx.app.notify(sub === 'on'
+                    ? 'Cloud key sync on — `codeep account push/sync` will now upload/download API keys. Note: synced keys are stored server-readable on codeep.dev.'
+                    : 'Cloud key sync off — API keys stay in your OS keychain only. (Run `codeep account purge-keys` to also wipe any keys already on the server.)');
+                break;
+            }
+            if (sub && sub !== 'status') {
+                ctx.app.notify('Usage: /keysync · /keysync on · /keysync off');
+                break;
+            }
+            const flag = config.get('syncKeysToCloud') === true;
+            const kLines = ['## Cloud key sync', ''];
+            kLines.push(`**State**      ${isKeySyncEnabled() ? 'on' : 'off'}`);
+            kLines.push(`**Flag**       syncKeysToCloud = ${flag}`);
+            if (envOff)
+                kLines.push('**Env**        forced off by CODEEP_NO_KEY_SYNC (overrides the flag)');
+            kLines.push('');
+            kLines.push('OFF by default. API keys live only in your OS keychain unless you turn this on. When on, `codeep account push`/`sync` upload/download keys, which are stored **server-readable** on codeep.dev. Toggle with `/keysync on` or `/keysync off`; wipe server copies with `codeep account purge-keys`.');
+            ctx.app.addMessage({ role: 'system', content: kLines.join('\n') });
+            break;
+        }
         case 'grant': {
             setProjectPermission(ctx.projectPath, true, true);
             ctx.setHasWriteAccess(true);

package/dist/renderer/components/Settings.js

@@ -250,6 +250,16 @@ export const SETTINGS = [
             { value: false, label: 'Off' },
         ],
     },
+    {
+        key: 'syncKeysToCloud',
+        label: 'Sync API Keys to Cloud (server-readable)',
+        getValue: () => config.get('syncKeysToCloud') === true,
+        type: 'select',
+        options: [
+            { value: false, label: 'Off (keychain only)' },
+            { value: true, label: 'On (push/sync to codeep.dev)' },
+        ],
+    },
 ];
 /**
  * Format value for display

package/dist/renderer/main.js

@@ -387,7 +387,11 @@ async function main() {
     // the review usage rather than the top-level help.
     if (args[0] === 'review') {
         const { runHeadlessReview } = await import('../utils/headlessReview.js');
-        process.exit(runHeadlessReview(args.slice(1)));
+        process.exit(await runHeadlessReview(args.slice(1)));
+    }
+    if (args[0] === 'hook') {
+        const { runHookCommand } = await import('../utils/gitHookInstaller.js');
+        process.exit(runHookCommand(args.slice(1)));
     }
     if (args.includes('--version') || args.includes('-v')) {
         console.log(`Codeep v${getCurrentVersion()}`);
@@ -400,10 +404,13 @@ Codeep - AI-powered coding assistant TUI
 Usage:
   codeep              Start interactive chat
   codeep account        Link CLI to your codeep.dev dashboard
-  codeep account sync   Pull keys + personalities + commands + profile from codeep.dev
-  codeep account push   Push local keys + personalities + commands + profile to codeep.dev
+  codeep account sync   Pull personalities + commands + profile (+ keys if cloud key sync is on)
+  codeep account push   Push personalities + commands + profile (+ keys if cloud key sync is on)
+  codeep account purge-keys  Delete all your API keys stored on codeep.dev (cloud only; local keychain untouched)
   codeep acp          Start ACP server (for Zed editor integration)
-  codeep review       Offline code review for CI (--json, --fail-on <level>)
+  codeep review       Offline code review for CI (--json, --fail-on, --rules, --ai)
+  codeep hook install   Install a git pre-commit hook running \`codeep review\`
+  codeep hook uninstall Remove the Codeep git hook
   codeep --version    Show version
   codeep --help       Show this help
 
@@ -419,9 +426,7 @@ Commands (in chat):
     if (args[0] === 'account') {
         const sub = args[1];
         if (sub === 'sync' || sub === 'pull') {
-            // Pull API keys from codeep.dev and save to local config
-            const { pullKeys } = await import('../utils/codeepCloud.js');
-            const { getSyncToken, setApiKey, loadAllApiKeys: loadKeys } = await import('../config/index.js');
+            const { getSyncToken, setApiKey, loadAllApiKeys: loadKeys, isKeySyncEnabled } = await import('../config/index.js');
             if (!getSyncToken()) {
                 console.log('\n  Not linked to codeep.dev. Run: codeep account\n');
                 process.exit(1);
@@ -430,28 +435,36 @@ Commands (in chat):
             // key. Otherwise the first setApiKey flips keysSecured=true and any local
             // legacy plaintext keys would never migrate (orphaned, invisible).
             await loadKeys();
-            process.stdout.write('  Pulling keys from codeep.dev...');
-            const keys = await pullKeys();
-            if (!keys) {
-                console.log(' failed.\n  Check your connection or re-link with: codeep account\n');
-                process.exit(1);
-            }
-            const count = Object.keys(keys).length;
-            if (count === 0) {
-                console.log(' no keys found.\n  Add keys at codeep.dev/dashboard');
-            }
-            else {
-                let synced = 0;
-                for (const [provider, key] of Object.entries(keys)) {
-                    try {
-                        await setApiKey(key, provider);
-                        synced++;
-                    }
-                    catch {
-                        console.log(`\n  Warning: could not securely store the key for ${provider}.`);
+            // API keys are opt-in (default OFF). Pull them only when cloud key sync is
+            // enabled; the personal config below always syncs (no secrets).
+            if (isKeySyncEnabled()) {
+                const { pullKeys } = await import('../utils/codeepCloud.js');
+                process.stdout.write('  Pulling keys from codeep.dev...');
+                const keys = await pullKeys();
+                if (!keys) {
+                    console.log(' failed.\n  Check your connection or re-link with: codeep account\n');
+                    process.exit(1);
+                }
+                const count = Object.keys(keys).length;
+                if (count === 0) {
+                    console.log(' no keys found.\n  Add keys at codeep.dev/dashboard');
+                }
+                else {
+                    let synced = 0;
+                    for (const [provider, key] of Object.entries(keys)) {
+                        try {
+                            await setApiKey(key, provider);
+                            synced++;
+                        }
+                        catch {
+                            console.log(`\n  Warning: could not securely store the key for ${provider}.`);
+                        }
                     }
+                    console.log(` synced ${synced} key${synced !== 1 ? 's' : ''}.`);
                 }
-                console.log(` synced ${synced} key${synced !== 1 ? 's' : ''}.`);
+            }
+            else {
+                console.log('  Cloud key sync is off — skipping API keys. Enable with: /keysync on');
             }
             // Also pull portable personal config — personalities + custom commands +
             // the user profile. Additive merge (never clobbers local files).
@@ -472,29 +485,38 @@ Commands (in chat):
             process.exit(0);
         }
         if (sub === 'push') {
-            // Push local API keys to codeep.dev
-            const { pushKeys } = await import('../utils/codeepCloud.js');
-            const { getSyncToken, getApiKey } = await import('../config/index.js');
-            const { PROVIDERS } = await import('../config/providers.js');
+            const { getSyncToken, getApiKey, isKeySyncEnabled } = await import('../config/index.js');
             if (!getSyncToken()) {
                 console.log('\n  Not linked to codeep.dev. Run: codeep account\n');
                 process.exit(1);
             }
-            await loadAllApiKeys();
-            const keys = {};
-            for (const providerId of Object.keys(PROVIDERS)) {
-                const key = getApiKey(providerId);
-                if (key)
-                    keys[providerId] = key;
-            }
-            const count = Object.keys(keys).length;
-            if (count === 0) {
-                console.log('\n  No local API keys to push.\n');
-                process.exit(0);
-            }
-            process.stdout.write(`  Pushing ${count} key${count !== 1 ? 's' : ''} to codeep.dev...`);
-            const ok = await pushKeys(keys);
-            console.log(ok ? ' done.' : ' failed.');
+            // API keys are opt-in (default OFF). Push them only when cloud key sync is
+            // enabled; the personal config below always pushes (no secrets).
+            let keyPushFailed = false;
+            if (isKeySyncEnabled()) {
+                const { pushKeys } = await import('../utils/codeepCloud.js');
+                const { PROVIDERS } = await import('../config/providers.js');
+                await loadAllApiKeys();
+                const keys = {};
+                for (const providerId of Object.keys(PROVIDERS)) {
+                    const key = getApiKey(providerId);
+                    if (key)
+                        keys[providerId] = key;
+                }
+                const count = Object.keys(keys).length;
+                if (count === 0) {
+                    console.log('  No local API keys to push.');
+                }
+                else {
+                    process.stdout.write(`  Pushing ${count} key${count !== 1 ? 's' : ''} to codeep.dev...`);
+                    const ok = await pushKeys(keys);
+                    console.log(ok ? ' done.' : ' failed.');
+                    keyPushFailed = !ok;
+                }
+            }
+            else {
+                console.log('  Cloud key sync is off — skipping API keys. Enable with: /keysync on');
+            }
             // Also push portable personal config — personalities + commands + profile.
             const { pushPersonalities, pushCommands, pushUserProfile } = await import('../utils/codeepCloud.js');
             const pCount = await pushPersonalities();
@@ -509,6 +531,19 @@ Commands (in chat):
                 console.log('  Pushed your profile (about you).');
             }
             console.log('');
+            process.exit(keyPushFailed ? 1 : 0);
+        }
+        if (sub === 'purge-keys') {
+            const { getSyncToken } = await import('../config/index.js');
+            if (!getSyncToken()) {
+                console.log('\n  Not linked to codeep.dev. Run: codeep account\n');
+                process.exit(1);
+            }
+            const { purgeKeys } = await import('../utils/codeepCloud.js');
+            process.stdout.write('  Deleting all your API keys from codeep.dev...');
+            const ok = await purgeKeys();
+            console.log(ok ? ' done. (Local keychain keys are untouched.)' : ' failed.');
+            console.log('');
             process.exit(ok ? 0 : 1);
         }
         const { runAccountFlow } = await import('../utils/codeepCloud.js');

package/dist/utils/agent.d.ts

@@ -22,6 +22,14 @@ export type PermissionDecision = 'allow-once' | 'allow-always' | 'deny-once' | '
  * invariant is unit-tested independently of the agent loop.
  */
 export declare function classifyPermissionOutcome(outcome: string | undefined | null): PermissionDecision;
+/**
+ * Build the set of tools that require a permission prompt this run. Derived from
+ * the global agentConfirm* settings, plus any `extra` tools forced in for this
+ * run only (ACP manual mode passes ['write_file','edit_file'] this way instead
+ * of mutating the global `agentConfirmWriteFile` config — which would leak the
+ * session's mode into the TUI and race on restore). Exported for unit testing.
+ */
+export declare function buildDangerousTools(extra?: string[]): Set<string>;
 export interface AgentOptions {
     maxIterations: number;
     maxDuration: number;
@@ -34,6 +42,10 @@ export interface AgentOptions {
     onTaskPlan?: (plan: TaskPlan) => void;
     onTaskUpdate?: (task: SubTask) => void;
     onRequestPermission?: (toolCall: ToolCall) => Promise<PermissionOutcome>;
+    /** Tool names to force into the per-run dangerous set, on top of the global
+     *  agentConfirm* settings. ACP manual mode passes ['write_file','edit_file']
+     *  here to gate them for THIS run only, instead of mutating global config. */
+    extraDangerousTools?: string[];
     onExecuteCommand?: (command: string, args: string[], cwd: string) => Promise<{
         stdout: string;
         stderr: string;

package/dist/utils/agent.js

@@ -119,6 +119,23 @@ export function classifyPermissionOutcome(outcome) {
         return 'deny-always';
     return 'deny-once'; // 'reject_once' OR anything unexpected → fail closed
 }
+/**
+ * Build the set of tools that require a permission prompt this run. Derived from
+ * the global agentConfirm* settings, plus any `extra` tools forced in for this
+ * run only (ACP manual mode passes ['write_file','edit_file'] this way instead
+ * of mutating the global `agentConfirmWriteFile` config — which would leak the
+ * session's mode into the TUI and race on restore). Exported for unit testing.
+ */
+export function buildDangerousTools(extra = []) {
+    const tools = new Set([
+        ...(config.get('agentConfirmDeleteFile') !== false ? ['delete_file'] : []),
+        ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
+        ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
+    ]);
+    for (const t of extra)
+        tools.add(t);
+    return tools;
+}
 /**
  * Build the result for a run that paused at a safety limit. Pausing is a normal,
  * resumable state — not an error — so the summary tells the user how to resume.
@@ -384,11 +401,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     // Track tools permanently rejected this session via reject_always
     const alwaysRejectedTools = new Set();
     // Tools that require permission when onRequestPermission is set (configurable)
-    const dangerousTools = new Set([
-        ...(config.get('agentConfirmDeleteFile') !== false ? ['delete_file'] : []),
-        ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
-        ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
-    ]);
+    const dangerousTools = buildDangerousTools(opts.extraDangerousTools);
     // Delegation handler: run a named (or generic) sub-agent in its own fresh
     // context and return its summary as the tool result. Reachable only when the
     // `delegate` tool was advertised (depth 0). The sub-agent runs nested (no own

package/dist/utils/codeReview.d.ts

@@ -54,3 +54,24 @@ export declare function formatReviewResult(result: ReviewResult): string;
  * Get review prompt for AI-enhanced review
  */
 export declare function getReviewSystemPrompt(result: ReviewResult): string;
+export interface BuiltinRuleInfo {
+    id: string;
+    category: ReviewCategory;
+    severity: ReviewIssue['severity'];
+    description: string;
+}
+/**
+ * Built-in rule metadata (id + what each flags) — the ids that
+ * `.codeep/review.{json,yml}` "disable" accepts. Includes the two line-count
+ * heuristics (long-file / long-function) that live outside CODE_PATTERNS.
+ */
+export declare function listBuiltinRules(): BuiltinRuleInfo[];
+/**
+ * Append an advisory "AI second opinion" section to a markdown review report.
+ * Advisory only — it never changes the score or the exit code; the deterministic
+ * review remains authoritative.
+ */
+export declare function appendAiSection(markdown: string, aiText: string | null, meta?: {
+    provider?: string;
+    model?: string;
+}): string;

package/dist/utils/codeReview.js

@@ -462,3 +462,34 @@ ${formatReviewResult(result)}
 
 Be concise and practical. Focus on issues that matter most for code quality and maintainability.`;
 }
+/**
+ * Built-in rule metadata (id + what each flags) — the ids that
+ * `.codeep/review.{json,yml}` "disable" accepts. Includes the two line-count
+ * heuristics (long-file / long-function) that live outside CODE_PATTERNS.
+ */
+export function listBuiltinRules() {
+    return [
+        ...CODE_PATTERNS.map((p) => ({
+            id: p.id,
+            category: p.category,
+            severity: p.severity,
+            description: p.message,
+        })),
+        { id: 'long-file', category: 'maintainability', severity: 'info', description: 'File exceeds 500 lines — consider splitting into smaller modules' },
+        { id: 'long-function', category: 'maintainability', severity: 'info', description: 'Function exceeds 50 lines — consider breaking it down' },
+    ];
+}
+/**
+ * Append an advisory "AI second opinion" section to a markdown review report.
+ * Advisory only — it never changes the score or the exit code; the deterministic
+ * review remains authoritative.
+ */
+export function appendAiSection(markdown, aiText, meta = {}) {
+    const label = meta.model
+        ? `${meta.model}${meta.provider ? ` via ${meta.provider}` : ''}`
+        : (meta.provider || 'your provider');
+    if (!aiText || !aiText.trim()) {
+        return `${markdown}\n\n## AI Second Opinion\n_Skipped — no response from ${label}._`;
+    }
+    return `${markdown}\n\n## AI Second Opinion (${label})\n_Advisory — does not affect the score or exit code; the deterministic review above is authoritative._\n\n${aiText.trim()}`;
+}

package/dist/utils/codeepCloud.d.ts

@@ -65,6 +65,12 @@ export declare function pullKeys(): Promise<Record<string, string> | null>;
  * Returns true on success.
  */
 export declare function pushKeys(keys: Record<string, string>): Promise<boolean>;
+/**
+ * Purge ALL of the user's API keys stored on codeep.dev (cloud-only — local
+ * keychain keys are untouched). A clean exit for anyone who synced keys and
+ * later wants them off the server. Returns true on success.
+ */
+export declare function purgeKeys(): Promise<boolean>;
 export declare const pullPersonalities: () => Promise<number | null>;
 export declare const pushPersonalities: () => Promise<number | null>;
 export declare const pullCommands: () => Promise<number | null>;

package/dist/utils/codeepCloud.js

@@ -221,6 +221,22 @@ export async function pushKeys(keys) {
     });
     return res?.ok ?? false;
 }
+/**
+ * Purge ALL of the user's API keys stored on codeep.dev (cloud-only — local
+ * keychain keys are untouched). A clean exit for anyone who synced keys and
+ * later wants them off the server. Returns true on success.
+ */
+export async function purgeKeys() {
+    const syncToken = getSyncToken();
+    if (!syncToken)
+        return false;
+    const res = await fetchWithRetry(`${API_BASE}/api/keys`, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json', 'x-sync-token': syncToken },
+        body: JSON.stringify({ all: true }),
+    });
+    return res?.ok ?? false;
+}
 // ─── Portable personal config sync (personalities + commands) ──────────────────
 //
 // Both are name → raw-.md-body bundles stored in a global dir

package/dist/utils/gitHookInstaller.d.ts

@@ -0,0 +1,26 @@
+import type { FailOn } from './headlessReview.js';
+export type HookType = 'pre-commit' | 'pre-push';
+export type HookAction = 'install' | 'uninstall' | 'help';
+export interface HookArgs {
+    action: HookAction;
+    hookType: HookType;
+    failOn: FailOn;
+    help: boolean;
+}
+export declare const HOOK_HELP = "Usage: codeep hook <install|uninstall> [options]\n\nInstall a git hook that runs `codeep review` on your changes, blocking the\ncommit/push when issues at/above the threshold are found. Honors a project's\n.codeep/review.yml (or .json).\n\nActions:\n  install      Install the hook (pre-commit by default)\n  uninstall    Remove the Codeep-managed hook\n\nOptions:\n  --pre-push          Manage the pre-push hook instead of pre-commit\n  --fail-on <level>   Severity that blocks: error | warning | info | none (default: error)\n  -h, --help          Show this help\n\nThe pre-commit hook reviews the working-tree content of staged files, so stage\nyour changes fully before committing for the most accurate result.\nCodeep never overwrites a pre-existing hook it didn't create.";
+/** Parse argv after `hook`. Pure. */
+export declare function parseHookArgs(argv: string[]): HookArgs;
+/** The hook script body. Pure. pre-commit scopes to staged files; pre-push reviews changes. */
+export declare function buildHookScript(hookType: HookType, failOn: FailOn): string;
+/** True when a hook file was created by Codeep (safe to overwrite/remove). */
+export declare function isCodeepHook(content: string): boolean;
+/** Resolve the git hooks directory (honors worktrees + core.hooksPath). Null if not a repo. */
+export declare function resolveHooksDir(cwd: string): string | null;
+export interface HookDeps {
+    resolveHooksDir: (cwd: string) => string | null;
+    readHook: (path: string) => string | null;
+    writeHook: (path: string, content: string) => void;
+    removeHook: (path: string) => void;
+    write: (text: string) => void;
+}
+export declare function runHookCommand(argv: string[], deps?: HookDeps): number;

package/dist/utils/gitHookInstaller.js

@@ -0,0 +1,168 @@
+// `codeep hook install|uninstall` — installs a GIT hook (pre-commit / pre-push)
+// that runs the offline reviewer on your changes and blocks the commit/push when
+// issues at/above the threshold are found. Honors .codeep/review.{yml,json}.
+//
+// This is a GIT-hook installer — distinct from the lifecycle SHELL hooks in
+// utils/hooks.ts (.codeep/hooks/<event>.sh) and the React hook in src/hooks/.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from 'fs';
+import { join, dirname, isAbsolute } from 'path';
+import { execSync } from 'child_process';
+const FAIL_ON_VALUES = ['error', 'warning', 'info', 'none'];
+const MARKER_START = '# >>> codeep hook >>>';
+const MARKER_END = '# <<< codeep hook <<<';
+export const HOOK_HELP = `Usage: codeep hook <install|uninstall> [options]
+
+Install a git hook that runs \`codeep review\` on your changes, blocking the
+commit/push when issues at/above the threshold are found. Honors a project's
+.codeep/review.yml (or .json).
+
+Actions:
+  install      Install the hook (pre-commit by default)
+  uninstall    Remove the Codeep-managed hook
+
+Options:
+  --pre-push          Manage the pre-push hook instead of pre-commit
+  --fail-on <level>   Severity that blocks: error | warning | info | none (default: error)
+  -h, --help          Show this help
+
+The pre-commit hook reviews the working-tree content of staged files, so stage
+your changes fully before committing for the most accurate result.
+Codeep never overwrites a pre-existing hook it didn't create.`;
+/** Parse argv after `hook`. Pure. */
+export function parseHookArgs(argv) {
+    const out = { action: 'help', hookType: 'pre-commit', failOn: 'error', help: false };
+    let i = 0;
+    if (argv[0] === 'install' || argv[0] === 'uninstall') {
+        out.action = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--pre-push')
+            out.hookType = 'pre-push';
+        else if (a === '--pre-commit')
+            out.hookType = 'pre-commit';
+        else if (a === '-h' || a === '--help')
+            out.help = true;
+        else if (a === '--fail-on') {
+            const v = argv[++i];
+            if (FAIL_ON_VALUES.includes(v))
+                out.failOn = v;
+        }
+        else if (a.startsWith('--fail-on=')) {
+            const v = a.slice('--fail-on='.length);
+            if (FAIL_ON_VALUES.includes(v))
+                out.failOn = v;
+        }
+    }
+    return out;
+}
+/** The hook script body. Pure. pre-commit scopes to staged files; pre-push reviews changes. */
+export function buildHookScript(hookType, failOn) {
+    const lines = [
+        '#!/bin/sh',
+        MARKER_START,
+        '# Managed by Codeep: `codeep hook install` to update, `codeep hook uninstall` to remove.',
+        'command -v codeep >/dev/null 2>&1 || exit 0', // no codeep on PATH → skip, don't block
+    ];
+    if (hookType === 'pre-commit') {
+        // NUL-delimited + xargs -0 so staged paths with spaces/metachars survive as
+        // single arguments (an unquoted $files would word-split and silently skip
+        // them — a fail-open gate). Temp file keeps it portable: BSD/macOS xargs has
+        // no `-r`, so we guard emptiness with `[ -s ]` instead.
+        lines.push('tmp=$(mktemp)');
+        lines.push('git diff --cached --name-only -z --diff-filter=ACMR > "$tmp"');
+        lines.push('if [ -s "$tmp" ]; then');
+        lines.push(`  xargs -0 codeep review --fail-on ${failOn} < "$tmp"`);
+        lines.push('  status=$?');
+        lines.push('else');
+        lines.push('  status=0');
+        lines.push('fi');
+        lines.push('rm -f "$tmp"');
+        lines.push('exit $status');
+    }
+    else {
+        lines.push(`codeep review --fail-on ${failOn}`);
+    }
+    lines.push(MARKER_END, '');
+    return lines.join('\n');
+}
+/** True when a hook file was created by Codeep (safe to overwrite/remove). */
+export function isCodeepHook(content) {
+    return content.includes(MARKER_START);
+}
+/** Resolve the git hooks directory (honors worktrees + core.hooksPath). Null if not a repo. */
+export function resolveHooksDir(cwd) {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore' });
+        const hooks = execSync('git rev-parse --git-path hooks', { cwd, encoding: 'utf8' }).trim();
+        return isAbsolute(hooks) ? hooks : join(cwd, hooks);
+    }
+    catch {
+        return null;
+    }
+}
+export function runHookCommand(argv, deps = defaultHookDeps()) {
+    const args = parseHookArgs(argv);
+    if (args.help || args.action === 'help') {
+        deps.write(HOOK_HELP);
+        return 0;
+    }
+    const hooksDir = deps.resolveHooksDir(process.cwd());
+    if (!hooksDir) {
+        deps.write('Not a git repository — run `codeep hook` inside a repo.');
+        return 1;
+    }
+    const target = join(hooksDir, args.hookType);
+    const existing = deps.readHook(target);
+    if (args.action === 'uninstall') {
+        if (existing === null) {
+            deps.write(`No ${args.hookType} hook to remove.`);
+            return 0;
+        }
+        if (!isCodeepHook(existing)) {
+            deps.write(`Refusing to remove ${args.hookType}: it was not created by Codeep.`);
+            return 1;
+        }
+        deps.removeHook(target);
+        deps.write(`Removed the Codeep ${args.hookType} hook.`);
+        return 0;
+    }
+    // install
+    if (existing !== null && !isCodeepHook(existing)) {
+        deps.write(`A ${args.hookType} hook already exists and was not created by Codeep — refusing to overwrite it. Remove it first, or add a \`codeep review\` call manually.`);
+        return 1;
+    }
+    deps.writeHook(target, buildHookScript(args.hookType, args.failOn));
+    const when = args.hookType === 'pre-commit' ? 'commit' : 'push';
+    deps.write(`Installed the Codeep ${args.hookType} hook → runs \`codeep review --fail-on ${args.failOn}\` on each ${when}.`);
+    return 0;
+}
+function defaultHookDeps() {
+    return {
+        resolveHooksDir,
+        readHook: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeHook: (p, content) => {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, content, { mode: 0o755 });
+            try {
+                chmodSync(p, 0o755);
+            }
+            catch { /* best effort (e.g. Windows) */ }
+        },
+        removeHook: (p) => {
+            try {
+                rmSync(p);
+            }
+            catch { /* ignore */ }
+        },
+        write: (t) => process.stdout.write(t + '\n'),
+    };
+}

package/dist/utils/headlessReview.d.ts

@@ -4,21 +4,35 @@ export interface ReviewArgs {
     files: string[];
     json: boolean;
     failOn: FailOn;
+    rules: boolean;
+    ai: boolean;
     help: boolean;
 }
-export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
+export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nCustom/disabled rules come from .codeep/review.yml (or .json) in the repo.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  --rules             List the built-in rule ids (for \"disable\" in .codeep/review.*) and exit\n  --ai                After the offline pass, ask your configured provider for a\n                      contextual second opinion on the working-tree diff\n                      (advisory; needs an API key; never affects the exit code)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export declare function parseReviewArgs(argv: string[]): ReviewArgs;
 /** Exit code for a result under a fail-on threshold. Pure. */
 export declare function exitCodeForResult(result: ReviewResult, failOn: FailOn): number;
+/** Render the built-in rule ids for `--rules`. Pure. */
+export declare function formatBuiltinRules(): string;
 export interface ReviewDeps {
     /** Run the review over optional specific files. */
     review: (files?: string[]) => ReviewResult;
     /** Sink for the report (one call). */
     write: (text: string) => void;
+    /** List of built-in rule ids (for --rules). */
+    listRules: () => string;
+    /** Optional AI second opinion; returns null when unavailable (no key / error). */
+    aiReview: (result: ReviewResult) => Promise<string | null>;
+    /** Provider/model label for the AI section header. */
+    aiMeta: () => {
+        provider?: string;
+        model?: string;
+    };
 }
 /**
  * Orchestrate a headless review and return the process exit code. Side effects
- * (filesystem, stdout) live behind `deps` so the flow is unit-testable.
+ * (filesystem, stdout, provider call) live behind `deps` so the flow is
+ * unit-testable. The exit code is ALWAYS deterministic — `--ai` is advisory.
  */
-export declare function runHeadlessReview(argv: string[], deps?: ReviewDeps): number;
+export declare function runHeadlessReview(argv: string[], deps?: ReviewDeps): Promise<number>;

package/dist/utils/headlessReview.js

@@ -2,7 +2,12 @@
 // deterministic reviewer in codeReview.ts. No API key, no TUI: it scans, prints
 // a report (markdown or JSON), and exits non-zero when issues at/above a chosen
 // severity are found, so it drops cleanly into CI (e.g. a GitHub Action).
-import { performCodeReview, formatReviewResult } from './codeReview.js';
+//
+// `--ai` is the one opt-in online mode: after the offline pass it asks the
+// configured provider for a contextual second opinion (advisory only — it never
+// affects the exit code), and degrades to deterministic-only when no key is set.
+import { performCodeReview, formatReviewResult, getReviewSystemPrompt, listBuiltinRules, appendAiSection, } from './codeReview.js';
+import { config, getCurrentProvider } from '../config/index.js';
 const FAIL_ON_VALUES = ['error', 'warning', 'info', 'none'];
 // Higher = more severe. `suggestion` sits below `info` so `--fail-on info`
 // never trips on a mere suggestion.
@@ -13,21 +18,33 @@ Run a deterministic, offline code review (no API key required). With no files,
 reviews your unstaged git changes, falling back to a src/ scan when the tree is
 clean. Pass files (or let your CI pass the PR's changed files) to scope it.
 
+Custom/disabled rules come from .codeep/review.yml (or .json) in the repo.
+
 Options:
   --json              Print the result as JSON instead of the markdown report
   --fail-on <level>   Exit non-zero when an issue at or above <level> is found:
                       error | warning | info | none   (default: error)
+  --rules             List the built-in rule ids (for "disable" in .codeep/review.*) and exit
+  --ai                After the offline pass, ask your configured provider for a
+                      contextual second opinion on the working-tree diff
+                      (advisory; needs an API key; never affects the exit code)
   -h, --help          Show this help
 
 Exit code: 0 when nothing at/above --fail-on is found, 1 otherwise.`;
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export function parseReviewArgs(argv) {
-    const out = { files: [], json: false, failOn: 'error', help: false };
+    const out = { files: [], json: false, failOn: 'error', rules: false, ai: false, help: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--json') {
             out.json = true;
         }
+        else if (arg === '--rules') {
+            out.rules = true;
+        }
+        else if (arg === '--ai') {
+            out.ai = true;
+        }
         else if (arg === '-h' || arg === '--help') {
             out.help = true;
         }
@@ -56,18 +73,44 @@ export function exitCodeForResult(result, failOn) {
     const tripped = result.issues.some((i) => (SEVERITY_RANK[i.severity] ?? 0) >= threshold);
     return tripped ? 1 : 0;
 }
+/** Render the built-in rule ids for `--rules`. Pure. */
+export function formatBuiltinRules() {
+    const rules = listBuiltinRules();
+    const idW = Math.max(...rules.map((r) => r.id.length));
+    const sevW = Math.max(...rules.map((r) => r.severity.length));
+    const out = [
+        'Built-in review rules — put any id in "disable" in .codeep/review.yml|json:',
+        '',
+    ];
+    for (const r of rules) {
+        out.push(`  ${r.id.padEnd(idW)}  ${r.severity.padEnd(sevW)}  ${r.description}`);
+    }
+    return out.join('\n');
+}
 /**
  * Orchestrate a headless review and return the process exit code. Side effects
- * (filesystem, stdout) live behind `deps` so the flow is unit-testable.
+ * (filesystem, stdout, provider call) live behind `deps` so the flow is
+ * unit-testable. The exit code is ALWAYS deterministic — `--ai` is advisory.
  */
-export function runHeadlessReview(argv, deps = defaultDeps()) {
+export async function runHeadlessReview(argv, deps = defaultDeps()) {
     const args = parseReviewArgs(argv);
     if (args.help) {
         deps.write(REVIEW_HELP);
         return 0;
     }
+    if (args.rules) {
+        deps.write(deps.listRules());
+        return 0;
+    }
     const result = deps.review(args.files.length ? args.files : undefined);
-    deps.write(args.json ? JSON.stringify(result, null, 2) : formatReviewResult(result));
+    const aiText = args.ai ? await deps.aiReview(result) : null;
+    if (args.json) {
+        deps.write(JSON.stringify(args.ai ? { ...result, aiReview: aiText } : result, null, 2));
+    }
+    else {
+        const md = formatReviewResult(result);
+        deps.write(args.ai ? appendAiSection(md, aiText, deps.aiMeta()) : md);
+    }
     return exitCodeForResult(result, args.failOn);
 }
 // Only the reviewer's `.root` is read, so a minimal context rooted at cwd is
@@ -84,8 +127,41 @@ function minimalContext(root) {
     };
 }
 function defaultDeps() {
+    const cwd = process.cwd();
     return {
-        review: (files) => performCodeReview(minimalContext(process.cwd()), files),
+        review: (files) => performCodeReview(minimalContext(cwd), files),
         write: (text) => process.stdout.write(text + '\n'),
+        listRules: () => formatBuiltinRules(),
+        aiMeta: () => {
+            try {
+                return { provider: getCurrentProvider().name, model: String(config.get('model') || '') };
+            }
+            catch {
+                return {};
+            }
+        },
+        aiReview: async (result) => {
+            try {
+                const { loadAllApiKeys, isConfigured } = await import('../config/index.js');
+                await loadAllApiKeys();
+                if (!isConfigured()) {
+                    process.stderr.write('codeep review --ai: no API key configured for the current provider; skipping the AI pass (deterministic results below).\n');
+                    return null;
+                }
+                const { getGitDiff } = await import('./git.js');
+                const { chat } = await import('../api/index.js');
+                const d = getGitDiff(false, cwd);
+                const diff = d.success && d.diff ? d.diff.slice(0, 50000) : '(no textual diff available — reviewing the deterministic findings only)';
+                // Fold the prompt + findings into the user message (not a system-role
+                // history entry): chat() does not hoist a history `system` entry into
+                // the Anthropic top-level `system` field, so it would be dropped on
+                // Anthropic-protocol providers. As the user message it reaches every provider.
+                const message = `${getReviewSystemPrompt(result)}\n\n## Diff under review\n\`\`\`diff\n${diff}\n\`\`\``;
+                return await chat(message, []);
+            }
+            catch {
+                return null; // never hard-fail the review on an AI error
+            }
+        },
     };
 }

package/dist/utils/keychain.d.ts

@@ -9,6 +9,9 @@ export interface SecureStorage {
     setApiKey(providerId: string, apiKey: string): Promise<void>;
     deleteApiKey(providerId: string): Promise<void>;
     hasApiKey(providerId: string): Promise<boolean>;
+    /** Whether the OS keychain is usable (vs the plaintext-config fallback).
+     *  Optional — only SmartStorage (what createSecureStorage returns) implements it. */
+    isKeychainAvailable?(): Promise<boolean>;
 }
 /**
  * Migrate existing plain-text API keys to keychain

package/dist/utils/keychain.js

@@ -124,6 +124,10 @@ class SmartStorage {
         }
         this.keychainTested = true;
     }
+    async isKeychainAvailable() {
+        await this.ensureKeychainTested();
+        return this.useKeychain;
+    }
     async getApiKey(providerId) {
         await this.ensureKeychainTested();
         if (this.useKeychain) {

package/dist/utils/reviewConfig.js

@@ -23,7 +23,10 @@
  */
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-const CONFIG_PATH = '.codeep/review.json';
+import yaml from 'js-yaml';
+// Candidate config files, in precedence order: YAML preferred (nicer for a
+// human-authored rules file — comments, single-quoted regex), JSON as fallback.
+const CONFIG_PATHS = ['.codeep/review.yml', '.codeep/review.yaml', '.codeep/review.json'];
 const MAX_RULES = 200;
 const VALID_CATEGORIES = [
     'security', 'performance', 'maintainability', 'bug', 'style', 'types', 'best-practice', 'documentation',
@@ -53,19 +56,35 @@ function asStringArray(v) {
         : [];
 }
 export function loadReviewConfig(projectRoot) {
-    const filePath = join(projectRoot, CONFIG_PATH);
-    if (!existsSync(filePath))
+    // First existing candidate wins (.yml > .yaml > .json).
+    let chosen = null;
+    let text = '';
+    for (const candidate of CONFIG_PATHS) {
+        const fp = join(projectRoot, candidate);
+        if (existsSync(fp)) {
+            chosen = candidate;
+            try {
+                text = readFileSync(fp, 'utf-8');
+            }
+            catch {
+                return null;
+            }
+            break;
+        }
+    }
+    if (!chosen)
         return null;
+    const isJson = chosen.endsWith('.json');
     let data;
     try {
-        data = JSON.parse(readFileSync(filePath, 'utf-8'));
+        data = isJson ? JSON.parse(text) : yaml.load(text);
     }
     catch {
-        console.warn(`[codeep] Ignoring ${CONFIG_PATH}: not valid JSON.`);
+        console.warn(`[codeep] Ignoring ${chosen}: not valid ${isJson ? 'JSON' : 'YAML'}.`);
         return null;
     }
     if (!data || typeof data !== 'object' || Array.isArray(data)) {
-        console.warn(`[codeep] Ignoring ${CONFIG_PATH}: expected a JSON object.`);
+        console.warn(`[codeep] Ignoring ${chosen}: expected a top-level object.`);
         return null;
     }
     const cfg = data;
@@ -82,12 +101,12 @@ export function loadReviewConfig(projectRoot) {
         const message = typeof r.message === 'string' && r.message.trim() ? r.message.trim() : null;
         const patternSrc = typeof r.pattern === 'string' && r.pattern ? r.pattern : null;
         if (!id || !message || !patternSrc) {
-            console.warn(`[codeep] Skipping a rule in ${CONFIG_PATH}: each rule needs id, pattern and message.`);
+            console.warn(`[codeep] Skipping a rule in ${chosen}: each rule needs id, pattern and message.`);
             continue;
         }
         // Reject oversized patterns outright — keeps regex compilation/run bounded.
         if (patternSrc.length > 1000) {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: pattern is too long (>1000 chars).`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: pattern is too long (>1000 chars).`);
             continue;
         }
         // Conservative ReDoS screen: reject the classic catastrophic shape — a group
@@ -95,7 +114,7 @@ export function loadReviewConfig(projectRoot) {
         // (\d*)*, (.*)+, (x+){2,}. Not exhaustive (the GitHub Action also bounds
         // wall-clock), but it blocks the common foot-guns in an untrusted review.json.
         if (/\([^)]*[+*]\)\s*[+*{]/.test(patternSrc)) {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: nested quantifiers risk catastrophic backtracking (ReDoS).`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: nested quantifiers risk catastrophic backtracking (ReDoS).`);
             continue;
         }
         // Always include the global flag so every match in a file is found.
@@ -107,7 +126,7 @@ export function loadReviewConfig(projectRoot) {
             pattern = new RegExp(patternSrc, flags);
         }
         catch {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: invalid regex.`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: invalid regex.`);
             continue;
         }
         const category = VALID_CATEGORIES.includes(r.category)

package/dist/utils/update.d.ts

@@ -5,7 +5,9 @@ export interface VersionInfo {
     error?: string;
 }
 /**
- * Get current version from package.json
+ * Current Codeep version. Uses the build-time-baked VERSION constant (works in
+ * the bun-compiled binary, which has no package.json on disk), falling back to
+ * reading package.json for an unbuilt dev tree.
  */
 export declare function getCurrentVersion(): string;
 /**

package/dist/utils/update.js

@@ -1,14 +1,18 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { VERSION } from '../version.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
- * Get current version from package.json
+ * Current Codeep version. Uses the build-time-baked VERSION constant (works in
+ * the bun-compiled binary, which has no package.json on disk), falling back to
+ * reading package.json for an unbuilt dev tree.
  */
 export function getCurrentVersion() {
+    if (VERSION)
+        return VERSION;
     try {
-        // In built version, package.json is in parent directory
         const packagePath = join(__dirname, '../../package.json');
         const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
         return packageJson.version;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "2.8.0";

package/dist/version.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/gen-version.js — do not edit by hand.
+// Baked from package.json at build time so the bun-compiled binary reports
+// the right version (it has no package.json on disk to read at runtime).
+export const VERSION = '2.8.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeep",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,9 +8,9 @@
     "codeep": "bin/codeep.js"
   },
   "scripts": {
-    "dev": "node --import tsx src/renderer/main.ts",
-    "prepack": "tsc; node scripts/fix-imports.js",
-    "build": "tsc && node scripts/fix-imports.js",
+    "dev": "node scripts/gen-version.js && node --import tsx src/renderer/main.ts",
+    "prepack": "node scripts/gen-version.js && tsc; node scripts/fix-imports.js",
+    "build": "node scripts/gen-version.js && tsc && node scripts/fix-imports.js",
     "start": "node dist/renderer/main.js",
     "demo:renderer": "node --import tsx src/renderer/demo.ts",
     "demo:app": "node --import tsx src/renderer/demo-app.ts",
@@ -42,10 +42,12 @@
   "dependencies": {
     "clipboardy": "^4.0.0",
     "conf": "^12.0.0",
+    "js-yaml": "^4.1.0",
     "keytar": "^7.9.0",
     "open": "^10.0.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
     "@vitest/coverage-v8": "^4.0.18",
     "pkg": "^5.8.1",