codeep 2.0.0 → 2.0.2

package/dist/acp/commands.js

@@ -600,6 +600,62 @@ Anything else the agent should know — edge cases, gotchas, things to double-ch
             }
         }
         // ─── Export ────────────────────────────────────────────────────────────────
+        // ─── Plan mode (2.0.2) ────────────────────────────────────────────────────
+        case 'plan': {
+            // Identical contract to TUI /plan: generate a pre-execution plan,
+            // surface it, hold as pending so /go can execute it without re-planning.
+            if (!args.length) {
+                const { getPendingPlan } = await import('../utils/planMode.js');
+                const cur = getPendingPlan();
+                return {
+                    handled: true,
+                    response: cur
+                        ? `**Pending plan for:** _${cur.task}_\n\n${cur.plan}\n\n---\nRun \`/go\` to execute, or \`/plan <revised task>\` to revise.`
+                        : 'Usage: `/plan <task>` — generates a plan you can review, then `/go` to execute.',
+                };
+            }
+            const task = args.join(' ');
+            onChunk(`_Generating plan for: ${task.slice(0, 80)}${task.length > 80 ? '…' : ''}_\n\n`);
+            try {
+                const { generatePlan } = await import('../utils/planMode.js');
+                const plan = await generatePlan(task);
+                return {
+                    handled: true,
+                    response: `${plan}\n\n---\nRun \`/go\` to execute this plan, or \`/plan <revised task>\` to refine it.`,
+                    streaming: true,
+                };
+            }
+            catch (err) {
+                return { handled: true, response: `Plan generation failed: ${err.message}`, streaming: true };
+            }
+        }
+        case 'go': {
+            const { getPendingPlan, composeExecutionPrompt, clearPendingPlan } = await import('../utils/planMode.js');
+            const cur = getPendingPlan();
+            if (!cur) {
+                return { handled: true, response: 'No pending plan. Run `/plan <task>` first.' };
+            }
+            const prompt = composeExecutionPrompt(cur);
+            clearPendingPlan();
+            onChunk(`_Executing approved plan…_\n\n`);
+            try {
+                const { buildProjectContext } = await import('./session.js');
+                const ctx = buildProjectContext(session.workspaceRoot);
+                const agentResult = await runAgent(prompt, ctx, {
+                    abortSignal,
+                    onIteration: (_i, msg) => { onChunk(msg + '\n'); },
+                    onThinking: (text) => { onChunk(text); },
+                });
+                return {
+                    handled: true,
+                    response: agentResult.finalResponse || '_(plan executed; no final summary)_',
+                    streaming: true,
+                };
+            }
+            catch (err) {
+                return { handled: true, response: `Plan execution failed: ${err.message}`, streaming: true };
+            }
+        }
         case 'export': {
             if (!session.history.length)
                 return { handled: true, response: 'No messages to export.' };

package/dist/acp/server.js

@@ -52,6 +52,9 @@ const AVAILABLE_COMMANDS = [
     { name: 'mcp', description: 'Manage MCP servers, marketplace, resources, prompts', input: { hint: '[browse | install <id> | add | remove | reload | resources | read <uri> | prompts | prompt <server> <name>]' } },
     { name: 'openrouter', description: 'OpenRouter routing preferences (prefer/ignore/fallbacks/privacy/clear)', input: { hint: '[show | prefer <p,...> | ignore <p,...> | fallbacks on|off | privacy strict|allow | clear]' } },
     { name: 'export', description: 'Export conversation', input: { hint: 'json | md | txt' } },
+    // Plan mode (2.0.2)
+    { name: 'plan', description: 'Generate a numbered plan for a task — review before /go executes', input: { hint: '<task>' } },
+    { name: 'go', description: 'Execute the pending plan from /plan' },
     // Project intelligence
     { name: 'scan', description: 'Scan project structure and generate summary' },
     { name: 'review', description: 'Run code review on project or specific files', input: { hint: '[file…]' } },

package/dist/api/index.js

@@ -593,6 +593,13 @@ async function chatAnthropic(message, history, model, apiKey, onChunk, abortSign
         headers['x-api-key'] = apiKey;
     }
     try {
+        // Anthropic prompt caching: wrap system as an array with a
+        // `cache_control` marker so the static system prompt (typically large
+        // and stable across a session) is cached. Below 1024 input tokens
+        // Anthropic silently skips caching — no error.
+        const cachedSystem = useNativeSystem
+            ? { system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }] }
+            : {};
         const response = await fetch(`${baseUrl}/v1/messages`, {
             method: 'POST',
             headers,
@@ -602,7 +609,7 @@ async function chatAnthropic(message, history, model, apiKey, onChunk, abortSign
                 max_tokens: maxTokens,
                 temperature,
                 stream,
-                ...(useNativeSystem ? { system: systemPrompt } : {}),
+                ...cachedSystem,
             }),
             signal: controller.signal,
         });
@@ -649,6 +656,8 @@ async function handleAnthropicStream(body, onChunk) {
     let buffer = '';
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
     let streamModel = '';
     while (true) {
         const { done, value } = await reader.read();
@@ -669,9 +678,13 @@ async function handleAnthropicStream(body, onChunk) {
                             onChunk(text);
                         }
                     }
-                    // message_start contains input_tokens
+                    // message_start contains input_tokens (and cache create/read
+                    // when prompt caching is in play).
                     if (parsed.type === 'message_start' && parsed.message?.usage) {
-                        inputTokens = parsed.message.usage.input_tokens || 0;
+                        const u = parsed.message.usage;
+                        inputTokens = u.input_tokens || 0;
+                        cacheCreationTokens = u.cache_creation_input_tokens || 0;
+                        cacheReadTokens = u.cache_read_input_tokens || 0;
                         streamModel = parsed.message.model || '';
                     }
                     // message_delta contains output_tokens
@@ -686,8 +699,15 @@ async function handleAnthropicStream(body, onChunk) {
         }
     }
     // Record token usage
-    if (inputTokens > 0 || outputTokens > 0) {
-        recordTokenUsage({ promptTokens: inputTokens, completionTokens: outputTokens, totalTokens: inputTokens + outputTokens }, streamModel || 'unknown', config.get('provider'));
+    if (inputTokens > 0 || outputTokens > 0 || cacheReadTokens > 0 || cacheCreationTokens > 0) {
+        const totalPrompt = inputTokens + cacheCreationTokens + cacheReadTokens;
+        recordTokenUsage({
+            promptTokens: totalPrompt,
+            completionTokens: outputTokens,
+            totalTokens: totalPrompt + outputTokens,
+            cacheCreationTokens: cacheCreationTokens || undefined,
+            cacheReadTokens: cacheReadTokens || undefined,
+        }, streamModel || 'unknown', config.get('provider'));
     }
     // Strip <think> tags from MiniMax responses
     return stripThinkTags(chunks.join(''));

package/dist/renderer/App.js

@@ -82,6 +82,17 @@ const COMMAND_DESCRIPTIONS = {
     'profile': 'Save/load settings profiles',
     'tasks': 'Show pending tasks from codeep.dev dashboard',
     'sync': 'Sync learning preferences and profiles to codeep.dev',
+    // 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',
+    'checkpoint': 'Snapshot the session (conversation + provider/model + git HEAD)',
+    'checkpoints': 'List saved checkpoints for this workspace',
+    'rewind': 'Restore conversation from a saved checkpoint',
+    'hooks': 'List installed lifecycle hooks (.codeep/hooks/<event>.sh)',
+    'mcp': 'Manage MCP servers (browse, install, add, remove, resources, prompts)',
+    'openrouter': 'Tune OpenRouter routing (preferred / ignore providers, fallbacks, privacy)',
+    'plan': 'Generate a numbered plan for a task — review before /go executes it',
+    'go': 'Execute the pending plan from /plan',
 };
 import { helpCategories, keyboardShortcuts } from './components/Help.js';
 import { handleSettingsKey, SETTINGS } from './components/Settings.js';
@@ -217,6 +228,12 @@ export class App {
         'provider', 'model', 'protocol', 'lang', 'grant', 'login', 'logout',
         'context-save', 'context-load', 'context-clear', 'learn',
         'cost', 'tasks', 'account', 'sync',
+        // 2.0 — extensions, checkpoints, MCP, custom commands, OpenRouter prefs.
+        // Keep in lockstep with COMMAND_DESCRIPTIONS below and helpCategories.
+        'compact', 'commands', 'checkpoint', 'checkpoints', 'rewind',
+        'hooks', 'mcp', 'openrouter',
+        // 2.0.2 — plan mode.
+        'plan', 'go',
         'c', 't', 'd', 'r', 'f', 'e', 'o', 'b', 'p',
     ];
     constructor(options) {

package/dist/renderer/commands.js

@@ -216,6 +216,65 @@ export async function handleCommand(command, args, ctx) {
             runAgentTask(args.join(' '), true, ctx, () => null, () => { });
             break;
         }
+        case 'plan': {
+            // Plan mode: ask the model for a plan, surface it, hold as pending.
+            // The user runs /go to execute or /plan <revised> to revise. See
+            // src/utils/planMode.ts for the rationale + system prompt.
+            if (!args.length) {
+                const { getPendingPlan } = await import('../utils/planMode.js');
+                const cur = getPendingPlan();
+                if (cur) {
+                    ctx.app.addMessage({
+                        role: 'system',
+                        content: `**Pending plan for:** _${cur.task}_\n\n${cur.plan}\n\n---\nRun \`/go\` to execute, or \`/plan <revised task>\` to revise.`,
+                    });
+                }
+                else {
+                    ctx.app.notify('Usage: /plan <task> — generates a plan you can review, then /go to execute.');
+                }
+                return;
+            }
+            if (ctx.isAgentRunning()) {
+                ctx.app.notify('Agent already running. Use /stop first.');
+                return;
+            }
+            const task = args.join(' ');
+            ctx.app.addMessage({ role: 'user', content: `/plan ${task}` });
+            ctx.app.notify('Generating plan…');
+            try {
+                const { generatePlan } = await import('../utils/planMode.js');
+                const plan = await generatePlan(task);
+                ctx.app.addMessage({
+                    role: 'assistant',
+                    content: `${plan}\n\n---\nRun \`/go\` to execute this plan, or \`/plan <revised task>\` to refine it.`,
+                });
+            }
+            catch (err) {
+                ctx.app.notify(`Plan generation failed: ${err.message}`);
+            }
+            break;
+        }
+        case 'go': {
+            // Execute the pending plan from /plan. The agent loop sees the
+            // task + plan as a single prompt, so MCP tools, hooks, permissions,
+            // and verification all apply unchanged.
+            const { getPendingPlan, composeExecutionPrompt, clearPendingPlan } = await import('../utils/planMode.js');
+            const cur = getPendingPlan();
+            if (!cur) {
+                ctx.app.notify('No pending plan. Run `/plan <task>` first.');
+                return;
+            }
+            if (ctx.isAgentRunning()) {
+                ctx.app.notify('Agent already running. Use /stop first.');
+                return;
+            }
+            const prompt = composeExecutionPrompt(cur);
+            clearPendingPlan();
+            ctx.app.notify(`Executing plan for: ${cur.task.slice(0, 80)}${cur.task.length > 80 ? '…' : ''}`);
+            const { runAgentTask } = await import('./agentExecution.js');
+            runAgentTask(prompt, false, ctx, () => null, () => { });
+            break;
+        }
         case 'stop': {
             if (ctx.isAgentRunning() && ctx.abortController) {
                 ctx.abortController.abort();
@@ -1685,6 +1744,296 @@ Describe what this skill does. The agent reads this body verbatim when it invoke
             ctx.app.addMessage({ role: 'system', content: formatCommandList(loadCustomCommands(ctx.projectPath)) });
             break;
         }
+        case 'mcp': {
+            // Mirrors the ACP `/mcp` handler in src/acp/commands.ts. In TUI the
+            // session id is the constant `codeep-tui` (the same one main.ts uses
+            // when it spawns project MCP servers in the background) and the
+            // workspace root is ctx.projectPath. Without a project we can still
+            // browse the marketplace, but anything that mutates project config
+            // refuses with a clear message.
+            const sub = args[0]?.toLowerCase();
+            const TUI_SESSION = 'codeep-tui';
+            const projectPath = ctx.projectPath;
+            const requireProject = () => {
+                if (!projectPath) {
+                    ctx.app.notify('Open a project (cd into it before running codeep) to add or modify MCP servers.');
+                    return false;
+                }
+                return true;
+            };
+            const { addProjectMcpServer, removeProjectMcpServer, loadMcpServerConfig } = await import('../utils/mcpConfig.js');
+            const { registerSessionServers } = await import('../utils/mcpRegistry.js');
+            if (sub === 'add') {
+                if (!requireProject())
+                    break;
+                const name = args[1];
+                const command = args[2];
+                if (!name || !command) {
+                    ctx.app.addMessage({ role: 'system', content: 'Usage: `/mcp add <name> <command> [args...]` — e.g. `/mcp add fs npx @modelcontextprotocol/server-filesystem /path`' });
+                    break;
+                }
+                const extraArgs = args.slice(3);
+                addProjectMcpServer(projectPath, { name, command, args: extraArgs });
+                ctx.app.notify(`Saved MCP server ${name} to .codeep/mcp_servers.json. Spawning…`);
+                const merged = loadMcpServerConfig(projectPath);
+                const { registered, errors } = await registerSessionServers(TUI_SESSION, merged, { workspaceRoot: projectPath });
+                const ok = registered.filter(t => t.serverName === name);
+                const failed = errors.find(e => e.server === name);
+                ctx.app.addMessage({
+                    role: 'system',
+                    content: failed
+                        ? `Saved \`${name}\` but spawn failed: \`${failed.error}\``
+                        : `Added \`${name}\` (${ok.length} tool${ok.length === 1 ? '' : 's'} available).`,
+                });
+                break;
+            }
+            if (sub === 'remove') {
+                if (!requireProject())
+                    break;
+                const name = args[1];
+                if (!name) {
+                    ctx.app.addMessage({ role: 'system', content: 'Usage: `/mcp remove <name>`' });
+                    break;
+                }
+                const removed = removeProjectMcpServer(projectPath, name);
+                if (!removed) {
+                    ctx.app.addMessage({ role: 'system', content: `No project-scoped MCP server named \`${name}\`.` });
+                    break;
+                }
+                const merged = loadMcpServerConfig(projectPath);
+                await registerSessionServers(TUI_SESSION, merged, { workspaceRoot: projectPath });
+                ctx.app.addMessage({ role: 'system', content: `Removed \`${name}\` from project config and stopped its process.` });
+                break;
+            }
+            if (sub === 'browse') {
+                const { formatMarketplaceList, findMarketplaceEntry, formatMarketplaceEntry, MCP_MARKETPLACE } = await import('../utils/mcpMarketplace.js');
+                const detail = args[1];
+                if (detail) {
+                    const entry = findMarketplaceEntry(detail);
+                    if (!entry) {
+                        ctx.app.addMessage({ role: 'system', content: `Marketplace id not found: \`${detail}\`. Run \`/mcp browse\` for the list.` });
+                    }
+                    else {
+                        const argHints = entry.argHints?.map(h => `<${h.placeholder ?? 'arg'}>`).join(' ') ?? '';
+                        ctx.app.addMessage({ role: 'system', content: formatMarketplaceEntry(entry) + `\n\nInstall with \`/mcp install ${entry.id} ${argHints}\`` });
+                    }
+                    break;
+                }
+                ctx.app.addMessage({ role: 'system', content: formatMarketplaceList() + `\n\nRun \`/mcp browse <id>\` for details or \`/mcp install <id> [args]\` to install. Total: ${MCP_MARKETPLACE.length}.` });
+                break;
+            }
+            if (sub === 'install') {
+                if (!requireProject())
+                    break;
+                const id = args[1];
+                if (!id) {
+                    ctx.app.addMessage({ role: 'system', content: 'Usage: `/mcp install <id> [extra args...]` — run `/mcp browse` to see ids.' });
+                    break;
+                }
+                const { findMarketplaceEntry } = await import('../utils/mcpMarketplace.js');
+                const entry = findMarketplaceEntry(id);
+                if (!entry) {
+                    ctx.app.addMessage({ role: 'system', content: `Marketplace id not found: \`${id}\`. Run \`/mcp browse\` for the list.` });
+                    break;
+                }
+                const extraArgs = args.slice(2);
+                const fullArgs = [...(entry.server.args ?? []), ...extraArgs];
+                addProjectMcpServer(projectPath, {
+                    name: entry.id,
+                    command: entry.server.command,
+                    args: fullArgs,
+                    env: entry.server.env,
+                    url: entry.server.url,
+                    headers: entry.server.headers,
+                });
+                ctx.app.notify(`Saved ${entry.id} to project config. Spawning…`);
+                const merged = loadMcpServerConfig(projectPath);
+                const { registered, errors } = await registerSessionServers(TUI_SESSION, merged, { workspaceRoot: projectPath });
+                const failed = errors.find(e => e.server === entry.id);
+                const lines = [];
+                if (failed) {
+                    lines.push(`Saved \`${entry.id}\` but spawn failed: \`${failed.error}\``);
+                }
+                else {
+                    const ok = registered.filter(t => t.serverName === entry.id);
+                    lines.push(`Installed **${entry.name}** (\`${entry.id}\`) — ${ok.length} tool${ok.length === 1 ? '' : 's'} available.`);
+                }
+                if (entry.envNotes?.length) {
+                    lines.push('', '**Environment variables you may need:**');
+                    for (const e of entry.envNotes) {
+                        const req = e.required ? ' (required)' : '';
+                        lines.push(`- \`${e.name}\`${req} — ${e.description}`);
+                    }
+                }
+                ctx.app.addMessage({ role: 'system', content: lines.join('\n') });
+                break;
+            }
+            if (sub === 'reload') {
+                if (!requireProject())
+                    break;
+                ctx.app.notify('Reloading MCP server config…');
+                const merged = loadMcpServerConfig(projectPath);
+                const { registered, errors } = await registerSessionServers(TUI_SESSION, merged, { workspaceRoot: projectPath });
+                const lines = [`## MCP reloaded`, '', `**${registered.length}** tool${registered.length === 1 ? '' : 's'} from **${merged.length}** server${merged.length === 1 ? '' : 's'}.`];
+                if (errors.length > 0) {
+                    lines.push('', '### Failed servers');
+                    for (const e of errors)
+                        lines.push(`- **${e.server}** — \`${e.error}\``);
+                }
+                ctx.app.addMessage({ role: 'system', content: lines.join('\n') });
+                break;
+            }
+            if (sub === 'resources') {
+                const { getSessionResources, awaitSessionReady } = await import('../utils/mcpRegistry.js');
+                await awaitSessionReady(TUI_SESSION);
+                const groups = await getSessionResources(TUI_SESSION);
+                if (groups.length === 0) {
+                    ctx.app.addMessage({ role: 'system', content: '_No MCP server in this session exposes resources._' });
+                    break;
+                }
+                const lines = ['## MCP resources', ''];
+                for (const g of groups) {
+                    lines.push(`**${g.serverName}** — ${g.resources.length} resource${g.resources.length === 1 ? '' : 's'}`);
+                    for (const r of g.resources) {
+                        const label = r.name ? `${r.name} — ` : '';
+                        const mime = r.mimeType ? ` (${r.mimeType})` : '';
+                        lines.push(`- ${label}\`${r.uri}\`${mime}${r.description ? ` — ${r.description}` : ''}`);
+                    }
+                    lines.push('');
+                }
+                lines.push('Read one with `/mcp read <uri>`.');
+                ctx.app.addMessage({ role: 'system', content: lines.join('\n').trim() });
+                break;
+            }
+            if (sub === 'read') {
+                const uri = args[1];
+                if (!uri) {
+                    ctx.app.addMessage({ role: 'system', content: 'Usage: `/mcp read <uri>` — run `/mcp resources` to see available URIs.' });
+                    break;
+                }
+                const { readSessionResource } = await import('../utils/mcpRegistry.js');
+                try {
+                    const contents = await readSessionResource(TUI_SESSION, uri);
+                    if (contents.length === 0) {
+                        ctx.app.addMessage({ role: 'system', content: `_No content returned for \`${uri}\`._` });
+                        break;
+                    }
+                    const lines = [`## Resource: \`${uri}\``, ''];
+                    for (const c of contents) {
+                        if (c.text !== undefined) {
+                            const fence = c.mimeType?.includes('json') ? 'json' : c.mimeType?.includes('markdown') ? 'markdown' : '';
+                            lines.push('```' + fence);
+                            lines.push(c.text);
+                            lines.push('```');
+                        }
+                        else if (c.blob) {
+                            lines.push(`_(${c.mimeType ?? 'binary'} blob, ${c.blob.length} base64 chars — not rendered)_`);
+                        }
+                    }
+                    ctx.app.addMessage({ role: 'system', content: lines.join('\n') });
+                }
+                catch (err) {
+                    ctx.app.addMessage({ role: 'system', content: `Failed to read \`${uri}\`: ${err.message}` });
+                }
+                break;
+            }
+            if (sub === 'prompts') {
+                const { getSessionPrompts, awaitSessionReady } = await import('../utils/mcpRegistry.js');
+                await awaitSessionReady(TUI_SESSION);
+                const groups = await getSessionPrompts(TUI_SESSION);
+                if (groups.length === 0) {
+                    ctx.app.addMessage({ role: 'system', content: '_No MCP server in this session exposes prompt templates._' });
+                    break;
+                }
+                const lines = ['## MCP prompt templates', ''];
+                for (const g of groups) {
+                    lines.push(`**${g.serverName}** — ${g.prompts.length} prompt${g.prompts.length === 1 ? '' : 's'}`);
+                    for (const p of g.prompts) {
+                        const argList = p.arguments?.length
+                            ? ` (${p.arguments.map(a => a.required ? a.name : `[${a.name}]`).join(', ')})`
+                            : '';
+                        lines.push(`- \`${p.name}\`${argList}${p.description ? ` — ${p.description}` : ''}`);
+                    }
+                    lines.push('');
+                }
+                lines.push('Materialise one with `/mcp prompt <server> <name> [key=value...]`.');
+                ctx.app.addMessage({ role: 'system', content: lines.join('\n').trim() });
+                break;
+            }
+            if (sub === 'prompt') {
+                const serverName = args[1];
+                const name = args[2];
+                if (!serverName || !name) {
+                    ctx.app.addMessage({ role: 'system', content: 'Usage: `/mcp prompt <server> <name> [key=value ...]`' });
+                    break;
+                }
+                const promptArgs = {};
+                for (const tok of args.slice(3)) {
+                    const eq = tok.indexOf('=');
+                    if (eq > 0)
+                        promptArgs[tok.slice(0, eq)] = tok.slice(eq + 1);
+                }
+                const { getSessionPrompt } = await import('../utils/mcpRegistry.js');
+                try {
+                    const { description, messages } = await getSessionPrompt(TUI_SESSION, serverName, name, promptArgs);
+                    const lines = [`## Prompt \`${serverName}/${name}\``];
+                    if (description)
+                        lines.push(`_${description}_`);
+                    lines.push('');
+                    for (const m of messages) {
+                        const text = typeof m.content?.text === 'string' ? m.content.text : JSON.stringify(m.content);
+                        lines.push(`**${m.role}:** ${text}`);
+                        lines.push('');
+                    }
+                    ctx.app.addMessage({ role: 'system', content: lines.join('\n').trim() });
+                }
+                catch (err) {
+                    ctx.app.addMessage({ role: 'system', content: `Failed to materialise prompt: ${err.message}` });
+                }
+                break;
+            }
+            // Default: list servers + tools for the current session.
+            const { getSessionTools, getSessionRegistrationErrors, awaitSessionReady } = await import('../utils/mcpRegistry.js');
+            await awaitSessionReady(TUI_SESSION);
+            const tools = await getSessionTools(TUI_SESSION);
+            const mcpErrors = getSessionRegistrationErrors(TUI_SESSION);
+            if (tools.length === 0 && mcpErrors.length === 0) {
+                ctx.app.addMessage({
+                    role: 'system',
+                    content: [
+                        '_No MCP servers connected to this session._',
+                        '',
+                        'Add one with `/mcp add <name> <command> [args...]` — it persists to `.codeep/mcp_servers.json`.',
+                        'Or browse the marketplace with `/mcp browse` and install with `/mcp install <id>`.',
+                    ].join('\n'),
+                });
+                break;
+            }
+            const lines = ['## MCP servers', ''];
+            if (tools.length > 0) {
+                const byServer = new Map();
+                for (const t of tools) {
+                    if (!byServer.has(t.serverName))
+                        byServer.set(t.serverName, []);
+                    byServer.get(t.serverName).push(t);
+                }
+                for (const [serverName, serverTools] of byServer) {
+                    lines.push(`**${serverName}** — ${serverTools.length} tool${serverTools.length === 1 ? '' : 's'}`);
+                    for (const t of serverTools) {
+                        const desc = t.description ? ` — ${t.description}` : '';
+                        lines.push(`- \`${t.agentName}\`${desc}`);
+                    }
+                    lines.push('');
+                }
+            }
+            if (mcpErrors.length > 0) {
+                lines.push('### Failed servers');
+                for (const e of mcpErrors)
+                    lines.push(`- **${e.server}** — \`${e.error}\``);
+            }
+            ctx.app.addMessage({ role: 'system', content: lines.join('\n').trim() });
+            break;
+        }
         default: {
             // 1. Try custom user command (project + global Markdown templates).
             const { findCustomCommand, expandCommand } = await import('../utils/customCommands.js');

package/dist/renderer/components/Help.js

@@ -29,6 +29,16 @@ export const helpCategories = [
             { key: '/rename <name>', description: 'Rename current session' },
             { key: '/search <term>', description: 'Search chat history' },
             { key: '/export [md|json|txt]', description: 'Export chat' },
+            { key: '/compact [keepN]', description: 'AI-summarize older messages to free up context (keeps last N)' },
+        ],
+    },
+    {
+        title: 'Checkpoints (2.0)',
+        items: [
+            { key: '/checkpoint [name]', description: 'Snapshot conversation + provider/model + git HEAD' },
+            { key: '/checkpoints', description: 'List saved checkpoints in this workspace' },
+            { key: '/rewind <id>', description: 'Restore conversation from a checkpoint' },
+            { key: '/checkpoint delete <id>', description: 'Delete a saved checkpoint' },
         ],
     },
     {
@@ -36,6 +46,8 @@ export const helpCategories = [
         items: [
             { key: '/agent <task>', description: 'Run agent with task' },
             { key: '/agent-dry <task>', description: 'Dry run (no changes)' },
+            { key: '/plan <task>', description: 'Generate a plan first — review before /go executes' },
+            { key: '/go', description: 'Execute the pending plan from /plan' },
             { key: '/stop', description: 'Stop running agent' },
             { key: '/undo', description: 'Undo last agent action' },
             { key: '/undo-all', description: 'Undo all agent actions' },
@@ -110,6 +122,24 @@ export const helpCategories = [
             { key: '/logout', description: 'Logout from provider' },
             { key: '/profile save <name>', description: 'Save current provider+model as profile' },
             { key: '/profile list', description: 'List saved profiles' },
+            { key: '/openrouter', description: 'OpenRouter routing prefs (prefer/ignore providers, fallbacks, privacy)' },
+        ],
+    },
+    {
+        title: 'Extensions & MCP (2.0)',
+        items: [
+            { key: '/mcp', description: 'List connected MCP servers + their tools' },
+            { key: '/mcp browse [id]', description: 'Browse marketplace (12 servers) or show one' },
+            { key: '/mcp install <id> [args]', description: 'Install a marketplace server into this project' },
+            { key: '/mcp add <name> <cmd>', description: 'Add a custom MCP server (npx, binary, etc.)' },
+            { key: '/mcp remove <name>', description: 'Remove a project-scoped MCP server' },
+            { key: '/mcp reload', description: 'Re-read .codeep/mcp_servers.json (after manual edit)' },
+            { key: '/mcp resources', description: 'List resources exposed by connected servers' },
+            { key: '/mcp read <uri>', description: 'Read one MCP resource' },
+            { key: '/mcp prompts', description: 'List prompt templates exposed by servers' },
+            { key: '/mcp prompt <server> <name>', description: 'Materialize a prompt with arguments (key=value)' },
+            { key: '/hooks', description: 'List installed lifecycle hooks (.codeep/hooks/<event>.sh)' },
+            { key: '/commands', description: 'List custom slash commands (.codeep/commands/*.md)' },
         ],
     },
     {

package/dist/utils/agentChat.js

@@ -301,9 +301,25 @@ additionalTools) {
         }
         else {
             endpoint = `${baseUrl}/v1/messages`;
+            // Anthropic prompt caching. Two cache breakpoints:
+            //   1. `system` (largest stable block — system prompt + skills catalog)
+            //   2. last tool in `tools` (Anthropic caches everything up to and
+            //      including the marker, so this caches the entire tools array)
+            // Cache hits cost 0.1× input. Misses ("cache creation") cost 1.25×.
+            // Net win after the 2nd same-shape request. Below 1024 input tokens
+            // Anthropic silently skips caching — no error path to handle.
+            const anthropicTools = getAnthropicTools(additionalTools);
+            const cachedTools = anthropicTools.length > 0
+                ? [
+                    ...anthropicTools.slice(0, -1),
+                    { ...anthropicTools[anthropicTools.length - 1], cache_control: { type: 'ephemeral' } },
+                ]
+                : anthropicTools;
             body = {
-                model, system: systemPrompt, messages,
-                tools: getAnthropicTools(additionalTools), stream: useStreaming,
+                model,
+                system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
+                messages,
+                tools: cachedTools, stream: useStreaming,
                 ...tempParam, max_tokens: getEffectiveMaxTokens(providerId, Math.max(config.get('maxTokens'), 16384)),
             };
         }
@@ -435,10 +451,15 @@ export async function agentChatFallback(messages, systemPrompt, onChunk, abortSi
         }
         else {
             endpoint = `${baseUrl}/v1/messages`;
+            // Fallback path injects system+tools as the first user message
+            // (no native tool API). Cache that block — it's large and stable.
             body = {
                 model,
                 messages: [
-                    { role: 'user', content: fallbackPrompt },
+                    {
+                        role: 'user',
+                        content: [{ type: 'text', text: fallbackPrompt, cache_control: { type: 'ephemeral' } }],
+                    },
                     { role: 'assistant', content: 'Understood. I will use the tools as specified.' },
                     ...messages,
                 ],

package/dist/utils/agentStream.js

@@ -169,13 +169,30 @@ export async function handleAnthropicAgentStream(body, onChunk, model, providerI
             const data = line.slice(6);
             try {
                 const parsed = JSON.parse(data);
-                // message_start has input tokens; message_delta has output tokens — merge both
+                // message_start has input tokens (incl. cache create/read fields if
+                // prompt caching is in use); message_delta has output tokens —
+                // merge both so extractAnthropicUsage sees the full picture.
                 if (parsed.type === 'message_start' && parsed.message?.usage) {
-                    usageData = { usage: { input_tokens: parsed.message.usage.input_tokens || 0, output_tokens: 0 } };
+                    const u = parsed.message.usage;
+                    usageData = {
+                        usage: {
+                            input_tokens: u.input_tokens || 0,
+                            output_tokens: 0,
+                            cache_creation_input_tokens: u.cache_creation_input_tokens || 0,
+                            cache_read_input_tokens: u.cache_read_input_tokens || 0,
+                        },
+                    };
                 }
                 else if (parsed.type === 'message_delta' && parsed.usage) {
-                    const inputTokens = usageData?.usage?.input_tokens || 0;
-                    usageData = { usage: { input_tokens: inputTokens, output_tokens: parsed.usage.output_tokens || 0 } };
+                    const prev = usageData?.usage ?? {};
+                    usageData = {
+                        usage: {
+                            input_tokens: prev.input_tokens || 0,
+                            output_tokens: parsed.usage.output_tokens || 0,
+                            cache_creation_input_tokens: prev.cache_creation_input_tokens || 0,
+                            cache_read_input_tokens: prev.cache_read_input_tokens || 0,
+                        },
+                    };
                 }
                 if (parsed.type === 'content_block_start') {
                     const block = parsed.content_block;

package/dist/utils/planMode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Plan mode — explicit pre-execution preview.
+ *
+ * Flow:
+ *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
+ *      (no tool calls, no file changes) and surface it to the user.
+ *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
+ *      the current process.
+ *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
+ *      `/go` hands the original task + approved plan to the regular
+ *      agent loop as a single prompt, so the existing tool execution,
+ *      verification, and permission paths apply unchanged.
+ *
+ * Why this design (MVP):
+ *   - Zero changes to the agent loop, MCP wiring, or ACP server.
+ *   - Plan rendering reuses the chat markdown renderer (no new TUI
+ *     panel to maintain).
+ *   - Edit flow is just "/plan <revised task>" — generates a new plan
+ *     that replaces the pending one; user pays one extra LLM call but
+ *     gets human-readable revision history in the chat above.
+ *   - When we ship a proper plan-mode UI later (TUI panel with
+ *     Accept/Edit/Reject buttons + per-step progress), it can keep
+ *     using this module as the backend.
+ */
+export interface PendingPlan {
+    task: string;
+    plan: string;
+    createdAt: number;
+}
+/**
+ * Ask the model for a plan for the given task. Stores the (task, plan)
+ * pair as the pending plan so a subsequent `/go` can execute it.
+ * Throws on chat failure — caller renders the error.
+ */
+export declare function generatePlan(task: string, onChunk?: (text: string) => void): Promise<string>;
+export declare function getPendingPlan(): PendingPlan | null;
+export declare function clearPendingPlan(): void;
+/**
+ * Compose the prompt the agent loop receives when the user runs `/go`.
+ * The agent treats this as a normal task, so tool calls / verification /
+ * permissions / hooks all flow through the existing paths — we just
+ * front-load the plan as context so the model doesn't re-plan
+ * implicitly.
+ */
+export declare function composeExecutionPrompt(plan: PendingPlan): string;

package/dist/utils/planMode.js

@@ -0,0 +1,94 @@
+/**
+ * Plan mode — explicit pre-execution preview.
+ *
+ * Flow:
+ *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
+ *      (no tool calls, no file changes) and surface it to the user.
+ *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
+ *      the current process.
+ *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
+ *      `/go` hands the original task + approved plan to the regular
+ *      agent loop as a single prompt, so the existing tool execution,
+ *      verification, and permission paths apply unchanged.
+ *
+ * Why this design (MVP):
+ *   - Zero changes to the agent loop, MCP wiring, or ACP server.
+ *   - Plan rendering reuses the chat markdown renderer (no new TUI
+ *     panel to maintain).
+ *   - Edit flow is just "/plan <revised task>" — generates a new plan
+ *     that replaces the pending one; user pays one extra LLM call but
+ *     gets human-readable revision history in the chat above.
+ *   - When we ship a proper plan-mode UI later (TUI panel with
+ *     Accept/Edit/Reject buttons + per-step progress), it can keep
+ *     using this module as the backend.
+ */
+import { chat } from '../api/index.js';
+const PLAN_SYSTEM_PROMPT = `You are in PLAN MODE.
+
+The user has given you a task. **Do not execute anything.** Do not call
+tools. Do not modify files. Do not run shell commands. Instead, produce
+a numbered plan of the steps you would take, so the user can review and
+approve before any changes happen.
+
+Format your response as Markdown:
+
+## Plan: <one-line summary of the task>
+
+1. **<short step name>** — what you'd do (e.g. read file, edit lines, run command).
+   _Why:_ rationale (1 sentence).
+   _Expected outcome:_ what the user should see after this step.
+
+2. **<step name>** — …
+
+(continue numbering)
+
+End with these three lines (verbatim labels, fill in values):
+
+**Risk:** <low | medium | high> — <one-sentence reason; e.g. "schema change, requires migration">
+**Files affected:** <comma-separated list of paths you'd touch, or "none">
+**Commands run:** <comma-separated shell commands, or "none">
+
+Rules:
+- Be concrete. Reference real file paths from the project if you know them.
+- Keep steps small enough that each maps to one or two tool calls when
+  later executed.
+- If the task is ambiguous, list the assumption(s) you're making at the
+  top of the plan ("Assumes: ...") so the user can correct before /go.
+- Do NOT produce code — describe what you'd change, not the change
+  itself. Code generation belongs in execution, not planning.
+- If the task is trivial (single-file rename, single-line edit), say so
+  in one sentence and skip the formal plan — don't bloat tiny work.`;
+let pending = null;
+/**
+ * Ask the model for a plan for the given task. Stores the (task, plan)
+ * pair as the pending plan so a subsequent `/go` can execute it.
+ * Throws on chat failure — caller renders the error.
+ */
+export async function generatePlan(task, onChunk) {
+    const history = [
+        { role: 'system', content: PLAN_SYSTEM_PROMPT },
+    ];
+    const plan = await chat(task, history, onChunk);
+    pending = { task, plan, createdAt: Date.now() };
+    return plan;
+}
+export function getPendingPlan() {
+    return pending;
+}
+export function clearPendingPlan() {
+    pending = null;
+}
+/**
+ * Compose the prompt the agent loop receives when the user runs `/go`.
+ * The agent treats this as a normal task, so tool calls / verification /
+ * permissions / hooks all flow through the existing paths — we just
+ * front-load the plan as context so the model doesn't re-plan
+ * implicitly.
+ */
+export function composeExecutionPrompt(plan) {
+    return `${plan.task}
+
+I've reviewed the following plan and approved it. Execute it step by step. If any step turns out to be wrong or impossible mid-execution, stop and report — don't silently improvise.
+
+${plan.plan}`;
+}

package/dist/utils/skillBundlesCloud.d.ts

@@ -24,10 +24,13 @@ export interface RemoteSkill {
     updated_at: string;
 }
 /**
- * Publish a project-scoped skill bundle to codeep.dev.
- * The bundle MUST exist under `<workspaceRoot>/.codeep/skills/<slug>/SKILL.md`
- * — global skills aren't publishable from this helper (intentional: users
- * publish work from a project they're owning, not from their global hoard).
+ * Publish a skill bundle to codeep.dev. The bundle may be project-scoped
+ * (`<workspaceRoot>/.codeep/skills/<slug>/SKILL.md`) or global
+ * (`~/.codeep/skills/<slug>/SKILL.md`) — either is publishable. The
+ * `--public` flag (translated into `opts.isPublic`) is the user's
+ * explicit consent gate; we don't gate further on bundle scope. If both
+ * exist with the same slug, the project copy wins (mirrors the rest of
+ * the bundle-loading flow).
  */
 export declare function publishBundle(workspaceRoot: string, slug: string, opts?: {
     isPublic?: boolean;

package/dist/utils/skillBundlesCloud.js

@@ -17,18 +17,24 @@ import { getSyncToken } from '../config/index.js';
 import { findSkillBundle } from './skillBundles.js';
 const API_BASE = 'https://codeep.dev';
 /**
- * Publish a project-scoped skill bundle to codeep.dev.
- * The bundle MUST exist under `<workspaceRoot>/.codeep/skills/<slug>/SKILL.md`
- * — global skills aren't publishable from this helper (intentional: users
- * publish work from a project they're owning, not from their global hoard).
+ * Publish a skill bundle to codeep.dev. The bundle may be project-scoped
+ * (`<workspaceRoot>/.codeep/skills/<slug>/SKILL.md`) or global
+ * (`~/.codeep/skills/<slug>/SKILL.md`) — either is publishable. The
+ * `--public` flag (translated into `opts.isPublic`) is the user's
+ * explicit consent gate; we don't gate further on bundle scope. If both
+ * exist with the same slug, the project copy wins (mirrors the rest of
+ * the bundle-loading flow).
  */
 export async function publishBundle(workspaceRoot, slug, opts = {}) {
     const token = getSyncToken();
     if (!token)
         return { ok: false, error: 'Not linked to codeep.dev — run `codeep account` first.' };
     const bundle = findSkillBundle(slug, workspaceRoot);
-    if (!bundle || bundle.scope !== 'project') {
-        return { ok: false, error: `Skill bundle "${slug}" not found in this project. Run \`/skills create-bundle ${slug}\` first.` };
+    if (!bundle) {
+        return {
+            ok: false,
+            error: `Skill bundle "${slug}" not found in either \`.codeep/skills/${slug}/\` (project) or \`~/.codeep/skills/${slug}/\` (global). Run \`/skills create-bundle ${slug}\` to scaffold one, or check \`/skills bundles\` to see what's available.`,
+        };
     }
     // Build the SKILL.md text we'll publish. We re-serialise from the loaded
     // bundle rather than reading the file again — that way frontmatter

package/dist/utils/tokenTracker.d.ts

@@ -5,6 +5,13 @@ export interface TokenUsage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Anthropic prompt caching: tokens written to the cache on this call
+     *  (billed at ~1.25× input rate). Undefined for providers that don't
+     *  support caching or for calls below the cache size threshold. */
+    cacheCreationTokens?: number;
+    /** Anthropic prompt caching: tokens read from cache on this call
+     *  (billed at ~0.1× input rate — the big savings live here). */
+    cacheReadTokens?: number;
 }
 export interface SessionTokenStats {
     totalPromptTokens: number;
@@ -18,6 +25,9 @@ interface TokenRecord {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Anthropic prompt caching breakdown — see TokenUsage. */
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
     model: string;
     provider: string;
     /** Authoritative per-call USD from the provider (OpenRouter), if available. */
@@ -59,6 +69,19 @@ export interface ProviderCostBreakdown {
  * Get cost breakdown grouped by provider/model
  */
 export declare function getCostBreakdown(): ProviderCostBreakdown[];
+/**
+ * Aggregate Anthropic prompt-caching stats for the current session.
+ * Returns the breakdown plus an estimate of what the input billing would
+ * have been *without* caching, so we can surface "you saved $X" to the
+ * user.
+ */
+export interface CacheStats {
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    /** Sum of estimatedSavings across all Anthropic-priced records. */
+    estimatedSavingsUsd: number;
+}
+export declare function getCacheStats(): CacheStats;
 /**
  * Get session stats
  */

package/dist/utils/tokenTracker.js

@@ -81,6 +81,8 @@ export function recordTokenUsage(usage, model, provider, actualCostUsd) {
         promptTokens: usage.promptTokens,
         completionTokens: usage.completionTokens,
         totalTokens: usage.totalTokens,
+        cacheCreationTokens: usage.cacheCreationTokens,
+        cacheReadTokens: usage.cacheReadTokens,
         model,
         provider,
         actualCostUsd,
@@ -104,10 +106,19 @@ export function extractOpenAIUsage(data) {
  */
 export function extractAnthropicUsage(data) {
     if (data?.usage) {
+        const inputTokens = data.usage.input_tokens || 0;
+        const outputTokens = data.usage.output_tokens || 0;
+        const cacheCreation = data.usage.cache_creation_input_tokens || 0;
+        const cacheRead = data.usage.cache_read_input_tokens || 0;
+        // Anthropic returns input_tokens EXCLUSIVE of cache creation and cache
+        // read tokens — they're reported separately. Total prompt = sum of all
+        // three so our context window math doesn't undercount.
         return {
-            promptTokens: data.usage.input_tokens || 0,
-            completionTokens: data.usage.output_tokens || 0,
-            totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+            promptTokens: inputTokens + cacheCreation + cacheRead,
+            completionTokens: outputTokens,
+            totalTokens: inputTokens + cacheCreation + cacheRead + outputTokens,
+            cacheCreationTokens: cacheCreation || undefined,
+            cacheReadTokens: cacheRead || undefined,
         };
     }
     return null;
@@ -132,13 +143,42 @@ export function getCostBreakdown() {
         else {
             const pricing = MODEL_PRICING[record.model];
             if (pricing) {
-                existing.estimatedCost += (record.promptTokens / 1_000_000) * pricing.inputPer1M + (record.completionTokens / 1_000_000) * pricing.outputPer1M;
+                // Anthropic prompt caching: cache_creation_input is billed at 1.25×
+                // the base input rate, cache_read_input at 0.1×. The remaining
+                // (uncached) prompt tokens bill at the standard 1.0× rate.
+                const cacheCreate = record.cacheCreationTokens ?? 0;
+                const cacheRead = record.cacheReadTokens ?? 0;
+                const uncachedPrompt = Math.max(0, record.promptTokens - cacheCreate - cacheRead);
+                existing.estimatedCost +=
+                    (uncachedPrompt / 1_000_000) * pricing.inputPer1M
+                        + (cacheCreate / 1_000_000) * pricing.inputPer1M * 1.25
+                        + (cacheRead / 1_000_000) * pricing.inputPer1M * 0.1
+                        + (record.completionTokens / 1_000_000) * pricing.outputPer1M;
             }
         }
         grouped.set(key, existing);
     }
     return Array.from(grouped.values());
 }
+export function getCacheStats() {
+    let cacheCreate = 0;
+    let cacheRead = 0;
+    let savings = 0;
+    for (const record of records) {
+        cacheCreate += record.cacheCreationTokens ?? 0;
+        cacheRead += record.cacheReadTokens ?? 0;
+        // Savings = what cache-read tokens would have cost at full input rate,
+        // minus what they actually cost at 0.1×. (Cache creation is a slight
+        // *penalty* of 0.25× — netted in for honest reporting.)
+        const pricing = MODEL_PRICING[record.model];
+        if (pricing) {
+            const cReadSaved = ((record.cacheReadTokens ?? 0) / 1_000_000) * pricing.inputPer1M * 0.9;
+            const cCreateCost = ((record.cacheCreationTokens ?? 0) / 1_000_000) * pricing.inputPer1M * 0.25;
+            savings += cReadSaved - cCreateCost;
+        }
+    }
+    return { cacheCreationTokens: cacheCreate, cacheReadTokens: cacheRead, estimatedSavingsUsd: Math.max(0, savings) };
+}
 /**
  * Get session stats
  */
@@ -207,6 +247,18 @@ export function formatCostReport() {
             lines.push(`| \`${b.provider}\` / \`${b.model}\` | ${formatTokenCount(b.promptTokens)} | ${formatTokenCount(b.completionTokens)} | $${b.estimatedCost.toFixed(4)} |`);
         }
     }
+    // Prompt caching summary — only shown if at least one cached call landed.
+    const cache = getCacheStats();
+    if (cache.cacheReadTokens > 0 || cache.cacheCreationTokens > 0) {
+        lines.push('', '### Prompt caching');
+        lines.push(`**Cache reads:** ${formatTokenCount(cache.cacheReadTokens)} tokens (billed at 0.1× input rate)`);
+        if (cache.cacheCreationTokens > 0) {
+            lines.push(`**Cache writes:** ${formatTokenCount(cache.cacheCreationTokens)} tokens (billed at 1.25× input rate)`);
+        }
+        if (cache.estimatedSavingsUsd > 0) {
+            lines.push(`**Estimated savings vs no caching:** $${cache.estimatedSavingsUsd.toFixed(4)}`);
+        }
+    }
     // Models with no pricing entry don't contribute to cost — flag so users
     // aren't surprised the total looks low.
     const untracked = breakdown.filter(b => b.estimatedCost === 0 && (b.promptTokens + b.completionTokens) > 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeep",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",