codeep 1.3.42 → 2.0.1

package/dist/utils/checkpoints.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session checkpoints — `/checkpoint` and `/rewind`.
+ *
+ * A checkpoint is a snapshot of the agent conversation at a point in time:
+ * session history, provider/model state, and the list of files the agent has
+ * touched in this session. It does NOT snapshot file content — that's git's
+ * job, and trying to do it ourselves means either a 100KB-per-file ceiling
+ * with surprise truncation, or a real-time disk hog. We surface a hint at
+ * rewind time telling the user how to restore files via git.
+ *
+ * Use cases this is for:
+ *   - User suspects the agent is going off the rails after N steps and
+ *     wants to roll the conversation back to before that turn.
+ *   - User is about to start a risky multi-step refactor and wants a
+ *     named bookmark to return to if it gets messy.
+ *
+ * Use cases this is NOT for:
+ *   - Replacing git. If you only need file rollback, `git restore` /
+ *     `git stash` is faster and reliable.
+ *   - Cross-session persistence beyond the workspace's `.codeep/checkpoints/`
+ *     folder — checkpoints are per-project, not global.
+ *
+ * On-disk shape (`.codeep/checkpoints/<id>.json`):
+ * {
+ *   "id": "ck-2026-05-18-abc123",
+ *   "name": "before big refactor",
+ *   "createdAt": "...",
+ *   "sessionId": "session-2026-05-18-...",
+ *   "provider": "z.ai",
+ *   "model": "glm-5.1",
+ *   "messages": [ ... ],
+ *   "filesTouched": ["src/a.ts", "src/b.ts"],
+ *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo
+ * }
+ */
+import type { Message } from '../config/index.js';
+export interface Checkpoint {
+    id: string;
+    name?: string;
+    createdAt: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    messages: Message[];
+    filesTouched: string[];
+    gitHead?: string;
+}
+/** Lightweight metadata for `/checkpoints` list — avoids loading full message arrays. */
+export interface CheckpointMeta {
+    id: string;
+    name?: string;
+    createdAt: string;
+    sessionId: string;
+    messageCount: number;
+    filesTouchedCount: number;
+    gitHead?: string;
+}
+/**
+ * Create a new checkpoint snapshot of the current session state.
+ * Returns the persisted checkpoint object.
+ */
+export declare function createCheckpoint(opts: {
+    workspaceRoot: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    messages: Message[];
+    filesTouched: string[];
+    name?: string;
+}): Checkpoint;
+/**
+ * Load a single checkpoint by id. Returns null if not found or unreadable.
+ */
+export declare function loadCheckpoint(workspaceRoot: string, id: string): Checkpoint | null;
+/**
+ * List checkpoints in the workspace, newest first. Returns metadata only —
+ * the full `messages` array is not loaded so this is cheap for `/checkpoints`.
+ */
+export declare function listCheckpoints(workspaceRoot: string): CheckpointMeta[];
+/**
+ * Delete a checkpoint by id. Returns true if a file was removed.
+ */
+export declare function deleteCheckpoint(workspaceRoot: string, id: string): boolean;
+/**
+ * Format a checkpoint list as a Markdown block for `/checkpoints` output.
+ */
+export declare function formatCheckpointList(metas: CheckpointMeta[]): string;
+/**
+ * Build the user-facing hint shown after a successful /rewind. Tells the
+ * user how to bring their files back to checkpoint state — checkpoints
+ * don't snapshot file content, so this is the only restore path.
+ */
+export declare function buildRewindGitHint(cp: Checkpoint): string;

package/dist/utils/checkpoints.js

@@ -0,0 +1,205 @@
+/**
+ * Session checkpoints — `/checkpoint` and `/rewind`.
+ *
+ * A checkpoint is a snapshot of the agent conversation at a point in time:
+ * session history, provider/model state, and the list of files the agent has
+ * touched in this session. It does NOT snapshot file content — that's git's
+ * job, and trying to do it ourselves means either a 100KB-per-file ceiling
+ * with surprise truncation, or a real-time disk hog. We surface a hint at
+ * rewind time telling the user how to restore files via git.
+ *
+ * Use cases this is for:
+ *   - User suspects the agent is going off the rails after N steps and
+ *     wants to roll the conversation back to before that turn.
+ *   - User is about to start a risky multi-step refactor and wants a
+ *     named bookmark to return to if it gets messy.
+ *
+ * Use cases this is NOT for:
+ *   - Replacing git. If you only need file rollback, `git restore` /
+ *     `git stash` is faster and reliable.
+ *   - Cross-session persistence beyond the workspace's `.codeep/checkpoints/`
+ *     folder — checkpoints are per-project, not global.
+ *
+ * On-disk shape (`.codeep/checkpoints/<id>.json`):
+ * {
+ *   "id": "ck-2026-05-18-abc123",
+ *   "name": "before big refactor",
+ *   "createdAt": "...",
+ *   "sessionId": "session-2026-05-18-...",
+ *   "provider": "z.ai",
+ *   "model": "glm-5.1",
+ *   "messages": [ ... ],
+ *   "filesTouched": ["src/a.ts", "src/b.ts"],
+ *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo
+ * }
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+function getCheckpointsDir(workspaceRoot) {
+    const dir = join(workspaceRoot, '.codeep', 'checkpoints');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function readGitHead(workspaceRoot) {
+    try {
+        // Short SHA is enough for human display; full SHA available via git if needed.
+        const out = execSync('git rev-parse --short HEAD', {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Generate a unique, human-recognizable checkpoint id.
+ * Format: `ck-YYYY-MM-DD-<8-char-uuid>`
+ */
+function generateCheckpointId() {
+    const date = new Date().toISOString().slice(0, 10);
+    return `ck-${date}-${randomUUID().slice(0, 8)}`;
+}
+/**
+ * Create a new checkpoint snapshot of the current session state.
+ * Returns the persisted checkpoint object.
+ */
+export function createCheckpoint(opts) {
+    const checkpoint = {
+        id: generateCheckpointId(),
+        name: opts.name,
+        createdAt: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        provider: opts.provider,
+        model: opts.model,
+        messages: opts.messages,
+        filesTouched: opts.filesTouched,
+        gitHead: readGitHead(opts.workspaceRoot),
+    };
+    const dir = getCheckpointsDir(opts.workspaceRoot);
+    writeFileSync(join(dir, `${checkpoint.id}.json`), JSON.stringify(checkpoint, null, 2));
+    return checkpoint;
+}
+/**
+ * Load a single checkpoint by id. Returns null if not found or unreadable.
+ */
+export function loadCheckpoint(workspaceRoot, id) {
+    // Defensive: reject ids that look like path traversal attempts. Real ids are
+    // `ck-YYYY-MM-DD-<hex>` so the regex is tight enough to catch typos too.
+    if (!/^ck-\d{4}-\d{2}-\d{2}-[a-f0-9]{8}$/.test(id))
+        return null;
+    const file = join(getCheckpointsDir(workspaceRoot), `${id}.json`);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List checkpoints in the workspace, newest first. Returns metadata only —
+ * the full `messages` array is not loaded so this is cheap for `/checkpoints`.
+ */
+export function listCheckpoints(workspaceRoot) {
+    const dir = getCheckpointsDir(workspaceRoot);
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const metas = [];
+    for (const file of files) {
+        try {
+            const full = join(dir, file);
+            const stat = statSync(full);
+            const cp = JSON.parse(readFileSync(full, 'utf-8'));
+            metas.push({
+                id: cp.id,
+                name: cp.name,
+                createdAt: cp.createdAt || stat.mtime.toISOString(),
+                sessionId: cp.sessionId,
+                messageCount: cp.messages?.length ?? 0,
+                filesTouchedCount: cp.filesTouched?.length ?? 0,
+                gitHead: cp.gitHead,
+            });
+        }
+        catch {
+            // Skip corrupt entries — don't let one bad checkpoint block the list.
+        }
+    }
+    // Newest first by createdAt.
+    metas.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+    return metas;
+}
+/**
+ * Delete a checkpoint by id. Returns true if a file was removed.
+ */
+export function deleteCheckpoint(workspaceRoot, id) {
+    if (!/^ck-\d{4}-\d{2}-\d{2}-[a-f0-9]{8}$/.test(id))
+        return false;
+    const file = join(getCheckpointsDir(workspaceRoot), `${id}.json`);
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a checkpoint list as a Markdown block for `/checkpoints` output.
+ */
+export function formatCheckpointList(metas) {
+    if (metas.length === 0) {
+        return [
+            '_No checkpoints yet._',
+            '',
+            'Create one with `/checkpoint [name]` before risky refactors so you can `/rewind` if things go sideways.',
+        ].join('\n');
+    }
+    const lines = ['## Checkpoints', ''];
+    for (const m of metas) {
+        const label = m.name ? `**${m.name}** (\`${m.id}\`)` : `\`${m.id}\``;
+        const gitFragment = m.gitHead ? ` · git \`${m.gitHead}\`` : '';
+        const date = m.createdAt.slice(0, 19).replace('T', ' ');
+        lines.push(`- ${label}`, `  ${date} · ${m.messageCount} message${m.messageCount === 1 ? '' : 's'} · ${m.filesTouchedCount} file${m.filesTouchedCount === 1 ? '' : 's'} touched${gitFragment}`);
+    }
+    lines.push('', 'Use `/rewind <id>` to restore a checkpoint, or `/checkpoint delete <id>` to drop one.');
+    return lines.join('\n');
+}
+/**
+ * Build the user-facing hint shown after a successful /rewind. Tells the
+ * user how to bring their files back to checkpoint state — checkpoints
+ * don't snapshot file content, so this is the only restore path.
+ */
+export function buildRewindGitHint(cp) {
+    if (cp.gitHead) {
+        return [
+            `**Files were NOT restored** — only the conversation. To bring files back to the state at checkpoint time:`,
+            '',
+            '```bash',
+            `git stash  # save current uncommitted changes if you want to keep them`,
+            `git checkout ${cp.gitHead} -- ${cp.filesTouched.length > 0 ? cp.filesTouched.map(f => `'${f}'`).join(' ') : '.'}`,
+            '```',
+        ].join('\n');
+    }
+    return [
+        '**Files were NOT restored** — only the conversation.',
+        cp.filesTouched.length > 0
+            ? `Files the agent touched between checkpoint and now: ${cp.filesTouched.map(f => `\`${f}\``).join(', ')}.`
+            : '',
+        'Use `git` (or your editor\'s undo) to revert any file changes you don\'t want.',
+    ].filter(Boolean).join('\n');
+}

package/dist/utils/context.d.ts

@@ -27,6 +27,30 @@ export declare function clearContext(projectPath: string): boolean;
  * Get all saved contexts
  */
 export declare function getAllContexts(): ConversationContext[];
+/**
+ * AI-powered compaction of a conversation history.
+ *
+ * Used by the `/compact` slash command. Sends the older portion of the
+ * conversation to the active provider with a summarization prompt, then
+ * replaces those messages with a single system message containing the
+ * summary. Keeps the last `keepRecent` messages verbatim so the
+ * conversation can continue without losing the most recent context.
+ *
+ * Returns the same `history` (untouched) if there isn't enough to
+ * meaningfully compact.
+ */
+export declare function compactHistory(history: Message[], options?: {
+    keepRecent?: number;
+    projectContext?: import('./project').ProjectContext | null;
+    /** Cap on how long the summarization API call can take, in ms. Defaults to 60s. */
+    timeoutMs?: number;
+    /** External abort signal (e.g. user pressed /stop). Combined with the timeout. */
+    abortSignal?: AbortSignal;
+}): Promise<{
+    compacted: Message[];
+    replaced: number;
+    summary: string;
+}>;
 /**
  * Summarize messages for context persistence
  * Keeps recent messages and summarizes older ones

package/dist/utils/context.js

@@ -113,6 +113,63 @@ export function getAllContexts() {
         return [];
     }
 }
+/**
+ * AI-powered compaction of a conversation history.
+ *
+ * Used by the `/compact` slash command. Sends the older portion of the
+ * conversation to the active provider with a summarization prompt, then
+ * replaces those messages with a single system message containing the
+ * summary. Keeps the last `keepRecent` messages verbatim so the
+ * conversation can continue without losing the most recent context.
+ *
+ * Returns the same `history` (untouched) if there isn't enough to
+ * meaningfully compact.
+ */
+export async function compactHistory(history, options = {}) {
+    const keepRecent = options.keepRecent ?? 4;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    // Need at least one full exchange to compact (user + assistant) plus the
+    // recent tail — otherwise compaction is just overhead.
+    if (history.length <= keepRecent + 2) {
+        return { compacted: history, replaced: 0, summary: '' };
+    }
+    const toCompact = history.slice(0, history.length - keepRecent);
+    const recent = history.slice(history.length - keepRecent);
+    const transcript = toCompact
+        .map(m => `[${m.role.toUpperCase()}]\n${m.content}`)
+        .join('\n\n---\n\n');
+    const prompt = 'Summarize the following conversation between a user and a coding assistant.' +
+        ' Capture concisely: (1) what the user was trying to accomplish, (2) key decisions and rationale,' +
+        ' (3) files or components touched, (4) outstanding questions or unfinished work.' +
+        ' The summary will replace these messages in the agent\'s context, so include anything needed' +
+        ' to continue the work without re-reading the originals.\n\nConversation:\n\n' +
+        transcript;
+    // Cap how long we'll wait. /compact otherwise blocks the whole session
+    // with no way to interrupt (the regular /stop targets the agent loop,
+    // not arbitrary chat calls). If the user passed their own AbortSignal,
+    // combine it with our timer so either can cancel.
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+    const onExternalAbort = () => timeoutController.abort();
+    options.abortSignal?.addEventListener('abort', onExternalAbort);
+    try {
+        const { chat } = await import('../api/index.js');
+        const summary = await chat(prompt, [], undefined, undefined, options.projectContext ?? undefined, timeoutController.signal);
+        const summaryMessage = {
+            role: 'system',
+            content: `[Conversation compacted — ${toCompact.length} earlier message${toCompact.length === 1 ? '' : 's'} summarized below]\n\n${summary}`,
+        };
+        return {
+            compacted: [summaryMessage, ...recent],
+            replaced: toCompact.length,
+            summary,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        options.abortSignal?.removeEventListener('abort', onExternalAbort);
+    }
+}
 /**
  * Summarize messages for context persistence
  * Keeps recent messages and summarizes older ones

package/dist/utils/customCommands.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Custom slash commands.
+ *
+ * Users drop `.md` files in either:
+ *   - `<workspace>/.codeep/commands/<name>.md`  (project-scoped)
+ *   - `~/.codeep/commands/<name>.md`            (global, all projects)
+ *
+ * Each file becomes a `/<name>` slash command. Project files take precedence
+ * over global files with the same name.
+ *
+ * File format (frontmatter optional):
+ *
+ *   ---
+ *   description: Detailed security review of a file
+ *   aliases: [sec, secrev]
+ *   ---
+ *
+ *   Please perform a thorough security review of: {{args}}
+ *
+ * The body is expanded with the user's arguments and sent as a user message
+ * to the agent. Placeholders supported:
+ *   - `{{args}}` and `$ARGUMENTS` — full args string (Claude Code compat)
+ *   - `{{arg1}}` … `{{argN}}`     — positional args (1-indexed)
+ *
+ * Custom commands are not invoked automatically — they only fire when the
+ * user types `/<name>`. The agent never sees them in its tool catalog.
+ */
+export interface CustomCommand {
+    /** Slash name without the leading `/` */
+    name: string;
+    /** One-line description for /help and ACP autocomplete */
+    description: string;
+    /** Body text after frontmatter, with placeholders unresolved */
+    body: string;
+    /** Filesystem path the command was loaded from */
+    source: string;
+    /** 'project' if loaded from <workspace>/.codeep/commands, else 'global' */
+    scope: 'project' | 'global';
+    /** Optional alternative names that also trigger this command */
+    aliases: string[];
+}
+/**
+ * Load all custom commands available in this workspace.
+ * Project commands shadow global commands with the same name.
+ */
+export declare function loadCustomCommands(workspaceRoot?: string): CustomCommand[];
+/**
+ * Resolve a user-typed slash name to a custom command, checking primary
+ * name first then aliases. Project scope wins over global on collisions
+ * (handled inside loadCustomCommands).
+ */
+export declare function findCustomCommand(name: string, workspaceRoot?: string): CustomCommand | null;
+/**
+ * Expand `{{args}}`, `$ARGUMENTS`, and `{{argN}}` placeholders in the
+ * command body. If the body has no placeholders, the args are appended
+ * on a new line so the agent still sees them.
+ */
+export declare function expandCommand(cmd: CustomCommand, args: string[]): string;
+/**
+ * Render the catalog as a Markdown block for `/commands`.
+ */
+export declare function formatCommandList(commands: CustomCommand[]): string;

package/dist/utils/customCommands.js

@@ -0,0 +1,201 @@
+/**
+ * Custom slash commands.
+ *
+ * Users drop `.md` files in either:
+ *   - `<workspace>/.codeep/commands/<name>.md`  (project-scoped)
+ *   - `~/.codeep/commands/<name>.md`            (global, all projects)
+ *
+ * Each file becomes a `/<name>` slash command. Project files take precedence
+ * over global files with the same name.
+ *
+ * File format (frontmatter optional):
+ *
+ *   ---
+ *   description: Detailed security review of a file
+ *   aliases: [sec, secrev]
+ *   ---
+ *
+ *   Please perform a thorough security review of: {{args}}
+ *
+ * The body is expanded with the user's arguments and sent as a user message
+ * to the agent. Placeholders supported:
+ *   - `{{args}}` and `$ARGUMENTS` — full args string (Claude Code compat)
+ *   - `{{arg1}}` … `{{argN}}`     — positional args (1-indexed)
+ *
+ * Custom commands are not invoked automatically — they only fire when the
+ * user types `/<name>`. The agent never sees them in its tool catalog.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Minimal YAML frontmatter parser — handles `key: value` and
+ * `key: [a, b, c]`. We deliberately avoid a YAML dependency because the
+ * surface area we care about is tiny.
+ */
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        return { meta: {}, body: raw };
+    const meta = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^\s*([a-zA-Z_][\w-]*)\s*:\s*(.*?)\s*$/);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        let value = kv[2];
+        const arr = value.match(/^\[(.*)\]$/);
+        if (arr) {
+            value = arr[1]
+                .split(',')
+                .map(s => s.trim().replace(/^["']|["']$/g, ''))
+                .filter(Boolean);
+        }
+        else {
+            value = value.replace(/^["']|["']$/g, '');
+        }
+        if (key === 'description' && typeof value === 'string')
+            meta.description = value;
+        if (key === 'aliases' && Array.isArray(value))
+            meta.aliases = value;
+    }
+    return { meta, body: match[2].trimStart() };
+}
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const commands = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const fullPath = join(dir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                continue;
+            // Sanity ceiling — a slash-command template above 64KB is almost
+            // certainly someone dumping a doc in the wrong folder.
+            if (stat.size > 65_536)
+                continue;
+            const raw = readFileSync(fullPath, 'utf-8');
+            const { meta, body } = parseFrontmatter(raw);
+            const name = entry.replace(/\.md$/, '').toLowerCase();
+            if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+                continue; // names match `/foo-bar`
+            commands.push({
+                name,
+                description: meta.description ?? `Custom ${scope} command`,
+                body: body.trim(),
+                source: fullPath,
+                scope,
+                aliases: (meta.aliases ?? []).map(a => a.toLowerCase()).filter(a => /^[a-z0-9][a-z0-9-]*$/.test(a)),
+            });
+        }
+        catch {
+            // Skip unreadable / malformed files silently — they shouldn't block
+            // the rest of the catalog from loading.
+        }
+    }
+    return commands;
+}
+/**
+ * Load all custom commands available in this workspace.
+ * Project commands shadow global commands with the same name.
+ */
+export function loadCustomCommands(workspaceRoot) {
+    const global = loadFromDir(join(homedir(), '.codeep', 'commands'), 'global');
+    const project = workspaceRoot
+        ? loadFromDir(join(workspaceRoot, '.codeep', 'commands'), 'project')
+        : [];
+    // Project wins on name collisions; collapse to a single map keyed by name.
+    const byName = new Map();
+    for (const cmd of global)
+        byName.set(cmd.name, cmd);
+    for (const cmd of project)
+        byName.set(cmd.name, cmd);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a user-typed slash name to a custom command, checking primary
+ * name first then aliases. Project scope wins over global on collisions
+ * (handled inside loadCustomCommands).
+ */
+export function findCustomCommand(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    const all = loadCustomCommands(workspaceRoot);
+    return all.find(c => c.name === lower || c.aliases.includes(lower)) ?? null;
+}
+/**
+ * Expand `{{args}}`, `$ARGUMENTS`, and `{{argN}}` placeholders in the
+ * command body. If the body has no placeholders, the args are appended
+ * on a new line so the agent still sees them.
+ */
+export function expandCommand(cmd, args) {
+    const joined = args.join(' ');
+    const hasPlaceholder = /\{\{args\}\}|\$ARGUMENTS|\{\{arg\d+\}\}/.test(cmd.body);
+    let expanded = cmd.body
+        .replace(/\{\{args\}\}/g, joined)
+        .replace(/\$ARGUMENTS/g, joined);
+    // Positional: {{arg1}}, {{arg2}}, ...
+    expanded = expanded.replace(/\{\{arg(\d+)\}\}/g, (_m, n) => {
+        const idx = parseInt(n, 10) - 1;
+        return args[idx] ?? '';
+    });
+    if (!hasPlaceholder && joined) {
+        expanded += `\n\n${joined}`;
+    }
+    return expanded;
+}
+/**
+ * Render the catalog as a Markdown block for `/commands`.
+ */
+export function formatCommandList(commands) {
+    if (!commands.length) {
+        return [
+            '_No custom commands yet._',
+            '',
+            'Create one by adding a Markdown file:',
+            '',
+            '- `<workspace>/.codeep/commands/<name>.md` — project-scoped',
+            '- `~/.codeep/commands/<name>.md` — global (all projects)',
+            '',
+            'Example:',
+            '',
+            '```markdown',
+            '---',
+            'description: Detailed security review of a file',
+            '---',
+            '',
+            'Please perform a thorough security review of: {{args}}',
+            '```',
+            '',
+            'Then call it as `/<name> <args>`.',
+        ].join('\n');
+    }
+    const projectCmds = commands.filter(c => c.scope === 'project');
+    const globalCmds = commands.filter(c => c.scope === 'global');
+    const lines = ['## Custom Commands', ''];
+    if (projectCmds.length) {
+        lines.push('**Project**');
+        for (const c of projectCmds) {
+            const aliasNote = c.aliases.length ? ` (aliases: ${c.aliases.map(a => `\`/${a}\``).join(', ')})` : '';
+            lines.push(`- \`/${c.name}\`${aliasNote} — ${c.description}`);
+        }
+        lines.push('');
+    }
+    if (globalCmds.length) {
+        lines.push('**Global**');
+        for (const c of globalCmds) {
+            const aliasNote = c.aliases.length ? ` (aliases: ${c.aliases.map(a => `\`/${a}\``).join(', ')})` : '';
+            lines.push(`- \`/${c.name}\`${aliasNote} — ${c.description}`);
+        }
+    }
+    return lines.join('\n');
+}