ikie-cli 0.1.32 → 0.1.33

package/README.md

@@ -1,43 +1,189 @@
-# ikie
+# Ikie
 
-**Agentic coding CLI** — your terminal AI pair programmer.
+**Agentic coding CLI — your AI pair programmer in the terminal.**
+
+Ikie reads, writes, and refactors code, runs commands, searches the web, and
+drives multi-step engineering tasks autonomously — all from your shell, with a
+polished interactive REPL and a one-shot mode for quick jobs.
 
 ```bash
 npm install -g ikie-cli
 ikie login
-ikie "write a rust web server"
+ikie "write a rust web server with graceful shutdown"
 ```
 
-## Features
+---
+
+## Highlights
+
+- **Autonomous agent loop** — Ikie plans, edits files, runs builds/tests, reads
+  the errors, and self-corrects until the task is done.
+- **Plan mode & agent mode** — research read-only and propose a plan, or execute
+  with full tool access. Toggle live with **Shift+Tab**.
+- **28 built-in tools** — files, shell, search, git, web, memory, sub-agents.
+- **Skills** — installable instruction packs that give Ikie expert knowledge for
+  a specific kind of task (UI/UX, research, framework conventions, …).
+- **MCP support** — extend Ikie with Model Context Protocol servers (GitHub,
+  databases, browser automation, and any custom MCP).
+- **Polished terminal UX** — markdown rendering, slash-command menu, 7 color
+  themes, image paste (Ctrl+V), session save/load, and live token/usage tracking.
+- **Safe by default** — mutating actions ask for permission once (press `a` to
+  always-allow for the session); reads of secret files (`.env`, keys) are guarded.
 
-- 12 built-in tools: read/write/edit files, bash, search, grep, memory, agent spawn, web fetch & search
-- Interactive REPL with slash commands, markdown rendering, and session management
-- One-shot mode: `ikie "your prompt"`
-- Image paste support (Ctrl+V)
-- Theming (7 color schemes)
+---
 
 ## Quick start
 
 ```bash
-# Install
-npm install -g ikie
+# 1. Install globally
+npm install -g ikie-cli
 
-# Sign in to your ikie account
+# 2. Sign in to your Ikie account
 ikie login
 
-# Start coding
-ikie "refactor this file and add tests"
+# 3a. One-shot — run a single task and exit
+ikie "add input validation to src/api/users.ts and write tests"
+
+# 3b. Interactive — start a REPL session
+ikie
+```
+
+**Requirements:** Node.js 20+ and an Ikie account (`ikie login`).
+
+---
+
+## Modes
+
+Ikie runs in one of two modes, shown in the prompt header:
+
+| Mode | What it can do |
+| --- | --- |
+| **agent** *(default)* | Full access — edit files, run commands, everything. |
+| **plan** | Read-only research. Ikie explores and proposes a plan but makes no changes until you approve. |
+
+Switch any time with **Shift+Tab** (toggles in place), or with `/plan`, `/agent`,
+and `/mode`. When a plan is approved, Ikie automatically switches to agent mode
+and carries it out.
+
+---
+
+## Tools
+
+Ikie has 28 built-in tools, grouped by purpose:
+
+- **Files** — `read_file`, `write_file`, `edit_file` (surgical exact-string edits), `list_dir`
+- **Search** — `search_files` (glob), `grep` (regex over contents)
+- **Shell** — `bash` (builds, tests, package managers; `&` backgrounds long-running processes)
+- **Git** — `git_status`, `git_diff`, `git_log`, `git_commit`, `git_branch`
+- **Web** — `fetch_url` (read any page as text), `web_search` (no extra API key — your login is enough)
+- **Memory** — `memory_write` (persist notes across sessions, project- or global-scoped)
+- **Delegation** — `spawn_agent` (hand isolated/parallel work to a focused sub-agent), `ask_user`
+- **Skills** — `use_skill`, `install_skill`, `remove_skill`
+- **MCP** — `mcp_list`, `mcp_add`, `mcp_install`, `mcp_start`, `mcp_stop`, `mcp_call`, `mcp_uninstall`
+- **Mode** — `switch_mode`
+
+---
+
+## Skills
+
+Skills are curated instruction packs (and optional bundled scripts) that load on
+demand when a task matches them. Install from a git URL or local path:
+
+```bash
+ikie skills install https://github.com/user/some-skill.git
+ikie skills list
+ikie skills remove some-skill
+```
+
+Inside a session, Ikie loads a matching skill automatically before doing the work.
+You can also manage them with `/skills`.
+
+---
+
+## MCP (Model Context Protocol)
+
+Extend Ikie with external MCP servers. Paste a Claude/Cline-style config and Ikie
+will wire it up:
+
+```
+claude mcp add magic --scope user --env API_KEY="…" -- npx -y @21st-dev/magic@latest
+```
+
+Then start it and its tools become available:
+
+```
+/  (use the slash menu) → mcp_start magic
 ```
 
-## Web access
+Built-in MCPs include **filesystem**, **github**, **database** (SQLite/Postgres),
+and **puppeteer** (browser automation).
+
+---
+
+## In-session commands
+
+Type `/` to open the command menu. Highlights:
+
+| Command | Description |
+| --- | --- |
+| `/help` | Show all commands |
+| `/plan` · `/agent` · `/mode` | Switch or show mode *(Shift+Tab toggles)* |
+| `/clear` | Clear conversation history |
+| `/compact` | Summarize the conversation to free up context |
+| `/session list\|load\|new\|delete` | Manage saved sessions |
+| `/memory [save]` | View or save persistent notes |
+| `/context` | Show the detected project context |
+| `/model <name>` · `/models` | Switch or list models |
+| `/settings [show\|model\|reset]` | View/change persisted settings |
+| `/skills` | List, show, install, or remove skills |
+| `/theme [name]` | Change the color theme |
+| `/usage` · `/tokens` | Account usage/credit and token estimate |
+| `/rpm <n>` | Set the model request-per-minute limit |
+| `/onboarding` | Re-run the first-time tutorial |
+| `!<cmd>` | Run a shell command directly (output lands in the session) |
+
+---
+
+## CLI usage
+
+```text
+ikie "<message>"            One-shot command
+ikie                        Start an interactive session
+ikie login                  Sign in to your Ikie account
+ikie logout                 Sign out
+ikie skills <…>             Manage skills (list / install / remove)
+
+Flags:
+  -m, --model <id>          Use a specific model
+  -y, --yes                 Auto-approve all tool executions
+      --rpm <n>             Max model requests per minute (default: 10)
+      --verbose             Debug output
+      --onboarding          Re-run first-time onboarding
+  -h, --help                Show help
+  -v, --version             Show version
+```
+
+---
+
+## Themes
+
+Seven built-in color schemes: **nebula**, **cyberpunk**, **dracula**, **forest**,
+**slate**, **amber**, and **aurora**. Switch with `/theme <name>`.
+
+---
+
+## Permissions & safety
 
-ikie can read pages and search the web:
+- `bash`, `write_file`, and `edit_file` ask before running. Press `y` to allow
+  once, `a` to always-allow that tool for the session, `n`/`!` to deny.
+- Reading project files is silent; reading credential files (`.env`, `.ssh`, keys,
+  `.npmrc`, …) prompts first.
+- Ikie warns before any command that could terminate its own session by killing
+  processes on its host port.
+- Run with `-y` / `--yes` to auto-approve everything (use with care).
 
-- **`fetch_url`** — read any page or URL (HTML is stripped to plain text).
-- **`web_search`** — search the web and get back titles, URLs, and snippets. Powered by the ikie
-  server — no separate search API key needed; your ikie login is enough.
+---
 
-## Requirements
+## License
 
-- Node.js 20+
-- An ikie account — sign in with `ikie login`
+MIT — see [LICENSE](./LICENSE).

package/dist/agent.js

@@ -1000,13 +1000,19 @@ to disambiguate. Make the smallest edit that fixes the root cause; don't reflow
 untouched code. Use \`write_file\` only for brand-new files or deliberate full rewrites,
 and always write the COMPLETE content.
 
-**5. bash hygiene.** It's non-interactive (pass \`-y\`/\`--yes\`); quote paths with spaces;
-chain with \`&&\` so a failure stops the chain; background long-running servers with a
-trailing \`&\`; raise \`timeout_ms\` for slow installs. Check the exit code — a non-zero
-exit means it failed, so read the error rather than moving on. **Avoid killing
-processes by port** (\`kill $(lsof -ti:PORT)\`, \`fuser -k\`): it can match ikie's own
-connection and end the session — target a specific PID, or stop the process you
-started, instead.
+**5. bash hygiene.** By default it's non-interactive, so prefer flags that skip
+prompts (\`-y\`/\`--yes\`, or pass every option explicitly, e.g. \`create-next-app\`'s
+\`--ts --tailwind --eslint --app\`). But when a command shows an **interactive
+arrow-key menu or prompt that has no flag** (e.g. \`shadcn init\`'s component-library
+picker), do NOT keep retrying with piped input — call bash with \`interactive: true\`.
+That hands the real terminal to the command so the **user answers directly**; output
+isn't captured, so afterward read any files it created to see the result. Also: quote
+paths with spaces; chain with \`&&\` so a failure stops the chain; background
+long-running servers with a trailing \`&\`; raise \`timeout_ms\` for slow installs. Check
+the exit code — a non-zero exit means it failed, so read the error rather than moving
+on. **Avoid killing processes by port** (\`kill $(lsof -ti:PORT)\`, \`fuser -k\`): it can
+match ikie's own connection and end the session — target a specific PID, or stop the
+process you started, instead.
 
 **6. Recover from errors deliberately.** When a tool fails, read the actual message,
 form a hypothesis, and change your approach — never re-run the identical failing call
@@ -1024,7 +1030,7 @@ only the non-obvious. Use \`ask_user\` only when truly blocked on a decision you
 - \`write_file\`: Create new files or full rewrites
 - \`edit_file\`: Replace exact strings (preferred for modifications)
 - \`bash\`: Run shell commands (build, test, git, etc.). Commands ending with & run detached in background.
-  **IMPORTANT:** The bash tool is non-interactive — it cannot handle prompts. For commands that ask questions (create-next-app, npm init, etc.), use \`--yes\`, \`-y\`, or pipe through \`yes\` to skip all prompts. For long-running downloads (npx installs), request \`timeout_ms\` up to 300000.
+  **IMPORTANT:** By default it's non-interactive — for commands that ask questions (create-next-app, npm init, etc.), skip prompts with \`--yes\`/\`-y\` or explicit flags. For prompts with no flag (e.g. an arrow-key menu), set \`interactive: true\` so the user answers in the real terminal. For long-running downloads (npx installs), request \`timeout_ms\` up to 300000.
 - \`list_dir\`: Explore directory structure
 - \`search_files\`: Find files by glob pattern
 - \`grep\`: Search file contents by regex

package/dist/repl.js

@@ -981,6 +981,16 @@ export async function startREPL(agent, config, projectContext, oneShot) {
         historySize: MAX_HISTORY,
         prompt: PROMPT,
     });
+    // Enable bracketed-paste mode so the terminal wraps pasted text in
+    // \x1b[200~ … \x1b[201~ markers. This lets a multi-chunk paste (a long
+    // paragraph the TTY delivers across several reads) be coalesced into ONE
+    // paste instead of being split into several. Disabled again on exit.
+    const setBracketedPaste = (on) => {
+        if (process.stdout.isTTY)
+            process.stdout.write(on ? '\x1b[?2004h' : '\x1b[?2004l');
+    };
+    setBracketedPaste(true);
+    process.on('exit', () => setBracketedPaste(false));
     let multilineBuffer = '';
     let busy = false;
     let ctrlCCount = 0;
@@ -1083,6 +1093,13 @@ export async function startREPL(agent, config, projectContext, oneShot) {
         const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
         if (!normalized)
             return;
+        // Short, single-line pastes (a word, a path, a URL) belong inline as if
+        // typed — only collapse multi-line or long pastes into a [Pasted #N] block.
+        if (!normalized.includes('\n') && normalized.length <= 200) {
+            forwardToReadline(Buffer.from(normalized, 'utf8'));
+            updateMenu();
+            return;
+        }
         const token = `[Pasted #${++pasteSeq}: ${pasteSummary(normalized)}]`;
         pastedBlocks.set(token, normalized);
         rl.write(token);
@@ -1250,6 +1267,7 @@ export async function startREPL(agent, config, projectContext, oneShot) {
         rl.prompt();
     };
     rl.on('close', () => {
+        setBracketedPaste(false);
         printGoodbye(sessionState, agent, config);
         process.exit(0);
     });

package/dist/tools.js

@@ -64,6 +64,7 @@ export const TOOL_DEFS = [
                     command: { type: 'string', description: 'Shell command' },
                     timeout_ms: { type: 'number', description: 'Timeout ms (default 30000)' },
                     cwd: { type: 'string', description: 'Working directory' },
+                    interactive: { type: 'boolean', description: 'Set true for commands that need an interactive terminal — ones that show arrow-key menus or prompts that cannot be skipped with flags (e.g. `shadcn init`, `create-next-app`, `npm init` without -y). The command is connected to the real terminal so the USER answers the prompts directly. Output is shown live, not captured, so the result only reports the exit status — read any files it creates afterward.' },
                 },
                 required: ['command'],
             },
@@ -623,6 +624,9 @@ async function bash(input) {
         cwd = resolve(input.cwd);
     }
     const command = input.command.trim();
+    if (input.interactive) {
+        return bashInteractive(command, cwd);
+    }
     if (command.endsWith('&')) {
         const bgCmd = command.slice(0, -1).trim();
         try {
@@ -670,6 +674,64 @@ async function bash(input) {
         return `Exit ${e.code ?? 1}\n${parts.join('\n')}`;
     }
 }
+/**
+ * Runs a command attached to the real terminal (stdio: 'inherit') so the USER
+ * can answer interactive prompts (arrow-key menus, y/N questions) that the
+ * non-interactive path cannot handle. Temporarily detaches the REPL's own stdin
+ * listeners and raw mode while the child owns the terminal, then restores them.
+ * Output is not captured — only the exit status is reported back to the agent.
+ */
+function bashInteractive(command, cwd) {
+    return new Promise((resolvePromise) => {
+        const stdin = process.stdin;
+        const isTTY = Boolean(stdin.isTTY);
+        const wasRaw = isTTY ? Boolean(stdin.isRaw) : false;
+        // Save and detach whatever the REPL has on stdin (cancel handler, etc.) so
+        // the child receives keystrokes directly.
+        const saved = isTTY ? stdin.rawListeners('data').slice() : [];
+        for (const l of saved)
+            stdin.removeListener('data', l);
+        const restore = () => {
+            if (isTTY) {
+                try {
+                    stdin.setRawMode(wasRaw);
+                }
+                catch { /* ignore */ }
+                if (process.stdout.isTTY)
+                    process.stdout.write('\x1b[?2004h'); // re-arm bracketed paste
+            }
+            for (const l of saved)
+                stdin.on('data', l);
+        };
+        if (isTTY) {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { /* ignore */ }
+            if (process.stdout.isTTY)
+                process.stdout.write('\x1b[?2004l'); // disable bracketed paste for the child
+        }
+        process.stdout.write('\n');
+        try {
+            const isWindows = process.platform === 'win32';
+            const child = spawn(isWindows ? 'cmd.exe' : 'bash', isWindows ? ['/d', '/s', '/c', command] : ['-c', command], { cwd, stdio: 'inherit' });
+            child.on('error', (err) => {
+                restore();
+                resolvePromise(`Error running interactive command: ${sanitizeError(err)}`);
+            });
+            child.on('exit', (code) => {
+                restore();
+                resolvePromise(code === 0
+                    ? '(interactive command completed — output was shown to the user; read any created/changed files to see the result)'
+                    : `Exit ${code ?? 1} (interactive command)`);
+            });
+        }
+        catch (err) {
+            restore();
+            resolvePromise(`Error running interactive command: ${sanitizeError(err)}`);
+        }
+    });
+}
 function listDir(input) {
     const root = resolve(input.path ?? '.');
     if (!existsSync(root))

package/package.json

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