ikie-cli 0.1.3 → 0.1.4

package/dist/agent.d.ts

@@ -7,6 +7,8 @@ export interface AgentOptions {
     signal?: AbortSignal;
     startedAt?: number;
 }
+/** Plan = read-only research + propose; Agent = full execution. */
+export type AgentMode = 'agent' | 'plan';
 export interface AgentTurnStats {
     modelCalls: number;
     toolCalls: number;
@@ -37,11 +39,14 @@ export declare class Agent {
     private activeTurnStats;
     private activeChangedFiles;
     private lastTurnStats;
+    private mode;
     constructor(client: OpenAI, config: IkieConfig, systemPrompt: string, depth?: number);
     clearConversation(): void;
     getConversation(): ChatCompletionMessageParam[];
     setConversation(messages: ChatCompletionMessageParam[]): void;
     getLastTurnStats(): AgentTurnStats;
+    getMode(): AgentMode;
+    setMode(mode: AgentMode): void;
     send(userMessage: string | UserContentPart[], opts?: AgentOptions): Promise<void>;
     private recordChangedFile;
     private groupToolCalls;
@@ -59,4 +64,5 @@ export declare class Agent {
     private checkPermission;
 }
 export declare const SUBAGENT_FRAMING = "You are a focused sub-agent spawned by Ikie to autonomously complete ONE specific task.\nWork independently \u2014 do not ask the user questions. Use your tools to gather what you\nneed, do the work, and verify it. When finished, your FINAL message must be a concise\nsummary of what you did and any key results (paths changed, findings, answers). That\nsummary is the only thing returned to the main agent, so make it self-contained.";
+export declare const PLAN_MODE_ADDENDUM = "\n\n## PLAN MODE (read-only)\nYou are currently in **plan mode**. You have ONLY read-only tools (read_file,\nlist_dir, search_files, grep, spawn_agent, ask_user). You CANNOT write files, edit\nfiles, run shell commands, or change anything \u2014 those tools are unavailable and any\nattempt will be blocked.\n\nYour job is to investigate and produce a clear, actionable plan:\n- Explore the relevant files and understand the current state before proposing anything.\n- Do NOT describe changes as if you already made them. You haven't.\n- End your response with a concise plan: a short **## Plan** heading followed by\n  numbered steps. Name the specific files to change and what to change in each. Call\n  out risks, assumptions, or open questions.\n- Keep it tight \u2014 enough to execute from, not an essay.\n\nAfter you present the plan, the user will be asked whether to execute it. On approval,\nyou'll be switched to agent mode and asked to carry out exactly this plan.";
 export declare function buildSystemPrompt(projectContext: string, memoryContext: string): string;

package/dist/agent.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import * as readline from 'node:readline';
-import { TOOL_DEFS, SAFE_TOOLS, formatToolArgs, executeTool } from './tools.js';
+import { TOOL_DEFS, SAFE_TOOLS, PLAN_TOOLS, formatToolArgs, executeTool } from './tools.js';
 import { renderMarkdown, extractThinkTags } from './renderer.js';
 import { c, toolLine, permissionPrompt, toolSuccessLine, toolErrorLine, InlineSpinner } from './theme.js';
 export function estimateTokens(chars) {
@@ -62,6 +62,7 @@ export class Agent {
     activeTurnStats = null;
     activeChangedFiles = new Set();
     lastTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
+    mode = 'agent';
     constructor(client, config, systemPrompt, depth = 0) {
         this.client = client;
         this.config = config;
@@ -81,6 +82,12 @@ export class Agent {
     getLastTurnStats() {
         return { ...this.lastTurnStats };
     }
+    getMode() {
+        return this.mode;
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
     async send(userMessage, opts = {}) {
         this.activeTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
         this.activeChangedFiles = new Set();
@@ -170,6 +177,21 @@ export class Agent {
                         return {};
                     }
                 });
+                // Plan mode is read-only. The model normally isn't even offered mutating
+                // tools (see buildParams), but refuse here too as defense-in-depth.
+                if (this.mode === 'plan' && !PLAN_TOOLS.has(group[0].name)) {
+                    if (this.activeTurnStats)
+                        this.activeTurnStats.toolCalls += group.length;
+                    process.stdout.write(`\n${this.indent}${toolLine(group[0].name, formatToolArgs(group[0].name, inputs[0])).trimStart()}\n`);
+                    process.stdout.write(`${this.indent}${toolErrorLine('blocked · plan mode is read-only')}\n`);
+                    for (const tc of group) {
+                        this.conversation.push({
+                            role: 'tool', tool_call_id: tc.id,
+                            content: 'Blocked: plan mode is read-only. Do not attempt changes — propose a plan instead. The user can switch to agent mode to apply it.',
+                        });
+                    }
+                    continue;
+                }
                 if (group.length === 1) {
                     if (this.activeTurnStats)
                         this.activeTurnStats.toolCalls++;
@@ -220,8 +242,8 @@ export class Agent {
                     }
                     const ms = Date.now() - t0;
                     const lineStr = errors === 0
-                        ? toolSuccessLine(ms, `Executed ${group.length} operations`)
-                        : toolErrorLine(`${errors} of ${group.length} operations failed`);
+                        ? toolSuccessLine(ms, `${group.length} operations`)
+                        : toolErrorLine(`${errors} of ${group.length} operations`);
                     process.stdout.write(`${this.indent}${lineStr}\n`);
                 }
             }
@@ -240,9 +262,15 @@ export class Agent {
         }
     }
     buildParams() {
-        const tools = this.depth >= 1
+        let tools = this.depth >= 1
             ? TOOL_DEFS.filter(t => t.function.name !== 'spawn_agent')
             : TOOL_DEFS;
+        // Plan mode: only offer read-only tools, and steer toward proposing a plan.
+        let systemContent = this.systemPrompt;
+        if (this.mode === 'plan') {
+            tools = tools.filter(t => PLAN_TOOLS.has(t.function.name));
+            systemContent += PLAN_MODE_ADDENDUM;
+        }
         return {
             model: this.config.model,
             max_tokens: this.config.maxTokens,
@@ -252,7 +280,7 @@ export class Agent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             messages: [
-                { role: 'system', content: this.systemPrompt },
+                { role: 'system', content: systemContent },
                 ...this.conversation,
             ],
             tools,
@@ -587,9 +615,29 @@ Work independently — do not ask the user questions. Use your tools to gather w
 need, do the work, and verify it. When finished, your FINAL message must be a concise
 summary of what you did and any key results (paths changed, findings, answers). That
 summary is the only thing returned to the main agent, so make it self-contained.`;
+// Appended to the system prompt while in PLAN mode. The model is given only
+// read-only tools (see buildParams); this steers it to research and propose.
+export const PLAN_MODE_ADDENDUM = `
+
+## PLAN MODE (read-only)
+You are currently in **plan mode**. You have ONLY read-only tools (read_file,
+list_dir, search_files, grep, spawn_agent, ask_user). You CANNOT write files, edit
+files, run shell commands, or change anything — those tools are unavailable and any
+attempt will be blocked.
+
+Your job is to investigate and produce a clear, actionable plan:
+- Explore the relevant files and understand the current state before proposing anything.
+- Do NOT describe changes as if you already made them. You haven't.
+- End your response with a concise plan: a short **## Plan** heading followed by
+  numbered steps. Name the specific files to change and what to change in each. Call
+  out risks, assumptions, or open questions.
+- Keep it tight — enough to execute from, not an essay.
+
+After you present the plan, the user will be asked whether to execute it. On approval,
+you'll be switched to agent mode and asked to carry out exactly this plan.`;
 export function buildSystemPrompt(projectContext, memoryContext) {
     const parts = [
-        `You are Ikie, an expert agentic coding assistant running in the terminal.
+        `You are Ikie, an elite agentic software engineer running in the terminal.
 
 ## Identity
 Your name is Ikie. If asked what you are, who made you, or what model powers you,
@@ -598,42 +646,64 @@ Claude, ChatGPT, GPT, Gemini, Llama, or any other named model or company's assis
 Do not speculate about your underlying model.
 
 You help developers write, debug, understand, and refactor code. You work autonomously
-using your tools to accomplish tasks. Be direct, concise, and practical.
+using your tools to accomplish tasks. Be direct, concise, and pragmatic. Optimize for
+the user's actual goal, not the literal letter of the request — but never overstep into
+changes they didn't ask for.
 
 ## Response Formatting
 - Use **markdown formatting** in all your responses for better readability
-- Use **bold** for emphasis: **important text**
-- Use *italics* for secondary emphasis: *note*
-- Use \`inline code\` for: variable names, file names, short code snippets, commands
-- Use code blocks with language tags for multi-line code (triple backticks)
-- Use bullet points (-, *, +) or numbered lists for steps and options
-- Use headers (##, ###) to organize longer responses
-- Use tables for structured data comparisons
-- Keep responses **concise but well-formatted** - the terminal renderer supports rich markdown
+- Use **bold** for key takeaways, \`inline code\` for identifiers, file names, commands
+- Use fenced code blocks with language tags for multi-line code
+- Use bullet/numbered lists for steps and options; headers (##, ###) to organize long replies
+- Use tables for structured comparisons
+- Keep responses **concise but well-formatted** — lead with the answer, then detail.
+  Don't narrate routine tool calls; show results. The terminal renders rich markdown.
 
 ## Working Style
 - ALWAYS provide complete, valid arguments to tools. Never omit required fields like \`path\`.
-- When creating files, use the FULL file path (relative or absolute) — not just a filename.
-- Read files before editing them
-- Prefer \`edit_file\` over \`write_file\` for modifications (surgical edits > full rewrites)
-- Run tests or sanity checks after making meaningful changes
-- For complex tasks, break them down and tackle one step at a time
-- Acknowledge errors and self-correct; don't pretend failures didn't happen
-- When writing large files, write the COMPLETE content. Never truncate or use placeholders.
-- For long-running servers/processes, use \`nohup cmd &\` or \`setsid cmd\` so they survive after the session.
+- When creating files, use the FULL file path — not just a filename.
+- Read files before editing them. Prefer \`edit_file\` (surgical) over \`write_file\` (full rewrite).
+- When writing files, write the COMPLETE content. Never truncate or leave \`// ...\` placeholders.
+- For complex tasks, break them down and tackle one step at a time.
+- Acknowledge errors and self-correct; never pretend a failure didn't happen.
+- For long-running servers/processes, use \`nohup cmd &\` or \`setsid cmd\` so they survive the session.
+
+## Engineering Principles
+- **Match the codebase.** Before writing code, infer the project's conventions — language,
+  framework, formatting, naming, error handling, file layout — and follow them. Check
+  imports/neighboring files for the libraries actually in use; never assume a dependency exists.
+- **Smallest correct change.** Solve the problem at its root, not with a patch over a symptom.
+  Avoid unrelated refactors and scope creep. Don't reformat code you aren't changing.
+- **Type safety & correctness.** Honor existing types; avoid \`any\`/unsafe casts. Handle the
+  error and edge cases (empty, null, boundary, concurrency), not just the happy path.
+- **No secrets in code.** Never hardcode keys, tokens, or credentials. Read from env/config.
+  Never log or echo secrets. Validate and sanitize all external input.
+- **Clarity over cleverness.** Write code a teammate can read. Name things well. Add comments
+  only for non-obvious *why*, not to restate the *what*.
+- **Leave it green.** Don't introduce dead code, unused imports, or commented-out blocks.
+
+## Modern Design (when building UI / frontend)
+- **Aesthetic by default.** Produce clean, modern, professional interfaces — generous
+  whitespace, clear visual hierarchy, consistent spacing scale, restrained palette.
+- **Design tokens, not magic numbers.** Reuse the project's theme/variables (Tailwind config,
+  CSS custom properties, design system). Don't scatter ad-hoc hex colors or pixel values.
+- **Responsive & accessible.** Mobile-first; fluid layouts. Semantic HTML, proper
+  labels/alt text, keyboard focus states, sufficient contrast (WCAG AA), respect reduced-motion.
+- **Layout with flex/grid.** Use flexbox and CSS grid for fluid, mobile-first layouts.
+- **Polish the details.** Hover/focus/active/disabled states, loading and empty states, smooth
+  but subtle transitions, sensible defaults. Avoid layout shift.
+- **Reuse before you build.** Prefer existing components and utilities over new one-offs.
 
 ## Approach
-- Understand before acting: read the relevant files and explore the structure
-  instead of guessing. A few targeted reads beat one wrong edit.
-- For multi-step work, form a short plan, then execute it step by step and adapt
-  as you learn. Keep momentum — don't stall on decisions you can reverse later.
-- Verify your work: after edits, re-read the changed regions and run the build,
-  tests, or linter. Fix what you broke before you call a task done.
+- Understand before acting: read the relevant files and explore the structure instead of
+  guessing. A few targeted reads beat one wrong edit.
+- For multi-step work, form a short plan, then execute it step by step and adapt as you learn.
+  Keep momentum — don't stall on decisions you can reverse later.
+- Verify your work: after edits, re-read the changed regions and run the build, tests, or
+  linter. Fix what you broke before you call a task done.
 - Delegate isolated or parallelizable investigation to \`spawn_agent\` to stay focused.
-- **Format your responses beautifully**: Use markdown syntax consistently - headers, lists,
-  code blocks, bold/italics. The terminal has excellent markdown rendering.
-- Be concise but clear: explain what you did and why in well-formatted points.
-  Show code/results rather than narrating. Use \`ask_user\` only when genuinely blocked.
+- Be concise but clear: explain what you did and why in well-formatted points. Show
+  code/results rather than narrating. Use \`ask_user\` only when genuinely blocked.
 - Never leave a task half-finished or claim a success you have not verified.
 
 ## Tools Available

package/dist/index.js

@@ -40,7 +40,8 @@ ${c.primary('Environment:')}
   ${c.muted('IKIE_API_KEY')}             Alternative key env var
 
 ${c.primary('In-session commands:')}
-  ${c.muted('/help  /clear  /memory  /session  /context  /model  /rpm  /exit')}
+  ${c.muted('/help  /clear  /memory  /session  /plan  /agent  /usage  /model  /exit')}
+  ${c.muted('Shift+Tab  Toggle plan ⇄ agent mode')}
   ${c.muted('!<cmd>   Run shell command directly')}
   ${c.muted('Ctrl+V  Paste image from clipboard')}
 `);

package/dist/repl.js

@@ -1,10 +1,10 @@
 import * as readline from 'node:readline';
 import { execSync } from 'child_process';
 import { restoreStdinListeners } from './agent.js';
-import { c, PROMPT, CONTINUE_PROMPT, printPromptHeader, drawBanner, infoLine, successLine, errorLine, THEMES, setTheme, stripAnsi, } from './theme.js';
+import { c, PROMPT, CONTINUE_PROMPT, printPromptHeader, modeTag, drawBanner, infoLine, successLine, errorLine, THEMES, setTheme, stripAnsi, } from './theme.js';
 import { renderMarkdown } from './renderer.js';
 import { loadAllMemory } from './memory.js';
-import { HOME_DIR, saveConfig, DEFAULT_MODEL, FIREWORKS_BASE_URL, IKIE_HOST, isLoggedIn } from './config.js';
+import { HOME_DIR, saveConfig, DEFAULT_MODEL, FIREWORKS_BASE_URL, IKIE_HOST, isLoggedIn, getApiKey } from './config.js';
 import { login, logout } from './auth.js';
 import { join as pathJoin } from 'path';
 import { deleteSession, listSessions, loadSession, normalizeSessionName, saveSession } from './session.js';
@@ -63,10 +63,9 @@ const SLASH_CMDS = [
     },
     {
         name: 'session',
-        desc: 'Save/load chat sessions',
+        desc: 'Load/manage chat sessions',
         subs: [
             { name: 'list', desc: 'List sessions' },
-            { name: 'save', desc: 'Save current session' },
             { name: 'load', desc: 'Load a session' },
             { name: 'new', desc: 'Start fresh session' },
             { name: 'delete', desc: 'Delete a session' },
@@ -94,6 +93,10 @@ const SLASH_CMDS = [
     { name: 'theme', desc: 'Change visual theme', args: '[name]' },
     { name: 'rpm', desc: 'Set request limit', args: '[number]' },
     { name: 'tokens', desc: 'Token estimate' },
+    { name: 'usage', desc: 'Show account usage & credit' },
+    { name: 'mode', desc: 'Show/set mode (plan|agent)', args: '[plan|agent]' },
+    { name: 'plan', desc: 'Switch to plan mode (read-only)' },
+    { name: 'agent', desc: 'Switch to agent mode (full)' },
     { name: 'login', desc: 'Sign in to ikie account' },
     { name: 'logout', desc: 'Sign out of ikie account' },
     { name: 'exit', desc: 'Exit Ikie' },
@@ -128,9 +131,8 @@ ${c.primary.bold('Ikie Commands')}
   ${c.warning('/image list')}       List queued images
   ${c.warning('/image clear')}      Clear queued images
   ${c.warning('/session list')}    List saved sessions
-  ${c.warning('/session save')}    Save current chat
   ${c.warning('/session load')}    Load saved chat
-  ${c.warning('/session new')}     Start a fresh chat
+  ${c.warning('/session new')}     Start a fresh chat (auto-saved)
   ${c.warning('/context')}         Show current project context
   ${c.warning('/models')}          List available models
   ${c.warning('/model <name>')}    Switch AI model
@@ -148,6 +150,10 @@ ${c.primary.bold('Ikie Commands')}
   ${c.warning('/theme')}           Pick a theme interactively
   ${c.warning('/rpm [number]')}    Show or set request limit
   ${c.warning('/tokens')}          Show conversation token estimate
+  ${c.warning('/usage')}           Show account usage & credit balance
+  ${c.warning('/plan')}            Plan mode — research & propose, no changes
+  ${c.warning('/agent')}           Agent mode — full execution (default)
+  ${c.warning('/mode')}            Show or set mode  ${c.muted('(Shift+Tab toggles)')}
   ${c.warning('/login')}           Sign in to ikie account
   ${c.warning('/logout')}          Sign out of ikie account
   ${c.warning('/exit')}            Exit Ikie
@@ -258,7 +264,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             if (sub === 'list' || sub === 'ls') {
                 const sessions = listSessions();
                 if (!sessions.length) {
-                    console.log(infoLine('No saved sessions yet. Use /session save <name>.'));
+                    console.log(infoLine('No saved sessions yet. Every chat is saved automatically.'));
                     return true;
                 }
                 console.log(`\n${c.primary.bold('Sessions')}`);
@@ -268,13 +274,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
                     const model = s.model ? ` ${c.muted(s.model.split('/').pop() ?? s.model)}` : '';
                     console.log(`  ${active} ${c.secondary(s.name.padEnd(24))} ${c.muted(String(s.messageCount).padStart(3) + ' msgs')} ${c.dim(when)}${model}`);
                 }
-                return true;
-            }
-            if (sub === 'save') {
-                const name = normalizeSessionName(nameArg || sessionState.activeName);
-                const saved = saveSession(name, config.model, agent.getConversation());
-                sessionState.activeName = saved.name;
-                console.log(successLine(`Session saved as "${saved.name}".`));
+                console.log(`\n  ${c.muted('Resume with')} ${c.warning('/session load <name>')}\n`);
                 return true;
             }
             if (sub === 'load') {
@@ -297,8 +297,8 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             }
             if (sub === 'new') {
                 agent.clearConversation();
-                sessionState.activeName = nameArg ? normalizeSessionName(nameArg) : undefined;
-                console.log(successLine(sessionState.activeName ? `Started new session "${sessionState.activeName}".` : 'Started a fresh session.'));
+                sessionState.activeName = nameArg ? normalizeSessionName(nameArg) : normalizeSessionName();
+                console.log(successLine(`Started new session "${sessionState.activeName}" (auto-saved).`));
                 return true;
             }
             if (sub === 'delete' || sub === 'rm') {
@@ -318,7 +318,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
                 }
                 return true;
             }
-            console.log(errorLine('Usage: /session list|save [name]|load <name>|new [name]|delete <name>'));
+            console.log(errorLine('Usage: /session list|load <name>|new [name]|delete <name>'));
             return true;
         }
         case 'context':
@@ -530,6 +530,56 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             console.log(infoLine(`~${Math.round(approxTokens).toLocaleString()} tokens in conversation`));
             return true;
         }
+        case 'plan': {
+            agent.setMode('plan');
+            console.log(successLine(`Switched to ${modeTag('plan')} mode — read-only. Ikie will research and propose a plan.`));
+            return true;
+        }
+        case 'agent': {
+            agent.setMode('agent');
+            console.log(successLine(`Switched to ${modeTag('agent')} mode — full execution.`));
+            return true;
+        }
+        case 'mode': {
+            const want = (args[0] ?? '').toLowerCase();
+            if (want === 'plan' || want === 'agent') {
+                agent.setMode(want);
+                console.log(successLine(`Mode set to ${modeTag(want)}.`));
+            }
+            else if (want) {
+                console.log(errorLine('Usage: /mode [plan|agent]'));
+            }
+            else {
+                console.log(infoLine(`Current mode: ${modeTag(agent.getMode())}  ${c.muted('· Shift+Tab to toggle')}`));
+            }
+            return true;
+        }
+        case 'usage': {
+            if (!isLoggedIn(config)) {
+                console.log(infoLine('Not signed in. Run /login to connect your ikie account.'));
+                return true;
+            }
+            const apiKey = getApiKey(config);
+            if (!apiKey) {
+                console.log(errorLine('No API key found. Run /login again.'));
+                return true;
+            }
+            try {
+                const res = await fetch(`${IKIE_HOST}/api/usage`, {
+                    headers: { Authorization: `Bearer ${apiKey}` },
+                });
+                if (!res.ok) {
+                    console.log(errorLine(`Couldn't fetch usage (HTTP ${res.status}).`));
+                    return true;
+                }
+                const data = (await res.json());
+                printUsage(data);
+            }
+            catch (err) {
+                console.log(errorLine(`Couldn't reach ikie at ${IKIE_HOST}: ${err instanceof Error ? err.message : String(err)}`));
+            }
+            return true;
+        }
         case 'exit':
         case 'quit':
         case 'q':
@@ -540,6 +590,43 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             return true;
     }
 }
+function fmtUsd(n) {
+    if (n === 0)
+        return '$0.00';
+    if (n < 0.01)
+        return `$${n.toFixed(6)}`;
+    return `$${n.toFixed(2)}`;
+}
+function fmtTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'K';
+    return (n / 1_000_000).toFixed(2).replace(/\.00$/, '') + 'M';
+}
+function printUsage(data) {
+    const s = data.stats;
+    const row = (label, value) => console.log(`  ${c.secondary(label.padEnd(18))} ${c.white(value)}`);
+    console.log(`\n${c.primary.bold('Account Usage')}\n`);
+    row('Credit balance', c.success.bold(fmtUsd(data.balance)).toString());
+    row('Total spent', fmtUsd(s.totalCost));
+    console.log();
+    row('Requests · 30d', s.requests30d.toLocaleString());
+    row('Requests · 24h', s.requests24h.toLocaleString());
+    row('Requests · all', s.totalRequests.toLocaleString());
+    console.log();
+    row('Total tokens', fmtTokens(s.totalTokens));
+    row('Read / Write', `${fmtTokens(s.readTokens)} / ${fmtTokens(s.writeTokens)}`);
+    row('Cached tokens', fmtTokens(s.cachedTokens));
+    console.log();
+    row('Avg latency', s.avgLatencyMs ? `${s.avgLatencyMs}ms` : '—');
+    row('Cache hit rate', `${(s.cacheHitRate * 100).toFixed(1)}%`);
+    if (data.model) {
+        row('Model', data.model.name);
+        row('Context window', `${data.model.context_window.toLocaleString()} tokens`);
+    }
+    console.log(`\n  ${c.muted('Full dashboard:')} ${c.info(`${IKIE_HOST}/dashboard`)}\n`);
+}
 function promptLine(prompt) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -549,6 +636,30 @@ function promptLine(prompt) {
         });
     });
 }
+/**
+ * After a plan-mode turn, ask whether to execute the proposed plan.
+ * Reads a single keypress. Assumes stdin is already in raw mode (it is, during
+ * a turn). Returns true on y / Enter, false otherwise.
+ */
+function confirmExecutePlan() {
+    return new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            resolve(false);
+            return;
+        }
+        process.stdout.write(`\n  ${c.primary('▸')} ${c.white.bold('Plan ready.')} ${c.muted('Execute it now?')}  ` +
+            `${c.success.bold('y')} ${c.muted('yes')}   ${c.error.bold('n')} ${c.muted('keep planning')}\n` +
+            `  ${c.muted('❯')} `);
+        const onKey = (d) => {
+            process.stdin.removeListener('data', onKey);
+            const k = d.toString().toLowerCase();
+            const yes = k === 'y' || k === '\r' || k === '\n';
+            process.stdout.write(yes ? c.success('y\n') : c.muted('n\n'));
+            resolve(yes);
+        };
+        process.stdin.on('data', onKey);
+    });
+}
 function printGoodbye(sessionState, agent, config) {
     const msgs = agent.getConversation();
     const hasConversation = msgs.length > 0;
@@ -562,15 +673,11 @@ function printGoodbye(sessionState, agent, config) {
         }
     }
     console.log(`\n${c.primary.bold('Goodbye!')}\n`);
-    if (sessionState.activeName) {
-        console.log(`  ${c.muted('Your session')} ${c.secondary.bold(sessionState.activeName)} ${c.muted('has been saved.')}`);
-        console.log(`\n  ${c.muted('To continue:')}`);
-        console.log(`    ${c.accent('ikie')} ${c.warning(`/session load ${sessionState.activeName}`)}\n`);
-    }
-    else if (hasConversation) {
-        console.log(`  ${c.warning('\u26A0')}  ${c.muted('Your current conversation was not saved.')}`);
-        console.log(`\n  ${c.muted('To save next time:')}`);
-        console.log(`    ${c.warning('/session save')} ${c.muted('<name>')}\n`);
+    if (sessionState.activeName && hasConversation) {
+        console.log(`  ${c.muted('Your session')} ${c.secondary.bold(sessionState.activeName)} ${c.muted('was saved.')}`);
+        console.log(`\n  ${c.muted('To pick up where you left off:')}`);
+        console.log(`    ${c.accent('ikie')} ${c.warning(`/session load ${sessionState.activeName}`)}`);
+        console.log(`\n  ${c.muted('Or list everything with')} ${c.warning('/session list')}\n`);
     }
     console.log(`  ${c.muted('Happy coding!')}\n`);
 }
@@ -677,7 +784,11 @@ function selectThemeInteractively(rl, config) {
 }
 export async function startREPL(agent, config, projectContext, oneShot) {
     void HISTORY_FILE;
-    if (oneShot) {
+    // A `/`-prefixed launch arg (e.g. `ikie /session load foo`) is a slash
+    // COMMAND, not a prompt — run it after setup, then stay interactive.
+    // A plain launch arg is a one-shot prompt: run it once and exit.
+    const initialCommand = oneShot && oneShot.trim().startsWith('/') ? oneShot.trim() : undefined;
+    if (oneShot && !initialCommand) {
         try {
             await agent.send(oneShot, { autoApprove: config.autoApprove });
         }
@@ -699,7 +810,9 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     let multilineBuffer = '';
     let busy = false;
     let ctrlCCount = 0;
-    const sessionState = {};
+    // Every session auto-saves. Start with a generated name so there's always
+    // somewhere to persist to; /session load can resume it later.
+    const sessionState = { activeName: normalizeSessionName() };
     const imageState = { nextId: 1, pending: [] };
     let pasteSeq = 0;
     let pasteMode = false;
@@ -731,6 +844,18 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     };
     const routeInputData = (data) => {
         const text = data.toString('utf8');
+        // Shift+Tab (CSI Z) → cycle agent⇄plan mode live at the prompt.
+        if (text === '\x1b[Z') {
+            const next = agent.getMode() === 'agent' ? 'plan' : 'agent';
+            agent.setMode(next);
+            const saved = rl.line || '';
+            process.stdout.write('\r\x1b[2K'); // clear the current prompt line
+            process.stdout.write(`  ${c.muted('▸')} ${modeTag(next)} ${c.muted('mode')}\n`);
+            printPromptHeader(next);
+            rl.setPrompt(PROMPT);
+            process.stdout.write(rl.getPrompt() + saved);
+            return;
+        }
         // Check for Ctrl+V (0x16) - try to paste image from clipboard
         if (data.length === 1 && data[0] === 0x16) {
             // Check if clipboard has an image
@@ -813,7 +938,7 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             rl.setPrompt(CONTINUE_PROMPT);
         }
         else {
-            printPromptHeader();
+            printPromptHeader(agent.getMode());
             if (imageState.pending.length) {
                 const labels = imageState.pending.map(image => `[Image #${image.id}]`).join(' ');
                 process.stdout.write(`${c.muted('   attached')} ${c.secondary(labels)}\n`);
@@ -883,8 +1008,10 @@ export async function startREPL(agent, config, projectContext, oneShot) {
         const userContent = buildUserContent(agentInput, imagesForTurn);
         imageState.pending = [];
         let restoredImages = false;
+        // Clear the (now-submitted) prompt line. The agent's InlineSpinner provides
+        // the "Working… · Esc to interrupt" feedback and clears itself when done, so
+        // we don't print a static line here (it would never get cleared).
         process.stdout.write('\r\x1b[2K');
-        process.stdout.write(`${c.muted('  Working. Press Esc to interrupt.')}\n`);
         busy = true;
         rl.pause();
         const taskStartedAt = Date.now();
@@ -926,6 +1053,24 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             if (sessionState.activeName && !abortController.signal.aborted) {
                 saveSession(sessionState.activeName, config.model, agent.getConversation());
             }
+            // Plan mode: a plan was just proposed — offer to execute it.
+            if (agent.getMode() === 'plan' && !abortController.signal.aborted) {
+                process.stdin.removeListener('data', cancelHandler);
+                const go = await confirmExecutePlan();
+                process.stdin.on('data', cancelHandler);
+                if (go && !abortController.signal.aborted) {
+                    agent.setMode('agent');
+                    process.stdout.write(`  ${c.muted('→ switching to')} ${modeTag('agent')} ${c.muted('mode, executing…')}\n`);
+                    await agent.send('Execute the plan you just proposed. Make the changes now.', {
+                        autoApprove: config.autoApprove,
+                        signal: abortController.signal,
+                        startedAt: taskStartedAt,
+                    });
+                    if (sessionState.activeName && !abortController.signal.aborted) {
+                        saveSession(sessionState.activeName, config.model, agent.getConversation());
+                    }
+                }
+            }
         }
         catch (err) {
             if (!abortController.signal.aborted) {
@@ -944,13 +1089,16 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             }
             const elapsed = formatElapsed(Date.now() - taskStartedAt);
             process.stdin.removeListener('data', cancelHandler);
-            if (process.stdin.isTTY)
-                process.stdin.setRawMode(false);
             process.stdin.pause();
             restoreStdinListeners(savedDataListeners, savedKeypressListeners);
             busy = false;
             ctrlCCount = 0;
             rl.resume();
+            // readline was created with terminal:true and owns echo while in raw mode.
+            // Re-enable raw mode (the turn's cancel handler may have toggled it) so the
+            // TTY doesn't also echo input — otherwise every line is echoed twice.
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(true);
             const status = abortController.signal.aborted
                 ? c.warning(formatTaskTimeline(agent, elapsed, 'cancelled'))
                 : taskFailed
@@ -964,5 +1112,15 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     rl.on('line', (raw) => {
         chain = chain.then(() => handleLine(raw));
     });
+    // If launched with a slash command (e.g. `ikie /session load foo`), run it
+    // once now, then hand control to the user with the result already applied.
+    if (initialCommand) {
+        try {
+            await handleSlashCommand(initialCommand, agent, config, projectContext, rl, sessionState, imageState);
+        }
+        catch (err) {
+            console.error(errorLine(err instanceof Error ? err.message : String(err)));
+        }
+    }
     showPrompt();
 }

package/dist/theme.d.ts

@@ -38,7 +38,8 @@ export declare const c: {
 export declare function stripAnsi(str: string): string;
 export declare const BANNER_ROWS = 9;
 export declare function drawBanner(model: string): void;
-export declare function printPromptHeader(): void;
+export declare function modeTag(mode: 'agent' | 'plan'): string;
+export declare function printPromptHeader(mode?: 'agent' | 'plan'): void;
 export declare const PROMPT: string;
 export declare const CONTINUE_PROMPT: string;
 export declare class InlineSpinner {

package/dist/theme.js

@@ -248,22 +248,24 @@ export function drawBanner(model) {
         '',
         `${c.muted('/help')} ${c.muted('·')} ${c.muted('/theme')} ${c.muted('·')} ${c.muted('Esc cancels running work')}`,
     ];
-    process.stdout.write(c.muted('╭' + '─'.repeat(innerWidth) + '╮') + '\n');
+    process.stdout.write('\n');
     for (let i = 0; i < Math.max(art.length, meta.length); i++) {
         const artLine = art[i] ?? '';
         const artColored = chalk.hex(colors[i % colors.length]).bold(padVisible(artLine, artWidth));
-        const metaLine = meta[i] ? `  ${c.muted('│')}  ${meta[i]}` : '';
-        const row = `${artColored}${metaLine}`;
-        process.stdout.write(`${c.muted('│')} ${padVisible(row, innerWidth - 1)}${c.muted('│')}\n`);
+        const metaLine = meta[i] ? `   ${meta[i]}` : '';
+        process.stdout.write(`  ${artColored}${metaLine}\n`);
     }
-    process.stdout.write(c.muted('╰' + '─'.repeat(innerWidth) + '╯') + '\n');
+    process.stdout.write('\n');
 }
-export function printPromptHeader() {
+export function modeTag(mode) {
+    return mode === 'plan' ? c.warning.bold('plan') : c.success('agent');
+}
+export function printPromptHeader(mode = 'agent') {
     const cwdName = basename(process.cwd()) || '/';
     const branch = getGitBranchFast();
     const gitSegment = branch ? ` ${c.muted('on')} ${c.secondary(branch)}` : '';
     const themeSegment = ` ${c.muted('theme')} ${c.secondary(activeTheme.name)}`;
-    process.stdout.write(`\n${c.primary('╭─')} ${c.primary.bold('ikie')}${gitSegment}${themeSegment} ${c.muted('in')} ${c.accent(cwdName)}\n`);
+    process.stdout.write(`\n${c.primary('╭─')} ${c.primary.bold('ikie')} ${c.muted('·')} ${modeTag(mode)}${gitSegment}${themeSegment} ${c.muted('in')} ${c.accent(cwdName)}\n`);
 }
 export const PROMPT = c.primary('╰─❯ ');
 export const CONTINUE_PROMPT = c.primary('│  ');
@@ -326,21 +328,45 @@ export class InlineSpinner {
         this.draw();
     }
 }
+// Maps a tool name to a clean verb + a dot color reflecting its effect.
+// Read-only tools are calm (info), mutating tools warn, exec/agent stand out.
+function toolMeta(rawName) {
+    const base = rawName.split(/\s|×/)[0];
+    switch (base) {
+        case 'read_file': return { verb: 'read', tint: c.info };
+        case 'write_file': return { verb: 'write', tint: c.warning };
+        case 'edit_file': return { verb: 'edit', tint: c.warning };
+        case 'bash': return { verb: 'run', tint: c.accent };
+        case 'list_dir': return { verb: 'list', tint: c.info };
+        case 'grep': return { verb: 'grep', tint: c.info };
+        case 'search_files': return { verb: 'find', tint: c.info };
+        case 'memory_write': return { verb: 'memory', tint: c.secondary };
+        case 'spawn_agent': return { verb: 'agent', tint: c.secondary };
+        case 'ask_user': return { verb: 'ask', tint: c.info };
+        default: return { verb: base, tint: c.primary };
+    }
+}
 export function toolLine(name, args) {
-    const tag = name === 'read_file' ? 'READ' :
-        name === 'write_file' ? 'WRITE' :
-            name === 'edit_file' ? 'EDIT' :
-                name === 'bash' ? 'EXEC' :
-                    name === 'list_dir' ? 'LIST' :
-                        name === 'grep' || name === 'search_files' ? 'FIND' : 'TOOL';
-    return `${c.primary('╭─')} ${c.accent.bold(`[${tag}]`)} ${c.warning.bold(name)}${c.muted('(')}${c.accent(args)}${c.muted(')')}`;
+    const { verb, tint } = toolMeta(name);
+    // Surface a "×N" batch suffix as a subtle count badge.
+    const countMatch = name.match(/×(\d+)/);
+    const badge = countMatch ? ` ${c.muted(`×${countMatch[1]}`)}` : '';
+    const label = c.white.bold(verb.padEnd(6));
+    return `${tint('●')} ${label}${badge} ${c.dim(args)}`;
 }
 export function toolSuccessLine(ms, preview) {
-    const tail = preview ? ` ${c.muted('│')} ${c.dim(preview)}` : '';
-    return `${c.primary('╰─')} ${c.success('ok')} ${c.muted(`${ms}ms`)}${tail}`;
+    const time = c.muted(formatDuration(ms));
+    const tail = preview ? `  ${c.dim(preview)}` : '';
+    return `  ${c.muted('⎿')} ${time}${tail}`;
 }
 export function toolErrorLine(msg) {
-    return `${c.primary('╰─')} ${c.error('err')} ${c.error(msg)}`;
+    return `  ${c.muted('⎿')} ${c.error('failed')} ${c.error(msg)}`;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = ms / 1000;
+    return s < 10 ? `${s.toFixed(1)}s` : `${Math.round(s)}s`;
 }
 export function successLine(msg) {
     return `  ${c.success('ok')} ${c.muted(msg)}`;
@@ -355,11 +381,12 @@ export function infoLine(msg) {
     return `  ${c.info('info')} ${c.muted(msg)}`;
 }
 export function permissionPrompt(toolName, preview) {
-    return (`\n  ${c.primary('╭─')} ${c.warning.bold('permission')} ${c.white.bold('Allow')} ${c.warning.bold(toolName)}${c.muted('?')}\n` +
-        `  ${c.primary('│')}  ${c.muted(preview)}\n` +
-        `  ${c.primary('│')}  ${c.muted('[')}${c.success.bold('y')}${c.muted(']')} allow  ` +
-        `${c.muted('[')}${c.error.bold('n')}${c.muted(']')} deny  ` +
-        `${c.muted('[')}${c.info.bold('a')}${c.muted(']')} always allow  ` +
-        `${c.muted('[')}${c.muted.bold('!')}${c.muted(']')} always deny\n` +
-        `  ${c.primary('╰─❯')} `);
+    const { verb, tint } = toolMeta(toolName);
+    return (`\n  ${tint('●')} ${c.white.bold('permission')} ${c.muted('·')} ${c.white(verb)} ${c.dim(preview)}\n` +
+        `  ${c.muted('⎿')} ` +
+        `${c.success.bold('y')} ${c.muted('allow')}   ` +
+        `${c.error.bold('n')} ${c.muted('deny')}   ` +
+        `${c.info.bold('a')} ${c.muted('always')}   ` +
+        `${c.muted.bold('!')} ${c.muted('never')}\n` +
+        `  ${c.muted('❯')} `);
 }

package/dist/tools.d.ts

@@ -1,5 +1,6 @@
 import type OpenAI from 'openai';
 export declare const TOOL_DEFS: OpenAI.Chat.ChatCompletionTool[];
 export declare const SAFE_TOOLS: Set<string>;
+export declare const PLAN_TOOLS: Set<string>;
 export declare function formatToolArgs(name: string, input: Record<string, unknown>): string;
 export declare function executeTool(name: string, input: Record<string, unknown>): Promise<string>;

package/dist/tools.js

@@ -172,6 +172,10 @@ export const TOOL_DEFS = [
 // spawn_agent is "safe" at the dispatch layer — the tools the sub-agent itself
 // runs go through their own approval inside the sub-agent loop.
 export const SAFE_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'memory_write', 'spawn_agent', 'ask_user']);
+// Tools available in PLAN mode — read-only exploration plus delegation/questions.
+// Everything that mutates the filesystem or runs commands (write_file, edit_file,
+// bash, memory_write) is intentionally excluded so plan mode can only research.
+export const PLAN_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'spawn_agent', 'ask_user']);
 // ─── Display helpers ──────────────────────────────────────────────────────────
 export function formatToolArgs(name, input) {
     const p = (v) => v != null && v !== 'undefined' ? String(v) : '(missing)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikie-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agentic coding CLI — your terminal AI pair programmer",
   "type": "module",
   "bin": {