codeep 2.0.1 → 2.0.3

package/README.md

@@ -526,6 +526,64 @@ Then call it as `/sec-review src/api/login.ts` (or `/sec` via the alias).
 **Discovery:** `/commands` lists all available templates. Project files shadow
 global files with the same name. Aliases also work for autocomplete.
 
+### Personalities (`/personality`, new in 2.0.3)
+
+Swap how the agent talks and what it prioritises mid-conversation:
+
+```
+/personality                  # list available
+/personality concise          # short answers, no preamble
+/personality security         # treat every input as hostile
+/personality senior-reviewer  # push back on shortcuts, name things well
+/personality ship-it          # pick first reasonable approach
+/personality off              # back to default tone
+```
+
+Six built-in presets: `concise`, `verbose`, `security`, `senior-reviewer`,
+`junior-mentor`, `ship-it`. The active one persists across sessions
+(stored in `~/.codeep/config.json` as `activePersonality`).
+
+**Custom personalities** — drop a Markdown file in
+`.codeep/personalities/<name>.md` (project) or
+`~/.codeep/personalities/<name>.md` (global):
+
+```markdown
+# Personality: PR Reviewer
+
+You are reviewing a PR from a junior engineer:
+- Cite line numbers for every concern.
+- Suggest an alternative, don't just flag the problem.
+- Keep tone collaborative, not pedantic.
+- End with one thing the author did well.
+```
+
+First `# Personality:` line is the display name; the rest is appended
+to the agent's system prompt verbatim when active. Project shadows
+global shadows built-in (by name).
+
+### Activity Insights (`/insights`, new in 2.0.3)
+
+Summarise what the agent has actually done for you over a window — runs,
+tool actions, projects touched, most-edited files — sourced from
+`~/.codeep/history/<id>.json` (one file per agent run, automatic).
+
+```
+/insights                 # last 7 days (default)
+/insights --days 30       # last month
+/insights --days 1        # today only
+```
+
+Surfaces (markdown rendered in chat):
+
+- Headline tally: runs · actions · active time · active-days density · avg actions/run
+- **By project** sorted by active time
+- **Top tools** (read_file × 340, write_file × 80, …)
+- **Most-touched files** (with `~` prefix for readability)
+- **Recent runs** — 10 most recent with project, duration, and the user prompt that started them
+
+Cost / token usage isn't in `/insights` (it lives in `/cost` per-session
+since the token tracker is in-memory). Insights is history-only.
+
 ### Project Intelligence (`/init`, `/scan`)
 
 Initialize a project and scan it once to cache deep analysis for faster AI responses:

package/dist/acp/commands.js

@@ -600,6 +600,101 @@ Anything else the agent should know — edge cases, gotchas, things to double-ch
             }
         }
         // ─── Export ────────────────────────────────────────────────────────────────
+        // ─── Personalities + insights (2.0.3) ─────────────────────────────────────
+        case 'personality': {
+            const { formatPersonalityList, findPersonality } = await import('../utils/personalities.js');
+            const sub = args[0]?.toLowerCase();
+            if (!sub) {
+                return { handled: true, response: formatPersonalityList(session.workspaceRoot) };
+            }
+            if (sub === 'off' || sub === 'none' || sub === 'clear') {
+                config.set('activePersonality', null);
+                return { handled: true, response: 'Personality cleared — agent uses default tone.' };
+            }
+            const p = findPersonality(sub, session.workspaceRoot);
+            if (!p) {
+                return { handled: true, response: `No personality named \`${sub}\`. Run \`/personality\` to see available.` };
+            }
+            config.set('activePersonality', p.name);
+            return {
+                handled: true,
+                response: `Active personality: **${p.displayName}** (\`${p.name}\`, ${p.scope})\n\n_${p.description}_\n\nClear with \`/personality off\`.`,
+            };
+        }
+        case 'insights': {
+            const { formatInsights } = await import('../utils/insights.js');
+            let days = 7;
+            for (let i = 0; i < args.length; i++) {
+                const a = args[i];
+                if (a === '--days' && args[i + 1]) {
+                    const n = parseInt(args[i + 1], 10);
+                    if (Number.isFinite(n))
+                        days = n;
+                }
+                else if (a.startsWith('--days=')) {
+                    const n = parseInt(a.slice('--days='.length), 10);
+                    if (Number.isFinite(n))
+                        days = n;
+                }
+            }
+            return { handled: true, response: formatInsights({ days }) };
+        }
+        // ─── 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,12 @@ 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' },
+    // Personalities + insights (2.0.3)
+    { name: 'personality', description: 'List or switch agent tone preset', input: { hint: '[name | off]' } },
+    { name: 'insights', description: 'Activity summary over the last N days (default 7)', input: { hint: '[--days N]' } },
     // 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/config/index.d.ts

@@ -57,6 +57,13 @@ interface ConfigSchema {
         data_collection?: 'allow' | 'deny';
         require_parameters?: boolean;
     };
+    /**
+     * Active personality preset (`concise`, `senior-reviewer`, custom user
+     * personalities from .codeep/personalities/*.md, …). When set, the
+     * loader text is appended to every agent system prompt. See
+     * utils/personalities.ts.
+     */
+    activePersonality?: string | null;
 }
 export type { AgentMode };
 export type { LanguageCode };

package/dist/renderer/App.js

@@ -91,6 +91,10 @@ const COMMAND_DESCRIPTIONS = {
     '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',
+    'personality': 'Switch agent tone: concise / verbose / security / senior-reviewer / etc',
+    'insights': 'Activity summary over the last N days (default 7): runs, files, tools, projects',
 };
 import { helpCategories, keyboardShortcuts } from './components/Help.js';
 import { handleSettingsKey, SETTINGS } from './components/Settings.js';
@@ -230,6 +234,10 @@ export class App {
         // Keep in lockstep with COMMAND_DESCRIPTIONS below and helpCategories.
         'compact', 'commands', 'checkpoint', 'checkpoints', 'rewind',
         'hooks', 'mcp', 'openrouter',
+        // 2.0.2 — plan mode.
+        'plan', 'go',
+        // 2.0.3 — personalities + insights.
+        'personality', 'insights',
         'c', 't', 'd', 'r', 'f', 'e', 'o', 'b', 'p',
     ];
     constructor(options) {

package/dist/renderer/commands.js

@@ -216,6 +216,109 @@ export async function handleCommand(command, args, ctx) {
             runAgentTask(args.join(' '), true, ctx, () => null, () => { });
             break;
         }
+        case 'insights': {
+            const { formatInsights } = await import('../utils/insights.js');
+            // Parse `--days N` (default 7). Accept both `--days 30` and `--days=30`.
+            let days = 7;
+            for (let i = 0; i < args.length; i++) {
+                const a = args[i];
+                if (a === '--days' && args[i + 1]) {
+                    const n = parseInt(args[i + 1], 10);
+                    if (Number.isFinite(n))
+                        days = n;
+                }
+                else if (a.startsWith('--days=')) {
+                    const n = parseInt(a.slice('--days='.length), 10);
+                    if (Number.isFinite(n))
+                        days = n;
+                }
+            }
+            ctx.app.addMessage({ role: 'system', content: formatInsights({ days }) });
+            break;
+        }
+        case 'personality': {
+            const { formatPersonalityList, findPersonality } = await import('../utils/personalities.js');
+            const sub = args[0]?.toLowerCase();
+            if (!sub) {
+                ctx.app.addMessage({ role: 'system', content: formatPersonalityList(ctx.projectPath) });
+                break;
+            }
+            if (sub === 'off' || sub === 'none' || sub === 'clear') {
+                config.set('activePersonality', null);
+                ctx.app.notify('Personality cleared — agent uses default tone.');
+                break;
+            }
+            const personality = findPersonality(sub, ctx.projectPath);
+            if (!personality) {
+                ctx.app.notify(`No personality named "${sub}". Run /personality to see available.`);
+                break;
+            }
+            config.set('activePersonality', personality.name);
+            ctx.app.addMessage({
+                role: 'system',
+                content: `Active personality: **${personality.displayName}** (\`${personality.name}\`, ${personality.scope})\n\n_${personality.description}_\n\nClear with \`/personality off\`.`,
+            });
+            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();

package/dist/renderer/components/Help.js

@@ -46,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' },
@@ -121,6 +123,9 @@ export const helpCategories = [
             { 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)' },
+            { key: '/personality', description: 'List or switch agent tone (concise / verbose / security / senior-reviewer / …)' },
+            { key: '/personality <name>', description: 'Activate a personality. /personality off to clear.' },
+            { key: '/insights [--days N]', description: 'Activity summary — runs, files, tools, projects over the last N days (default 7)' },
         ],
     },
     {

package/dist/utils/agent.js

@@ -253,6 +253,19 @@ export async function runAgent(prompt, projectContext, options = {}) {
     if (skillCatalogBlock) {
         systemPrompt += '\n\n' + skillCatalogBlock;
     }
+    // Active personality goes LAST — appended after skills / project rules /
+    // smart context so its tone overrides earlier conventions. Set via
+    // `/personality <name>`; empty when no personality is active.
+    try {
+        const { getActivePersonalityPrompt } = await import('./personalities.js');
+        const personalityPrompt = getActivePersonalityPrompt(projectContext.root);
+        if (personalityPrompt) {
+            systemPrompt += personalityPrompt;
+        }
+    }
+    catch {
+        // Personality loading must never block an agent run.
+    }
     // Initial user message with optional task plan
     let initialPrompt = prompt;
     if (taskPlan) {

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/insights.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `/insights` — agent activity summary over a configurable window.
+ *
+ * Source of truth: `~/.codeep/history/<id>.json`, one file per agent
+ * run, written by the agent loop. Schema (relevant fields):
+ *   { id, startTime, endTime, prompt, projectRoot, actions: [
+ *       { type: 'write' | 'read' | 'execute' | …, path?, command?, timestamp }
+ *     ]
+ *   }
+ *
+ * We deliberately don't read sessions/*.json here — sessions store
+ * chat history without tool-level detail, while history/ captures the
+ * exact actions which is what users want to see ("which file did I
+ * touch most this week?").
+ *
+ * Cost / token usage is per-process and lost across restarts (the
+ * token tracker is in-memory), so /insights reports actions and time
+ * but not historical dollar amounts. The current session's cost still
+ * shows in /cost.
+ */
+interface InsightsOptions {
+    /** Days to look back. Default 7. */
+    days?: number;
+}
+/**
+ * Format `/insights` output as Markdown. Returns a friendly empty-state
+ * message when there's no history in the window — we don't error.
+ */
+export declare function formatInsights(opts?: InsightsOptions): string;
+export {};

package/dist/utils/insights.js

@@ -0,0 +1,166 @@
+/**
+ * `/insights` — agent activity summary over a configurable window.
+ *
+ * Source of truth: `~/.codeep/history/<id>.json`, one file per agent
+ * run, written by the agent loop. Schema (relevant fields):
+ *   { id, startTime, endTime, prompt, projectRoot, actions: [
+ *       { type: 'write' | 'read' | 'execute' | …, path?, command?, timestamp }
+ *     ]
+ *   }
+ *
+ * We deliberately don't read sessions/*.json here — sessions store
+ * chat history without tool-level detail, while history/ captures the
+ * exact actions which is what users want to see ("which file did I
+ * touch most this week?").
+ *
+ * Cost / token usage is per-process and lost across restarts (the
+ * token tracker is in-memory), so /insights reports actions and time
+ * but not historical dollar amounts. The current session's cost still
+ * shows in /cost.
+ */
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+function loadHistoryRuns(sinceMs) {
+    const dir = join(homedir(), '.codeep', 'history');
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const runs = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(join(dir, file), 'utf8');
+            const run = JSON.parse(raw);
+            if (typeof run.startTime !== 'number')
+                continue;
+            if (run.startTime < sinceMs)
+                continue;
+            runs.push(run);
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return runs.sort((a, b) => b.startTime - a.startTime);
+}
+function fmtDuration(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m`;
+    const h = Math.floor(ms / 3_600_000);
+    const m = Math.round((ms % 3_600_000) / 60_000);
+    return m === 0 ? `${h}h` : `${h}h ${m}m`;
+}
+function relativeDayBucket(ts, now) {
+    const dayMs = 86_400_000;
+    const days = Math.floor((now - ts) / dayMs);
+    if (days === 0)
+        return 'today';
+    if (days === 1)
+        return 'yesterday';
+    if (days < 7)
+        return `${days}d ago`;
+    return new Date(ts).toISOString().slice(0, 10);
+}
+/**
+ * Format `/insights` output as Markdown. Returns a friendly empty-state
+ * message when there's no history in the window — we don't error.
+ */
+export function formatInsights(opts = {}) {
+    const days = Math.max(1, Math.min(365, opts.days ?? 7));
+    const now = Date.now();
+    const sinceMs = now - days * 86_400_000;
+    const runs = loadHistoryRuns(sinceMs);
+    const lines = [`## Activity — last ${days} day${days === 1 ? '' : 's'}`, ''];
+    if (runs.length === 0) {
+        lines.push(`_No agent runs in the last ${days} day${days === 1 ? '' : 's'}._`);
+        lines.push('');
+        lines.push('Run an agent task with `/agent <task>` (or just type a request when agent mode is on) — the activity here populates from `~/.codeep/history/`.');
+        return lines.join('\n');
+    }
+    // ── Headline metrics ──────────────────────────────────────────────────────
+    const totalRuns = runs.length;
+    const totalActions = runs.reduce((s, r) => s + (r.actions?.length ?? 0), 0);
+    const totalActiveMs = runs.reduce((s, r) => s + Math.max(0, (r.endTime ?? r.startTime) - r.startTime), 0);
+    const avgActions = (totalActions / totalRuns).toFixed(1);
+    const distinctDays = new Set(runs.map((r) => new Date(r.startTime).toISOString().slice(0, 10))).size;
+    lines.push(`**${totalRuns}** run${totalRuns === 1 ? '' : 's'}`
+        + `  ·  **${totalActions}** tool action${totalActions === 1 ? '' : 's'}`
+        + `  ·  **${fmtDuration(totalActiveMs)}** active`
+        + `  ·  **${distinctDays}**/${days} active day${distinctDays === 1 ? '' : 's'}`
+        + `  ·  avg **${avgActions}** action${avgActions === '1.0' ? '' : 's'}/run`);
+    // ── By project ────────────────────────────────────────────────────────────
+    const byProject = new Map();
+    for (const r of runs) {
+        const proj = r.projectRoot ? basename(r.projectRoot) : '(no project)';
+        const cur = byProject.get(proj) ?? { runs: 0, actions: 0, activeMs: 0 };
+        cur.runs++;
+        cur.actions += r.actions?.length ?? 0;
+        cur.activeMs += Math.max(0, (r.endTime ?? r.startTime) - r.startTime);
+        byProject.set(proj, cur);
+    }
+    const projects = [...byProject.entries()].sort((a, b) => b[1].activeMs - a[1].activeMs);
+    if (projects.length > 0) {
+        lines.push('', '### By project', '');
+        lines.push('| Project | Runs | Actions | Active time |');
+        lines.push('|---|---:|---:|---:|');
+        for (const [name, s] of projects.slice(0, 8)) {
+            lines.push(`| \`${name}\` | ${s.runs} | ${s.actions} | ${fmtDuration(s.activeMs)} |`);
+        }
+        if (projects.length > 8)
+            lines.push(`| _… and ${projects.length - 8} more_ | | | |`);
+    }
+    // ── Top tool types ────────────────────────────────────────────────────────
+    const byType = new Map();
+    for (const r of runs) {
+        for (const a of r.actions ?? []) {
+            byType.set(a.type, (byType.get(a.type) ?? 0) + 1);
+        }
+    }
+    const tools = [...byType.entries()].sort((a, b) => b[1] - a[1]);
+    if (tools.length > 0) {
+        lines.push('', '### Top tools', '');
+        for (const [name, count] of tools.slice(0, 8)) {
+            lines.push(`- \`${name}\` × **${count}**`);
+        }
+    }
+    // ── Top files touched ─────────────────────────────────────────────────────
+    const byPath = new Map();
+    for (const r of runs) {
+        for (const a of r.actions ?? []) {
+            if (a.path)
+                byPath.set(a.path, (byPath.get(a.path) ?? 0) + 1);
+        }
+    }
+    const files = [...byPath.entries()].sort((a, b) => b[1] - a[1]);
+    if (files.length > 0) {
+        lines.push('', '### Most-touched files', '');
+        for (const [path, count] of files.slice(0, 8)) {
+            // Trim home prefix for readability
+            const display = path.replace(homedir(), '~');
+            lines.push(`- \`${display}\` × **${count}**`);
+        }
+    }
+    // ── Recent runs ───────────────────────────────────────────────────────────
+    lines.push('', '### Recent runs', '');
+    for (const r of runs.slice(0, 10)) {
+        const when = relativeDayBucket(r.startTime, now);
+        const dur = fmtDuration(Math.max(0, (r.endTime ?? r.startTime) - r.startTime));
+        const proj = r.projectRoot ? basename(r.projectRoot) : '—';
+        const prompt = (r.prompt || '').replace(/\s+/g, ' ').trim();
+        const promptShort = prompt.length > 80 ? prompt.slice(0, 77) + '…' : prompt;
+        lines.push(`- _${when}_ · **${proj}** · ${dur} · ${promptShort}`);
+    }
+    // ── Session cost callout ──────────────────────────────────────────────────
+    // We only track tokens in-memory per process, so historical cost isn't
+    // available. Tell the user where to look for the current session.
+    lines.push('', "_For this session's cost + cache savings, run `/cost`._");
+    return lines.join('\n');
+}

package/dist/utils/personalities.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Personalities — pluggable system prompt addenda that shape how the
+ * agent communicates and what it prioritises.
+ *
+ * Storage:
+ *   - **Built-in**: hardcoded below (concise, verbose, security,
+ *     senior-reviewer, junior-mentor, ship-it).
+ *   - **Project**: `<workspace>/.codeep/personalities/<name>.md`
+ *   - **Global**:  `~/.codeep/personalities/<name>.md`
+ *
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format (project / global):
+ *   ```
+ *   # Personality: Concise Reviewer
+ *   <free-form Markdown body — gets appended to system prompt verbatim>
+ *   ```
+ * (The first H1 line is parsed as the display name; everything else is
+ * the prompt body.)
+ *
+ * Activation:
+ *   - `config.activePersonality` holds the active name (or null/undefined
+ *     for default behaviour).
+ *   - `getActivePersonalityPrompt(workspaceRoot)` returns the prompt
+ *     addendum to inject into the agent's system prompt, or '' when no
+ *     personality is active.
+ *   - Persists across sessions until cleared with `/personality off`.
+ */
+export type PersonalityScope = 'builtin' | 'project' | 'global';
+export interface Personality {
+    /** Slug (filename without .md, or built-in id). Lowercase, hyphens. */
+    name: string;
+    /** Human display label shown in `/personality` list. */
+    displayName: string;
+    /** One-line description for the list view. */
+    description: string;
+    /** Markdown body appended to the system prompt when active. */
+    prompt: string;
+    scope: PersonalityScope;
+}
+export declare function loadAllPersonalities(workspaceRoot?: string): Personality[];
+export declare function findPersonality(name: string, workspaceRoot?: string): Personality | null;
+/**
+ * Returns the prompt addendum for the currently active personality, or
+ * '' when none is set. Called from agent.ts after the base system prompt
+ * is composed — appended last so personality overrides apply even if
+ * project rules conflict.
+ */
+export declare function getActivePersonalityPrompt(workspaceRoot?: string): string;
+export declare function formatPersonalityList(workspaceRoot?: string): string;

package/dist/utils/personalities.js

@@ -0,0 +1,226 @@
+/**
+ * Personalities — pluggable system prompt addenda that shape how the
+ * agent communicates and what it prioritises.
+ *
+ * Storage:
+ *   - **Built-in**: hardcoded below (concise, verbose, security,
+ *     senior-reviewer, junior-mentor, ship-it).
+ *   - **Project**: `<workspace>/.codeep/personalities/<name>.md`
+ *   - **Global**:  `~/.codeep/personalities/<name>.md`
+ *
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format (project / global):
+ *   ```
+ *   # Personality: Concise Reviewer
+ *   <free-form Markdown body — gets appended to system prompt verbatim>
+ *   ```
+ * (The first H1 line is parsed as the display name; everything else is
+ * the prompt body.)
+ *
+ * Activation:
+ *   - `config.activePersonality` holds the active name (or null/undefined
+ *     for default behaviour).
+ *   - `getActivePersonalityPrompt(workspaceRoot)` returns the prompt
+ *     addendum to inject into the agent's system prompt, or '' when no
+ *     personality is active.
+ *   - Persists across sessions until cleared with `/personality off`.
+ */
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { config } from '../config/index.js';
+const BUILTIN = [
+    {
+        name: 'concise',
+        displayName: 'Concise',
+        description: 'Short answers. No preamble. No filler. Get in, get out.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Concise
+
+Keep responses tight:
+- Skip preamble ("Great question!", "Let me help…") — go straight to substance.
+- Use bullet points over paragraphs for lists of 3+ items.
+- One code block per answer when possible; no commentary around obvious code.
+- Prefer "Done." over "I've successfully completed the task by…"
+- No emojis unless the user explicitly uses them first.`,
+    },
+    {
+        name: 'verbose',
+        displayName: 'Verbose',
+        description: 'Detailed explanations with rationale, alternatives considered, and caveats.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Verbose
+
+Take time to explain:
+- For every non-trivial change, lay out: what / why / alternatives I considered / why I chose this one.
+- Cite line numbers and file paths so the user can audit.
+- When reading code, summarise what the surrounding context does before acting — this catches misunderstandings early.
+- End complex tasks with a "what to verify" checklist for the user.`,
+    },
+    {
+        name: 'security',
+        displayName: 'Security-paranoid',
+        description: 'Flags every input as untrusted, second-guesses every API call, prefers defensive code.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Security-paranoid
+
+Treat every input as hostile until proven otherwise:
+- For any code that touches user input, env vars, file paths, or network: enumerate the attack surface in a short comment block above the code.
+- Prefer allowlists over blocklists. Prefer parameterised queries / escape-on-output to ad-hoc sanitisation.
+- Flag every secret/key reference and ensure it's read from env or secret manager — never inline.
+- When suggesting dependencies, prefer audited ones (cite stars / last-publish date) and note known CVEs if any.
+- After implementing, list 2-3 concrete attack scenarios you considered (e.g. "what if input contains '../'?") and how the code handles them.`,
+    },
+    {
+        name: 'senior-reviewer',
+        displayName: 'Senior reviewer',
+        description: 'Strong opinions on architecture, naming, abstraction boundaries. Pushes back on shortcuts.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Senior Reviewer
+
+Critique like a staff engineer reviewing a PR from a colleague:
+- If the proposed approach has a cleaner alternative, propose it first — even if the user's framing pushed toward the messier one.
+- Name things with the team in mind. Reject lazy names (handler, util, manager) and propose specific ones.
+- Watch for premature abstraction (one-call helpers) and missing abstractions (3rd copy of the same 5 lines).
+- Push back on "just for now" hacks unless the user explicitly says it's a throwaway.
+- Mention what's NOT tested when adding new code, and suggest the test cases that'd catch likely regressions.`,
+    },
+    {
+        name: 'junior-mentor',
+        displayName: 'Junior mentor',
+        description: 'Explains concepts as you go, links to docs, suggests what to learn next.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Junior Mentor
+
+The user is learning — meet them where they are:
+- Before introducing a new concept, give a 1-2 sentence "why this exists" context.
+- Use analogies for abstract topics (closures = "a backpack the function carries"). Keep them grounded, not fancy.
+- Link to canonical docs (MDN, language reference, official tutorial) rather than blog posts.
+- After completing a task, suggest 1 thing to read or 1 small follow-up exercise that reinforces the concept just used.
+- Resist showing off. Don't introduce ES2024 destructuring spread tricks when a plain for-loop teaches the lesson better.`,
+    },
+    {
+        name: 'ship-it',
+        displayName: 'Ship it',
+        description: 'Optimise for speed-to-merge. No bikeshedding. "Done is better than perfect" mode.',
+        scope: 'builtin',
+        prompt: `
+
+## Personality: Ship It
+
+The user wants this merged today:
+- Pick the first reasonable approach. Don't enumerate three alternatives — commit to one.
+- Inline TODO comments are fine for cleanup-later items. Don't refactor adjacent code.
+- Test the happy path. Edge cases can wait for follow-up unless they're security-relevant.
+- Suggest minimum-viable solution, not robust-for-all-cases. The user can iterate.
+- If the user asks "should we also…", default to "no, ship this first, that's a separate PR".`,
+    },
+];
+/** Load custom personalities from a `.codeep/personalities/` directory. */
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const name = entry.slice(0, -3).toLowerCase();
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+            continue; // skip weirdly-named files
+        try {
+            const raw = readFileSync(join(dir, entry), 'utf8');
+            if (raw.length > 64 * 1024)
+                continue; // cap at 64 KB
+            // First H1 → displayName; rest → prompt.
+            const h1 = raw.match(/^#\s+(?:Personality:\s+)?(.+)$/m);
+            const displayName = h1?.[1].trim() ?? name;
+            const body = h1 ? raw.slice(raw.indexOf('\n', raw.indexOf(h1[0])) + 1).trimStart() : raw;
+            // First paragraph (or line) → description (cap 200 chars).
+            const firstPara = body.split(/\n\s*\n/)[0]?.replace(/\s+/g, ' ').trim() ?? '';
+            const description = firstPara.length > 200 ? firstPara.slice(0, 197) + '…' : firstPara;
+            out.push({
+                name,
+                displayName,
+                description: description || `Custom personality from ${entry}`,
+                prompt: '\n\n## Personality: ' + displayName + '\n\n' + body,
+                scope,
+            });
+        }
+        catch {
+            // Skip broken files — never crash personality loading.
+        }
+    }
+    return out;
+}
+export function loadAllPersonalities(workspaceRoot) {
+    const project = workspaceRoot
+        ? loadFromDir(join(workspaceRoot, '.codeep', 'personalities'), 'project')
+        : [];
+    const global = loadFromDir(join(homedir(), '.codeep', 'personalities'), 'global');
+    // Merge with scope priority: project > global > builtin.
+    const byName = new Map();
+    for (const p of BUILTIN)
+        byName.set(p.name, p);
+    for (const p of global)
+        byName.set(p.name, p);
+    for (const p of project)
+        byName.set(p.name, p);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findPersonality(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    return loadAllPersonalities(workspaceRoot).find((p) => p.name === lower) ?? null;
+}
+/**
+ * Returns the prompt addendum for the currently active personality, or
+ * '' when none is set. Called from agent.ts after the base system prompt
+ * is composed — appended last so personality overrides apply even if
+ * project rules conflict.
+ */
+export function getActivePersonalityPrompt(workspaceRoot) {
+    const name = config.get('activePersonality');
+    if (!name)
+        return '';
+    const p = findPersonality(name, workspaceRoot);
+    return p?.prompt ?? '';
+}
+export function formatPersonalityList(workspaceRoot) {
+    const list = loadAllPersonalities(workspaceRoot);
+    const active = config.get('activePersonality');
+    const lines = ['## Personalities', ''];
+    if (active) {
+        lines.push(`**Active:** \`${active}\` — switch with \`/personality <name>\` or clear with \`/personality off\`.`);
+    }
+    else {
+        lines.push('**Active:** _(none — agent uses default tone)_');
+    }
+    lines.push('');
+    lines.push('| Name | Scope | Description |');
+    lines.push('|---|---|---|');
+    for (const p of list) {
+        const tag = p.scope === 'builtin' ? 'built-in' : p.scope;
+        const marker = active === p.name ? ' ✓' : '';
+        lines.push(`| \`${p.name}\`${marker} | ${tag} | ${p.description} |`);
+    }
+    lines.push('');
+    lines.push('Drop a `<name>.md` file into `.codeep/personalities/` (project) or `~/.codeep/personalities/` (global) to add your own — first `#` line becomes the display name, body becomes the prompt addendum.');
+    return lines.join('\n');
+}

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/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.1",
+  "version": "2.0.3",
   "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",