miii-agent 0.1.30 → 0.1.31

package/README.md

@@ -1,9 +1,9 @@
-<h1 align="center">miii</h1>
+<h1 align="center">miii — Local AI Coding Agent for Your Terminal</h1>
 
 <p align="center">
-  <strong>Cursor / Claude Code, but local.</strong><br>
-  An offline AI pair-programmer in your terminal, powered by Ollama.<br>
-  Private by default. Free forever.
+  <strong>An open-source, offline alternative to Claude Code, Cursor, and GitHub Copilot.</strong><br>
+  A private AI pair-programmer in your terminal, powered by Ollama and any local LLM.<br>
+  Private by default. Free forever. Works offline.
 </p>
 
 <p align="center">
@@ -15,26 +15,41 @@
 </p>
 
 <p align="center">
-  <img src="demo3.gif" alt="miii demo">
+  <img src="demo3.gif" alt="miii local AI coding agent terminal demo powered by Ollama">
+</p>
+
+<p align="center">
+  🔒 <strong>100% local</strong> — your code never leaves your machine &nbsp;·&nbsp;
+  💸 <strong>Free</strong> — no API keys, no per-token billing &nbsp;·&nbsp;
+  ⚡ <strong>Offline</strong> — runs on your own GPU
 </p>
 
 ---
 
-## What is this?
+## What is miii? — a local AI coding agent
 
 miii lives in your terminal and codes alongside you — reading files, writing features, running tests, fixing bugs. The twist: it runs on **your** hardware, powered by [Ollama](https://ollama.com) (or any local OpenAI-compatible server like [llama.cpp](https://github.com/ggml-org/llama.cpp) / [LM Studio](https://lmstudio.ai)).
 
-Your code never leaves your disk. There's nothing to log in to. Pull a model, type `miii`, go.
+Your code never leaves your disk. There's nothing to log in to. Pull a model, type `miii`, go. It's the open-source, offline answer to cloud coding assistants like Claude Code, Cursor, and GitHub Copilot.
 
-## Try it in 30 seconds
+## Install (macOS, Linux, Windows)
 
 **macOS / Linux:**
 
 ```bash
 ollama pull qwen2.5-coder:14b   # any coding model works
+```
+
+**Which model should I use?**
+- **Low VRAM (8GB):** `qwen2.5-coder:7b` (Fast, capable)
+- **Mid VRAM (16-24GB):** `qwen2.5-coder:14b` (Sweet spot)
+- **High VRAM (48GB+):** `qwen2.5-coder:32b` (Powerhouse)
+
+```bash
 curl -fsSL https://raw.githubusercontent.com/maruakshay/miii-cli/main/install.sh | sh
 miii
 ```
+*(The installer downloads the pre-compiled binary and adds it to your local path)*
 
 **Windows (PowerShell):**
 
@@ -77,7 +92,7 @@ miii --version  # what you're running
 Opt out of background updates by adding `"autoUpdate": false` to `~/.miii/config.json`,
 or re-run the install script (`curl … | sh`) any time to update by hand.
 
-## Why local-first?
+## Why local-first? Private, free, offline
 
 Most "AI coding tools" are just wrappers around a cloud API — slow, metered, and they ship your private codebase to someone else's server.
 
@@ -89,13 +104,16 @@ Most "AI coding tools" are just wrappers around a cloud API — slow, metered, a
 | Offline      | No                    | Yes                          |
 | Latency      | Network + queue       | Your GPU only                |
 
-It doesn't just chat, either — it decomposes the problem, calls tools, and checks its own work before claiming victory.
+It doesn't just chat, either — it follows a **Plan $\rightarrow$ Act $\rightarrow$ Observe** loop:
+1. **Plan**: Decomposes the problem into a sequence of concrete steps.
+2. **Act**: Calls the necessary tools to gather context or modify code.
+3. **Observe**: Verifies the result and adjusts the plan until the goal is met.
 
 ## Five letters, five ideas
 
 **s**mall · **s**imple · **s**mart · **s**trategic · **s**emantic — a tiny codebase you can read in an afternoon, no config ceremony, plans before it acts, and operates on the *meaning* of your code, not blind text matching.
 
-## A few things that make it fun
+## Features
 
 - **🧪 `miii doctor`** — not every local model can drive an agent. Doctor runs your models through real engineering tasks and tells you which ones actually deliver.
   ```bash
@@ -189,6 +207,15 @@ The model pages through the middle with ranged `read_file` reads. Spill files ar
 <details>
 <summary><strong>Development</strong></summary>
 
+**Project Architecture:**
+```text
+src/
+ ├── agent/    # The core reasoning loop
+ ├── tools/    # Implementation of read/write/bash
+ ├── terminal/ # UI and input handling
+ └── config/   # Settings and provider logic
+```
+
 ```bash
 git clone https://github.com/maruakshay/miii-cli.git
 cd miii-cli
@@ -211,6 +238,26 @@ npm run build && npm link   # restore later with: npm install -g miii-agent
 
 ---
 
+## FAQ
+
+**Does miii work without internet?**
+Yes. Once you've pulled a model with Ollama, miii runs fully offline. No network calls, no account, no cloud.
+
+**Is my code sent anywhere?**
+No. Every file read, edit, and model inference happens on your machine. Your codebase never leaves your disk.
+
+**Which model is best for coding?**
+Depends on VRAM: `qwen2.5-coder:7b` (8GB), `qwen2.5-coder:14b` (16–24GB, the sweet spot), `qwen2.5-coder:32b` (48GB+). Run `miii doctor` to grade your installed models on real engineering tasks.
+
+**How is miii different from Claude Code, Cursor, or GitHub Copilot?**
+Claude Code, Cursor, and Copilot are cloud services — metered, account-gated, and they ship your code to a third-party server. miii is open-source, free, and runs entirely on your hardware. Same terminal-agent workflow as Claude Code, but on your own local model.
+
+**How is it different from Continue.dev?**
+Continue.dev is an IDE extension. miii is a standalone terminal agent — no editor required — with a Plan → Act → Observe loop, permission-gated tools, and lossless output spill built in.
+
+**Do I need a GPU?**
+No, but it helps. Smaller models run on CPU; a GPU makes larger models fast enough for real work.
+
 ## Status
 
 **MVP.** Core agent loop is stable; actively refining tool execution, streaming, and the permission model. PRs welcome — fork it, break it, improve it.

package/dist/cli.js

@@ -1445,6 +1445,7 @@ Ask in a numbered list. One round of questions per turn. Then wait.
 - After a tool result, move directly to the next tool call or the final answer. Do not restate what the previous tool did.
 - Every tool call MUST carry a complete, valid arguments object: all required fields present, correct types, valid JSON. Never emit a call with empty, partial, or placeholder arguments.
 - WRONG (leaks as text, nothing runs): writing \`call:some_tool{"foo":"bar"}\` or a fenced JSON block in your reply. RIGHT: emit it as a native function call with a full arguments object.
+- Batch independent tool calls in a SINGLE turn \u2014 parallel, not serial. If two reads, greps, or searches do not depend on each other's output, emit them together. Only serialize when a later call needs an earlier result.
 
 # Tools
 You have access to the following tools. Call them via the function-calling interface.
@@ -1454,14 +1455,33 @@ ${toolLines}
 - When you need to act on the filesystem or run a command, emit a tool call.
 - After each tool result, decide: more tool calls, or a final plain-text answer.
 - Stop emitting tool calls when GOAL is met. Reply with a concise plain-text final message confirming CRITERION is satisfied.
+- After the work is done, always close by asking the user what they want to do next \u2014 a brief, specific prompt (offer the most likely follow-ups when obvious). One line, no filler.
 
 # Rules
 - Always read a file before updating it. Never edit, overwrite, or create-over a file you have not read first this turn.
 - Prefer editing existing files over creating new ones.
+- To change an existing file, use edit_file with a small, targeted old_str/new_str diff \u2014 never rewrite the whole file with write_file. Reserve write_file for brand-new files or small ones. A full-file write_file on a large file risks getting cut off at the output token limit mid-write; a targeted edit_file stays small and avoids that.
+- When a new file's content is large, create it with write_file for the first portion, then append the rest with successive edit_file calls. Keep every write small.
 - For edit_file, make old_str unique by including surrounding context, or set replace_all to change every occurrence.
 - Never invent file paths. Read, glob, or grep before editing.
 - No empty filler or robotic boilerplate. A brief, genuine warm touch (see Tone and voice) is welcome; hollow pleasantries and reflexive apologies are not.
 
+# Scope discipline
+- Do ONLY what the user asked. No unrequested refactors, renames, reformatting, or "while I'm here" edits.
+- If you spot an unrelated issue worth fixing, mention it in your final message \u2014 do not fix it unprompted.
+- Touch the fewest files needed. A one-line request gets a one-line change, not a redesign.
+
+# Secrets and safety
+- Never print, log, or echo secrets, API keys, tokens, passwords, or \`.env\` values. Redact them if you must reference one.
+- Never write credentials into source, commits, or output. If a secret is needed, read it from the environment or config.
+- Do not exfiltrate file contents to external services without the user asking.
+
+# Git and commits
+- Do NOT commit, push, or create branches/PRs unless the user explicitly asks.
+- When asked to commit: never commit on the main branch \u2014 branch first. Stage only files relevant to the change; never blanket \`git add -A\` without checking what it sweeps in.
+- Write a concise commit message stating what changed and why. Do not add credentials or generated noise.
+- Never force-push, rebase shared history, or run destructive git commands without explicit confirmation.
+
 # Context discipline
 - read_file returns line numbers and accepts offset/limit. For large files, grep or glob to the relevant region first, then read only that range with offset/limit. Do not read a whole large file when you need a few functions \u2014 it wastes the context window.
 - Reference code by the line numbers read_file returns.
@@ -2298,7 +2318,7 @@ var InputBar = memo(function InputBar2({ input, caret, disabled, processingLabel
   const [frame, setFrame] = useState(0);
   useEffect(() => {
     if (!disabled) return;
-    const t = setInterval(() => setFrame((f) => (f + 1) % SPIN.length), 150);
+    const t = setInterval(() => setFrame((f) => (f + 1) % SPIN.length), 200);
     return () => clearInterval(t);
   }, [disabled]);
   return /* @__PURE__ */ jsx2(
@@ -3347,14 +3367,26 @@ function clipTail(rendered, max) {
   if (lines.length <= max) return { text: rendered, clipped: 0 };
   return { text: lines.slice(-max).join("\n"), clipped: lines.length - max };
 }
+var ANSI_RE = /\x1b\[[0-9;]*m/g;
+function stripAnsi(s) {
+  return s.replace(ANSI_RE, "");
+}
+function visualHeight(text, width) {
+  const w = Math.max(1, width);
+  let rows = 0;
+  for (const line of text.split("\n")) {
+    rows += Math.max(1, Math.ceil(stripAnsi(line).length / w));
+  }
+  return rows;
+}
 function clipTailVisual(content, maxRows, width) {
   const w = Math.max(1, width);
   const lines = content.split("\n");
-  const visualRows = (line) => Math.max(1, Math.ceil(line.length / w));
+  const visualRows2 = (line) => Math.max(1, Math.ceil(stripAnsi(line).length / w));
   let rows = 0;
   let start = lines.length;
   for (let i = lines.length - 1; i >= 0; i--) {
-    const h = visualRows(lines[i]);
+    const h = visualRows2(lines[i]);
     if (rows + h > maxRows && start < lines.length) break;
     rows += h;
     start = i;
@@ -3367,9 +3399,20 @@ function liveFrameRows() {
   return Math.max(6, rows - 8);
 }
 var COLLAPSED_LINES = 3;
+function visualRows(text, width, cap) {
+  const w = Math.max(1, width);
+  let rows = 0;
+  const lines = text.split("\n");
+  for (const line of lines) {
+    rows += Math.max(1, Math.ceil(line.length / w));
+    if (rows >= cap) return cap;
+  }
+  return rows;
+}
 function estimateToolRows(use, result) {
   const input = use.input ?? {};
   const noErr = !result?.is_error;
+  const w = contentWidth();
   if (use.name === "write_file" && noErr) {
     const total = countLines(String(input.content ?? ""));
     const shown = Math.min(total, COLLAPSED_LINES);
@@ -3385,10 +3428,10 @@ function estimateToolRows(use, result) {
     const lines = (result.content ?? "").split("\n");
     const multi = (use.name === "run_bash" || use.name === "grep" || use.name === "glob" || result.is_error) && lines.length > 1;
     if (multi) {
-      const shown = Math.min(lines.length, COLLAPSED_LINES);
-      rows += 1 + shown + (lines.length > shown ? 1 : 0);
+      const shownLines = lines.slice(0, COLLAPSED_LINES).join("\n");
+      rows += 1 + visualRows(shownLines, w, COLLAPSED_LINES * 4) + (lines.length > COLLAPSED_LINES ? 1 : 0);
     } else {
-      rows += 1;
+      rows += visualRows(lines[0] ?? "", w, 4);
     }
   }
   return rows;
@@ -3422,7 +3465,7 @@ function ThinkingBlock({ content }) {
   const [frame, setFrame] = useState2(0);
   const visible = useThinkingVisible();
   useEffect2(() => {
-    const t = setInterval(() => setFrame((f) => (f + 1) % FRAMES.length), 80);
+    const t = setInterval(() => setFrame((f) => (f + 1) % FRAMES.length), 100);
     return () => clearInterval(t);
   }, []);
   const label = "thinking";
@@ -3801,7 +3844,8 @@ function ChatView({
   permissionCursor = 0,
   activeToolUses,
   activeToolResults,
-  header
+  header,
+  logEpoch = 0
 }) {
   const empty = messages.length === 0 && !streaming && !thinking && !pendingPermission && !error;
   const log = [];
@@ -3816,8 +3860,12 @@ function ChatView({
   let streamNode = null;
   let streamRows = 0;
   if (streaming && streamingContent) {
-    const { text, clipped } = clipTail(renderMarkdownStreaming(streamingContent), liveBudget);
-    streamRows = text.split("\n").length + (clipped > 0 ? 1 : 0);
+    const raw = clipTail(streamingContent, liveBudget);
+    const width = contentWidth();
+    const rendered = clipTailVisual(renderMarkdownStreaming(raw.text), liveBudget, width);
+    const text = rendered.text;
+    const clipped = raw.clipped + rendered.clipped;
+    streamRows = visualHeight(text, width) + (clipped > 0 ? 1 : 0);
     streamNode = /* @__PURE__ */ jsxs12(Box12, { flexDirection: "column", marginBottom: 1, children: [
       clipped > 0 && /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: `\u2191 ${clipped} more line${clipped === 1 ? "" : "s"} above \u2014 streaming\u2026` }),
       /* @__PURE__ */ jsxs12(Box12, { flexDirection: "row", children: [
@@ -3847,7 +3895,7 @@ function ChatView({
     ] });
   }
   return /* @__PURE__ */ jsxs12(Fragment2, { children: [
-    /* @__PURE__ */ jsx12(Static, { items: log, children: (item) => item.key === "header" ? /* @__PURE__ */ jsx12(Box12, { children: item.node }, item.key) : /* @__PURE__ */ jsx12(Box12, { marginLeft: 1, children: item.node }, item.key) }),
+    /* @__PURE__ */ jsx12(Static, { items: log, children: (item) => item.key === "header" ? /* @__PURE__ */ jsx12(Box12, { children: item.node }, item.key) : /* @__PURE__ */ jsx12(Box12, { marginLeft: 1, children: item.node }, item.key) }, logEpoch),
     /* @__PURE__ */ jsxs12(Box12, { flexDirection: "column", marginLeft: 1, marginBottom: 1, children: [
       empty && /* @__PURE__ */ jsxs12(Box12, { flexDirection: "column", marginBottom: 1, children: [
         /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: EMPTY_STATE_TITLE }),
@@ -4015,8 +4063,8 @@ function useAgentRunner(model, activeCtx) {
           case "turn-end": {
             flushStream(true);
             flushThink(true);
-            setStreaming(false);
             if (ev.stop_reason === "tool_use") {
+              setStreaming(false);
               flushTurn(null);
               setThinking(true);
               thinkingAcc = "";
@@ -4288,6 +4336,7 @@ function useKeyboard(opts) {
     sessions,
     setSessions,
     setNotice,
+    setLogEpoch,
     switchProvider
   } = opts;
   const {
@@ -4321,6 +4370,7 @@ function useKeyboard(opts) {
     setError(null);
     setNotice(null);
     clearPasteStore();
+    setLogEpoch((n) => n + 1);
   }
   const effort = cfg.effort ?? "medium";
   useInput((char, key) => {
@@ -4779,6 +4829,7 @@ function App() {
   sessionIdRef.current = sessionId;
   const [sessions, setSessions] = useState5([]);
   const [notice, setNotice] = useState5(null);
+  const [logEpoch, setLogEpoch] = useState5(0);
   const [input, setInput] = useState5("");
   const [caret, setCaret] = useState5(0);
   const [paletteCursor, setPaletteCursor] = useState5(0);
@@ -4899,6 +4950,7 @@ function App() {
     sessions,
     setSessions,
     setNotice,
+    setLogEpoch,
     switchProvider
   });
   const effort = cfg.effort ?? "medium";
@@ -4910,7 +4962,7 @@ function App() {
     return Math.round(used / activeCtx * 100);
   })();
   return /* @__PURE__ */ jsxs13(Box13, { flexDirection: "column", paddingX: 1, children: [
-    state !== "ready" && /* @__PURE__ */ jsx13(WelcomeBlock, { model: cfg.model, activeCtx, effort, cwd, error: agent.error, updateAvailable, updateStatus }),
+    state !== "ready" && state !== "sessions" && state !== "models" && /* @__PURE__ */ jsx13(WelcomeBlock, { model: cfg.model, activeCtx, effort, cwd, error: agent.error, updateAvailable, updateStatus }),
     state === "loading" && !agent.error && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: `connecting to ${provName}\u2026` }) }),
     agent.error && state !== "ready" && /* @__PURE__ */ jsx13(
       ChatView,
@@ -4922,7 +4974,7 @@ function App() {
         error: agent.error
       }
     ),
-    (state === "select-model" || state === "models") && /* @__PURE__ */ jsx13(
+    state === "select-model" && /* @__PURE__ */ jsx13(
       ModelsView,
       {
         models: filteredModels,
@@ -4933,7 +4985,7 @@ function App() {
         providerType: provEntry.type,
         effort,
         query: pickerQuery,
-        requireSelection: state === "select-model"
+        requireSelection: true
       }
     ),
     state === "providers" && /* @__PURE__ */ jsx13(
@@ -4945,8 +4997,7 @@ function App() {
         query: pickerQuery
       }
     ),
-    state === "sessions" && /* @__PURE__ */ jsx13(SessionsView, { sessions, cursor }),
-    state === "ready" && /* @__PURE__ */ jsxs13(Fragment3, { children: [
+    (state === "ready" || state === "sessions" || state === "models") && /* @__PURE__ */ jsxs13(Fragment3, { children: [
       notice && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { color: "green", children: `\u2713 ${notice}` }) }),
       /* @__PURE__ */ jsx13(
         ChatView,
@@ -4961,18 +5012,33 @@ function App() {
           permissionCursor: agent.permissionCursor,
           activeToolUses: agent.activeToolUses,
           activeToolResults: agent.activeToolResults,
-          header: /* @__PURE__ */ jsx13(WelcomeBlock, { model: cfg.model, activeCtx, effort, cwd })
+          header: /* @__PURE__ */ jsx13(WelcomeBlock, { model: cfg.model, activeCtx, effort, cwd }),
+          logEpoch
         }
       ),
-      input.startsWith("/") && /* @__PURE__ */ jsx13(CommandPalette, { filter: input, cursor: paletteCursor }),
-      contextWarning !== null && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { color: "yellow", children: `\u26A0 context ${contextWarning}% full \u2014 run /clear and start fresh` }) }),
-      !input.startsWith("/") && (() => {
+      state === "ready" && input.startsWith("/") && /* @__PURE__ */ jsx13(CommandPalette, { filter: input, cursor: paletteCursor }),
+      state === "ready" && contextWarning !== null && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { color: "yellow", children: `\u26A0 context ${contextWarning}% full \u2014 run /clear and start fresh` }) }),
+      state === "ready" && !input.startsWith("/") && (() => {
         const m = parseMention(input);
         if (!m) return null;
         return /* @__PURE__ */ jsx13(FilePicker, { matches: searchFiles(process.cwd(), m.query), cursor: filePickerCursor });
       })(),
-      /* @__PURE__ */ jsx13(InputBar, { input, caret, disabled: agent.busy, processingLabel: agent.processingLabel }),
-      !agent.busy && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: providerDown ? "provider unavailable \u2014 /provider to switch \xB7 /models to pick a model" : "type / to see commands" }) }),
+      state === "ready" && /* @__PURE__ */ jsx13(InputBar, { input, caret, disabled: agent.busy, processingLabel: agent.processingLabel }),
+      state === "sessions" && /* @__PURE__ */ jsx13(SessionsView, { sessions, cursor }),
+      state === "models" && /* @__PURE__ */ jsx13(
+        ModelsView,
+        {
+          models: filteredModels,
+          cursor,
+          model: cfg.model,
+          host: provEntry.baseUrl,
+          provider: provName,
+          providerType: provEntry.type,
+          effort,
+          query: pickerQuery
+        }
+      ),
+      state === "ready" && !agent.busy && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: providerDown ? "provider unavailable \u2014 /provider to switch \xB7 /models to pick a model" : "type / to see commands" }) }),
       updateAvailable && /* @__PURE__ */ jsx13(Box13, { marginLeft: 2, marginBottom: 1, children: /* @__PURE__ */ jsx13(Text13, { color: updateStatus === "failed" ? "red" : updateStatus === "installed" ? "green" : "yellow", children: updateBannerText(updateAvailable, updateStatus) }) })
     ] })
   ] });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "miii-agent",
-  "version": "0.1.30",
-  "description": "Cursor / Claude Code, but local. An offline AI pair-programmer in your terminal, powered by Ollama. Private by default, free forever.",
+  "version": "0.1.31",
+  "description": "Local AI coding agent for your terminal — an open-source, offline alternative to Claude Code, Cursor, and GitHub Copilot, powered by Ollama. Private by default, free forever.",
   "type": "module",
   "bin": {
     "miii": "dist/cli.js"
@@ -52,7 +52,14 @@
     "pair-programming",
     "code-generation",
     "llama-cpp",
-    "lm-studio"
+    "lm-studio",
+    "copilot",
+    "copilot-alternative",
+    "cursor-alternative",
+    "claude-code",
+    "claude-code-alternative",
+    "developer-tools",
+    "qwen"
   ],
   "license": "MIT",
   "dependencies": {