minu 0.1.0__py3-none-any.whl

minu/__init__.py

@@ -0,0 +1,5 @@
+"""minu: a tiny agent harness for local models (llama.cpp / MLX / Ollama)."""
+from importlib.metadata import PackageNotFoundError, version
+
+try: __version__ = version("minu")
+except PackageNotFoundError: __version__ = "0.0.0"

minu/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

minu/agent.py

@@ -0,0 +1,119 @@
+"""The agent loop: stream a reply, run its command, feed the output back."""
+import json, re, time
+
+from textual import work
+from textual.widgets import Markdown
+
+from .config import BLOCK, STEPS
+from .images import mentioned_images
+from .tools import fetch, search, sh, split_think, to_cmd
+
+
+class AgentMixin:
+    def approve(s, cmd):
+        if s.auto: s.ui(s.note, f"$ {cmd}", "cmd"); return True
+        s.ui(s.note, f"$ {cmd}", "cmd")
+        return s.ask("run it?")
+
+    def exec_cmd(s, cmd):
+        if not s.approve(cmd): return "[user declined to run this]"
+        s.set_state("running…")
+        out = sh(cmd); s.state = ""
+        lines = out.splitlines()
+        s.ui(s.note, "\n".join(lines[:15]) + (f"\n… ({len(lines) - 15} more lines)" if len(lines) > 15 else ""), "out")
+        return out
+
+    def web(s, kind, arg):  # /search and /fetch: look it up, show it, hand it to the model
+        s.set_state(f"{'searching' if kind == 'search' else 'fetching'}…")
+        try: res = search(arg) if kind == "search" else fetch(arg)
+        except Exception as e: res = f"{kind} failed: {e}"
+        lines = res.splitlines()
+        s.ui(s.note, "\n".join(lines[:20]) + (f"\n… ({len(lines) - 20} more lines)" if len(lines) > 20 else ""), "out")
+        if not s.srv.url: return s.say("▸ no model loaded, so just showing results (ctrl+o to pick one)")
+        ask = (f'Web search results for "{arg}":\n\n{res}\n\nAnswer "{arg}" now from these results, citing URLs. Do not run any commands.' if kind == "search"
+               else f"Contents of {arg}:\n\n{res}\n\nSummarize this page.")
+        s.push({"role": "user", "content": ask}); return True
+
+    @work(thread=True, exclusive=True, group="turn")
+    def turn(s, pre=None):
+        s.busy = True; s.stop_ev.clear()
+        try:
+            if not pre or s.web(*pre):  # web() returns None when there's no model to answer
+                for _ in range(STEPS):
+                    if s.step(): break
+        except Exception as e:
+            msg = str(e)
+            if re.search(r"image|mmproj|multimodal|vision", msg, re.I) and any(isinstance(m["content"], list) for m in s.msgs):
+                for m in s.msgs:  # drop images so the chat can continue
+                    if isinstance(m["content"], list):
+                        m["content"] = m["content"][0]["text"] + "\n[image removed: model can't see images]"
+                msg = "this model can't read images. Pick one marked [vision] (ctrl+o), or e.g. gemma3:4b on Ollama"
+            s.say(f"▸ error: {msg}")
+        s.busy = False; s.set_state("")
+
+    def step(s):
+        md = think_box = think_w = None
+        raw, reasoning, calls, block = "", "", {}, None
+        last, first, think_t, n, final_tps = 0.0, None, None, 0, None
+        s.set_state("waiting…")
+        for ch in s.srv.stream(s.msgs, s.native, s.stop_ev):
+            if u := ch.get("usage"):
+                s.used = u.get("total_tokens") or u.get("prompt_tokens", 0) + u.get("completion_tokens", 0)
+                if u.get("completion_tokens") and first: final_tps = u["completion_tokens"] / max(time.time() - first, 1e-3)
+            if (tm := ch.get("timings")) and tm.get("predicted_per_second"): final_tps = tm["predicted_per_second"]  # llama.cpp
+            if not ch.get("choices"): continue
+            d = ch["choices"][0].get("delta") or {}
+            piece, rpiece = d.get("content") or "", d.get("reasoning_content") or d.get("reasoning") or ""
+            raw += piece; reasoning += rpiece
+            for tc in d.get("tool_calls") or []:
+                c = calls.setdefault(tc.get("index", 0), {"id": "", "name": "", "args": ""})
+                f = tc.get("function") or {}
+                c["id"] = tc.get("id") or c["id"]; c["name"] += f.get("name") or ""; c["args"] += f.get("arguments") or ""
+            if piece or rpiece or d.get("tool_calls"):
+                n += 1; first = first or time.time()
+            think, text = s.split(reasoning, raw)
+            if not s.native and (block := BLOCK.search(text)):
+                break
+            if time.time() - last > 0.08:
+                last = time.time()
+                if n > 1: s.tps = (n - 1) / max(last - first, 1e-3)  # ~1 token per streamed chunk
+                if think:
+                    think_t = think_t or time.time()
+                    if not think_box: think_box, think_w = s.ui(s.add_think)
+                    s.ui(s.render, think_w, think)
+                if text:
+                    if not md: md = s.ui(s.add, Markdown(""))
+                    if think_box and not think_box.collapsed: s.ui(s.end_think, think_box, time.time() - think_t)
+                    s.ui(s.render, md, text)
+                s.set_state("writing…" if text else "thinking…" if think else "waiting…")
+        think, text = s.split(reasoning, raw)
+        if block: text = text[:block.end()]
+        if final_tps: s.tps = final_tps
+        if think:
+            if not think_box: think_box, think_w = s.ui(s.add_think)
+            s.ui(s.render, think_w, think); s.ui(s.end_think, think_box, time.time() - (think_t or first or time.time()))
+        if text or not calls:
+            if not md: md = s.ui(s.add, Markdown(""))
+            s.ui(s.render, md, text or "_(empty)_")
+        if s.stop_ev.is_set():
+            s.push({"role": "assistant", "content": text}); s.say("▸ stopped"); return True
+        if calls:
+            s.push({"role": "assistant", "content": text, "tool_calls": [
+                {"id": c["id"] or f"call{i}", "type": "function", "function": {"name": c["name"], "arguments": c["args"]}}
+                for i, c in calls.items()]})
+            for i, c in calls.items():
+                try: cmd = json.loads(c["args"] or "{}").get("command", "")
+                except json.JSONDecodeError: cmd = c["args"]
+                s.push({"role": "tool", "tool_call_id": c["id"] or f"call{i}", "content": s.exec_cmd(cmd)})
+            return s.stop_ev.is_set()
+        s.push({"role": "assistant", "content": text})
+        if block:
+            s.push({"role": "user", "content": "Output:\n" + s.exec_cmd(to_cmd(block))})
+            return s.stop_ev.is_set()
+        for p in mentioned_images(text): s.ui(s.show_image, p)
+        return True
+
+    @staticmethod
+    def split(reasoning, raw):  # reasoning field (llama.cpp/Ollama) + inline <think> tags -> (thinking, answer)
+        think, text = split_think(raw)
+        return "\n".join(x for x in (reasoning.strip(), think) if x), text

minu/app.py

@@ -0,0 +1,207 @@
+"""The minu TUI: layout, status bar, input handling."""
+import os, subprocess, threading, time, re
+
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.widgets import Collapsible, OptionList, Static
+
+from .agent import AgentMixin
+from .config import BANNER, COMMANDS, SYSTEM, SYSTEM_NATIVE
+from .images import encode_image, find_images, image_widget
+from .model_flows import ModelFlowsMixin
+from .server import Server, kill_children
+from .sessions import SessionsMixin
+from .tools import sh_env
+from .widgets import Prompt
+
+
+class Minu(ModelFlowsMixin, SessionsMixin, AgentMixin, App):
+    CSS = """
+    #banner { height: 1fr; width: 100%; content-align: center middle; text-align: center; color: $accent; }
+    #log { height: 1fr; padding: 0 1; scrollbar-size-vertical: 1; display: none; }
+    .user { color: $accent; margin-top: 1; text-style: bold; }
+    .cmd { color: $warning; }
+    .out { color: $text-muted; }
+    .sys { color: $text-muted; text-style: italic; }
+    .img { width: auto; height: 14; margin: 0 2; }
+    Markdown { margin: 0; padding: 0; }
+    .think-box { background: transparent; border: none; padding: 0; margin: 1 0 0 0; }
+    .think-box > Contents { padding: 0 0 0 2; }
+    .think-box CollapsibleTitle { color: $text-muted; padding: 0; }
+    .think { color: $text-muted; text-style: italic; }
+    #prompt { height: auto; min-height: 5; max-height: 12; border: round $accent; padding: 0 1; background: $surface; }
+    #prompt:focus { border: round $accent-lighten-2; }
+    #prompt > .text-area--cursor-line { background: transparent; }
+    #status { height: 1; padding: 0 1; color: $text-muted; background: $panel; }
+    #slash { height: auto; max-height: 11; border: round $accent; background: $surface; display: none; padding: 0 1; }
+    """
+    BINDINGS = [("ctrl+o", "pick", "model"), ("ctrl+y", "auto", "auto-run"),
+                ("escape", "halt", "stop"), ("ctrl+l", "clear", "clear"), ("ctrl+n", "clear", "new session"),
+                Binding("ctrl+c", "quit", "quit", show=False, priority=True)]  # beats TextArea's ctrl+c copy
+
+    def __init__(s, start=None, auto=False, native=False, resume=None):
+        super().__init__()
+        s.resume_path = resume
+        s.srv, s.start_with, s.auto, s.native = Server(), start, auto, native
+        s.msgs = [{"role": "system", "content": SYSTEM_NATIVE if native else SYSTEM}]
+        s.used, s.busy, s.state, s.ollama_proc, s.session, s.tps = 0, False, "", None, None, None
+        s.stop_ev, s.ok_ev, s.ok, s.pending = threading.Event(), threading.Event(), False, False
+
+    def compose(s) -> ComposeResult:
+        yield Static(BANNER, id="banner")
+        yield VerticalScroll(id="log")
+        yield OptionList(id="slash")
+        p = Prompt(id="prompt", placeholder="ask minu…  (type / for commands)", soft_wrap=True)
+        p.border_title, p.border_subtitle = "message", "enter send · ctrl+j newline"
+        yield p
+        yield Static(id="status")
+
+    def on_mount(s):
+        s.title = "minu"; s.status(); s.query_one("#prompt").focus()
+        if s.resume_path: s.resume(s.resume_path)
+        if s.start_with: s.load(*s.start_with)
+        else: s.action_pick()
+
+    def on_click(s, e):  # click anywhere on the chat -> type in the input box
+        if len(s.screen_stack) == 1: s.query_one("#prompt").focus()
+
+    def on_unmount(s):
+        s.srv.stop()
+        if s.ollama_proc: s.ollama_proc.terminate()
+
+    # ---- ui helpers (main thread)
+    def status(s):
+        ctx = f"{s.used}/{s.srv.ctx}" if s.srv.ctx else str(s.used)
+        st = f" · {s.state}" if s.state else ""
+        tps = f" · {s.tps:.1f} tok/s" if s.tps else ""
+        s.query_one("#status", Static).update(
+            f"{s.srv.name} · {ctx} tok{tps} · auto {'on' if s.auto else 'off'}{st}   ^o model ^y auto esc stop ^c quit")
+
+    def add(s, w):
+        s.query_one("#banner").display = False
+        log = s.query_one("#log"); log.display = True
+        log.mount(w); s.call_after_refresh(log.scroll_end, animate=False); return w
+
+    async def render(s, w, text):  # update a streaming widget; follow the bottom unless the user scrolled up
+        log = s.query_one("#log"); pinned = log.max_scroll_y - log.scroll_y <= 3
+        if (r := w.update(text)) is not None: await r
+        if pinned: s.call_after_refresh(log.scroll_end, animate=False)
+
+    def add_think(s):  # live reasoning, shown in the chat and folded away once the answer starts
+        body = Static("", classes="think", markup=False)
+        box = s.add(Collapsible(body, title="thinking…", collapsed=False, classes="think-box"))
+        return box, body
+
+    def end_think(s, box, secs): box.title, box.collapsed = f"thought for {secs:.1f}s", True
+
+    def note(s, text, cls="sys"): return s.add(Static(text, classes=cls, markup=False))
+
+    def show_image(s, p):
+        try: s.add(image_widget(p))
+        except Exception as e: s.note(f"▸ can't show {p.name}: {e}")
+
+    def ui(s, fn, *a):  # call from worker thread
+        return s.call_from_thread(fn, *a)
+
+    def say(s, text): s.ui(s.note, text)
+    def set_state(s, text): s.state = text; s.ui(s.status)
+
+    # ---- actions
+    def action_quit(s):  # unblock worker threads first, or the app hangs on exit waiting for them
+        s.stop_ev.set(); s.ok, s.pending = False, False; s.ok_ev.set(); s.srv.abort()
+        t = threading.Timer(4, lambda: (kill_children(), os._exit(0))); t.daemon = True  # last resort if a thread is still stuck
+        t.start()
+        s.exit()
+
+    def action_auto(s): s.auto = not s.auto; s.status()
+    def action_halt(s):
+        s.stop_ev.set()
+        if s.pending: s.ok = False; s.pending = False; s.ok_ev.set()
+
+    def action_clear(s):
+        if s.busy: return s.notify("busy, press esc first")
+        s.msgs = s.msgs[:1]; s.used = 0; s.session = None; s.tps = None
+        log = s.query_one("#log"); log.remove_children(); log.display = False
+        s.query_one("#banner").display = True; s.status()
+
+    # ---- worker-thread helpers
+    def ask(s, q):
+        s.say(q)
+        def go():
+            s.pending = True; inp = s.query_one("#prompt"); inp.placeholder = "[Y/n]  enter = yes"; inp.focus()
+        s.ok_ev.clear(); s.ui(go); s.ok_ev.wait()
+        return s.ok
+
+    def proc(s, cmd, label):  # run a long command, live last line in the status bar
+        p = subprocess.Popen(cmd, shell=isinstance(cmd, str), stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                             stdin=subprocess.DEVNULL, env={**sh_env(), "PYTHONUNBUFFERED": "1"})
+        tail, buf, last = [], b"", 0.0
+        while chunk := p.stdout.read1(4096):
+            buf += chunk
+            *lines, buf = re.split(rb"[\r\n]", buf)
+            tail = (tail + [x.decode(errors="replace").strip() for x in lines if x.strip()])[-20:]
+            if time.time() - last > 0.2:
+                cur = buf.decode(errors="replace").strip() or (tail[-1] if tail else "")
+                s.set_state(f"{label}: {cur[-70:]}"); last = time.time()
+            if s.stop_ev.is_set(): p.terminate()
+        if buf.strip(): tail.append(buf.decode(errors="replace").strip())
+        s.set_state("")
+        return p.wait(), tail
+
+    # ---- the / menu
+    def on_text_area_changed(s, e):
+        if e.text_area.id != "prompt": return
+        t, menu = e.text_area.text, s.query_one("#slash", OptionList)
+        s.menu_items = [c for c in COMMANDS if c[0].startswith(t)] if t.startswith("/") and not re.search(r"\s", t) else []
+        if s.menu_items:
+            menu.set_options([f"{c:<9}{a:<10}{d}" for c, a, d in s.menu_items]); menu.highlighted = 0
+        menu.display = bool(s.menu_items)
+
+    def slash_move(s, d):
+        menu = s.query_one("#slash", OptionList)
+        menu.highlighted = ((menu.highlighted or 0) + d) % len(s.menu_items)
+
+    def slash_choose(s, complete_only=False, index=None):
+        menu, inp = s.query_one("#slash", OptionList), s.query_one("#prompt")
+        cmd, arg, _ = s.menu_items[menu.highlighted if index is None else index]
+        menu.display = False
+        if arg or complete_only:  # needs an argument: fill it in and keep typing
+            inp.text = cmd + " "; inp.move_cursor(inp.document.end); inp.focus()
+        else:
+            inp.clear(); s.on_prompt_submitted(Prompt.Submitted(cmd))
+
+    def on_option_list_option_selected(s, e):
+        if e.option_list.id == "slash": s.slash_choose(index=e.option_index)
+
+    def on_prompt_submitted(s, e):
+        text = e.value.strip(); inp = s.query_one("#prompt")
+        if s.pending:
+            s.ok = text.lower() in ("", "y", "yes"); s.pending = False
+            inp.placeholder = "ask minu…"; s.ok_ev.set(); return
+        if not text: return
+        if text == "/model": return s.action_pick()
+        if text == "/delete": return s.action_delete()
+        if text in ("/new", "/clear"): return s.action_clear()
+        if text == "/auto": return s.action_auto()
+        if text == "/resume": return s.pick_session()
+        if text in ("/exit", "/quit", "/q"): return s.action_quit()
+        if text.startswith("/view"):
+            imgs = find_images(text[5:])
+            return [s.show_image(p) for p in imgs] if imgs else s.notify("no image file at that path")
+        if s.busy: return s.notify("busy, esc to stop")
+        if m := re.match(r"/(search|fetch)\s+(.+)", text, re.S):
+            s.add(Static(f"> {text}", classes="user", markup=False)); return s.turn((m[1], m[2].strip()))
+        if re.fullmatch(r"/[a-z]+", text.split()[0]) and not Path(text.split()[0]).exists():  # not a pasted path
+            return s.notify(f"unknown command {text.split()[0]} (type / to see them)")
+        if not s.srv.url: return s.notify("no model loaded (ctrl+o)")
+        imgs = find_images(text)
+        s.add(Static(f"> {text}", classes="user", markup=False))
+        for p in imgs: s.show_image(p)
+        content = text
+        if imgs:
+            try: content = [{"type": "text", "text": text}] + [{"type": "image_url", "image_url": {"url": encode_image(p)}} for p in imgs]
+            except Exception as err: s.note(f"▸ couldn't read image: {err}")
+        s.push({"role": "user", "content": content}); s.turn()

minu/cli.py

@@ -0,0 +1,49 @@
+"""Command line: `minu [--hf|--gguf|--mlx|--ollama|--url ...]`, plus `minu search|fetch` for the agent."""
+import argparse, os, signal, sys
+
+from . import __version__, images
+from .sessions import session_files
+from .tools import fetch, search, shims
+
+
+def main():
+    if len(sys.argv) > 2 and sys.argv[1] in ("search", "fetch"):
+        try: print((search if sys.argv[1] == "search" else fetch)(" ".join(sys.argv[2:])))
+        except Exception as e: print(f"error: {e}"); sys.exit(1)
+        return
+    ap = argparse.ArgumentParser(prog="minu", description="tiny agent harness for local models")
+    ap.add_argument("-V", "--version", action="version", version=f"minu {__version__}")
+    g = ap.add_mutually_exclusive_group()
+    g.add_argument("--hf", help="HF repo; GGUF -> llama.cpp, mlx -> MLX")
+    g.add_argument("--gguf", help="HF GGUF repo or .gguf path (llama.cpp)")
+    g.add_argument("--mlx", help="HF MLX repo (mlx_lm)")
+    g.add_argument("--ollama", help="Ollama model name")
+    g.add_argument("--url", help="existing OpenAI-compatible server")
+    ap.add_argument("-y", "--auto", action="store_true", help="run commands without asking")
+    ap.add_argument("--native", action="store_true", help="use native tool calls instead of ```sh blocks")
+    ap.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue the latest session for this folder")
+    ap.add_argument("-r", "--resume", metavar="FILE", help="resume a session .jsonl")
+    a = ap.parse_args()
+    start = None
+    if a.hf:
+        low = a.hf.lower()
+        if "gguf" in low: start = ("gguf", a.hf)
+        elif "mlx" in low: start = ("mlx", a.hf)
+        else: ap.error("can't tell if repo is GGUF or MLX; use --gguf or --mlx")
+    for k in ("gguf", "mlx", "ollama", "url"):
+        if getattr(a, k): start = (k, getattr(a, k))
+    shims()
+    import logging; logging.getLogger("textual_image").setLevel(logging.CRITICAL)
+    try: import textual_image.widget  # noqa: F401  (must detect terminal graphics before the app starts)
+    except Exception: images.IMAGES = False  # odd terminal: show image names instead of pixels
+    resume = a.resume
+    if a.cont:
+        latest = session_files()
+        resume = latest[0] if latest else None
+        if not resume: print("no saved sessions for this folder yet")
+    from .app import Minu  # imported late so `minu search|fetch` stay fast
+    from .server import kill_children
+    app = Minu(start, a.auto, a.native, resume)
+    signal.signal(signal.SIGTERM, lambda *_: app.action_quit())
+    signal.signal(signal.SIGHUP, lambda *_: (kill_children(), os._exit(1)))  # terminal closed
+    app.run()

minu/config.py

@@ -0,0 +1,49 @@
+"""Paths, limits, prompts and the banner."""
+import os, platform, re
+from pathlib import Path
+
+HOME = Path.home()
+HF = Path(os.environ.get("HF_HUB_CACHE") or Path(os.environ.get("HF_HOME", HOME / ".cache/huggingface")) / "hub")
+OLLAMA = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+OLLAMA = OLLAMA if OLLAMA.startswith("http") else "http://" + OLLAMA
+CTX = int(os.environ.get("MINU_CTX", 16384))
+DIR = HOME / ".cache/minu"
+MINU_HOME = Path(os.environ.get("MINU_HOME") or HOME / ".minu").expanduser()  # sessions live here
+OUT_MAX, STEPS = 4000, 25
+MLX_OK = platform.system() == "Darwin" and platform.machine() == "arm64"
+IMG_EXT = (".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp")
+IMG_RE = re.compile(r"[\w~./-]+\.(?:png|jpe?g|gif|webp|bmp)\b", re.I)
+UA = {"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"}
+OS = {"Darwin": "macOS"}.get(platform.system(), platform.system())
+ENV = f"on {OS}, cwd {os.getcwd()}"
+SYSTEM = (f"You are minu, a terse coding agent {ENV}. You can run shell commands and use the web. "
+          "To run one, reply with only a ```sh block, then stop; you get its output. Example:\n"
+          "```sh\nminu-search \"turing machine\"\n```\n"
+          "minu-fetch URL reads a page. Edit files with heredoc or python3. Use ```text for examples.")
+SYSTEM_NATIVE = (f"You are minu, a terse coding agent {ENV}. Use the sh tool to run commands and use the web: "
+                 "minu-search \"query\", minu-fetch URL. Edit files with heredoc or python3.")
+COMMANDS = [  # shown in the / menu: (command, argument, description)
+    ("/new", "", "start a new session"),
+    ("/model", "", "pick or download a model"),
+    ("/delete", "", "delete a downloaded model to free disk space"),
+    ("/resume", "", "open a saved session"),
+    ("/search", "<query>", "search the web, the model answers from the results"),
+    ("/fetch", "<url>", "read a web page, the model summarizes it"),
+    ("/view", "<image>", "show an image"),
+    ("/auto", "", "toggle running commands without asking"),
+    ("/clear", "", "same as /new"),
+    ("/exit", "", "quit minu"),
+]
+TOOLS = [{"type": "function", "function": {"name": "sh", "description": "Run a shell command",
+          "parameters": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}}}]
+BLOCK = re.compile(r"```(?:sh|bash|shell|zsh)[ \t]*\n(.*?)```|<tool_call>(.*?)</tool_call>", re.S)
+BANNER = """\
+███╗   ███╗ ██╗ ███╗   ██╗ ██╗   ██╗
+████╗ ████║ ██║ ████╗  ██║ ██║   ██║
+██╔████╔██║ ██║ ██╔██╗ ██║ ██║   ██║
+██║╚██╔╝██║ ██║ ██║╚██╗██║ ██║   ██║
+██║ ╚═╝ ██║ ██║ ██║ ╚████║ ╚██████╔╝
+╚═╝     ╚═╝ ╚═╝ ╚═╝  ╚═══╝  ╚═════╝
+
+[dim]tiny harness for local models
+ctrl+o  pick or download a model  ·  drop an image path to attach it[/]"""

minu/images.py

@@ -0,0 +1,35 @@
+"""Attaching images to messages and showing them in the terminal."""
+import base64, io, shlex
+from pathlib import Path
+
+from textual.widgets import Static
+
+from .config import IMG_EXT, IMG_RE
+
+def find_images(text):  # image paths in a message (drag-and-drop pastes a path)
+    try: toks = shlex.split(text)
+    except ValueError: toks = text.split()
+    out = []
+    for t in toks:
+        p = Path(t.strip(",;:")).expanduser()
+        if p.suffix.lower() in IMG_EXT and p.is_file() and p.resolve() not in out: out.append(p.resolve())
+    return out
+
+def mentioned_images(text):
+    out = []
+    for m in IMG_RE.findall(text):
+        p = Path(m).expanduser()
+        if p.is_file() and p.resolve() not in out: out.append(p.resolve())
+    return out
+
+def encode_image(p):
+    from PIL import Image
+    im = Image.open(p); im.thumbnail((1024, 1024)); im = im.convert("RGB")
+    b = io.BytesIO(); im.save(b, "JPEG", quality=85)
+    return "data:image/jpeg;base64," + base64.b64encode(b.getvalue()).decode()
+
+IMAGES = True
+def image_widget(p):
+    if not IMAGES: return Static(f"[image: {p}]", classes="sys", markup=False)
+    from textual_image.widget import Image
+    return Image(str(p), classes="img")

minu/installs.py

@@ -0,0 +1,21 @@
+"""Where tools live, and how to install them when they are missing."""
+import platform, shutil, sys
+
+from .config import HOME, MLX_OK
+
+def which(tool):
+    return shutil.which(tool) or shutil.which(tool, path=f"{HOME}/.local/bin:/opt/homebrew/bin:/usr/local/bin")
+
+def install_cmd(tool):  # -> (command or None, help)
+    brew, uv = which("brew"), which("uv")
+    pip = lambda pkg: f"uv tool install {pkg}" if uv else f"{sys.executable} -m pip install -U {pkg}"
+    if tool == "llama-server":
+        return ("brew install llama.cpp" if brew else None), "https://github.com/ggml-org/llama.cpp/blob/master/docs/install.md"
+    if tool == "ollama":
+        if platform.system() == "Linux": return "curl -fsSL https://ollama.com/install.sh | sh", "https://ollama.com/download"
+        return ("brew install ollama" if brew else None), "https://ollama.com/download"
+    if tool == "hf":
+        return pip("huggingface_hub"), "https://huggingface.co/docs/huggingface_hub/installation"
+    if tool == "mlx_lm.server":
+        return (pip("mlx-lm") if MLX_OK else None), "MLX needs an Apple Silicon Mac"
+    return None, ""

minu/model_flows.py

@@ -0,0 +1,156 @@
+"""Picking, downloading, installing and loading models (mixed into the app)."""
+import asyncio, importlib.util, json, re, subprocess, time, urllib.request
+from pathlib import Path
+
+from textual import work
+
+from .config import MLX_OK, OLLAMA
+from .installs import install_cmd, which
+from .server import spawn
+from .models import delete_model, deletable, discover, gb, hf_files, hf_search, ollama_up
+from .widgets import Ask, Picker
+
+
+class ModelFlowsMixin:
+    @work(exclusive=True, group="pick")
+    async def action_pick(s):
+        if which("ollama") and not await asyncio.to_thread(ollama_up):
+            await asyncio.to_thread(s.start_ollama)
+        items = [("⬇  download from Hugging Face…", ("dl-hf", None)),
+                 ("⬇  pull from Ollama…", ("dl-ollama", None)),
+                 ("✕  delete a model…", ("delete", None))] + await asyncio.to_thread(discover)
+        choice = await s.push_screen_wait(Picker("models", items))
+        if not choice: return
+        kind, ref = choice
+        if kind == "dl-ollama":
+            name = await s.push_screen_wait(Ask("Ollama model to pull (see ollama.com/library)", "e.g. qwen3:4b, gemma3:4b (vision)"))
+            if name: s.pull_ollama(name)
+        elif kind == "dl-hf":
+            await s.hf_flow()
+        elif kind == "delete":
+            await s.delete_flow()
+        else:
+            s.load(kind, ref)
+
+    @work(exclusive=True, group="pick")
+    async def action_delete(s): await s.delete_flow()
+
+    async def delete_flow(s):
+        items = await asyncio.to_thread(deletable)
+        if not items: return s.notify("no downloaded models to delete")
+        total = sum(i[1][3] for i in items)
+        choice = await s.push_screen_wait(Picker(f"delete a model ({gb(total)} on disk)", items))
+        if not choice: return
+        kind, ref, name, size = choice
+        loaded = s.srv.url and s.srv.kind == kind and s.srv.ref == ref
+        if loaded and s.busy: return s.notify("that model is busy, press esc first")
+        warn = "  (it's loaded; it will be stopped)" if loaded else ""
+        if not await s.push_screen_wait(Picker(f"delete {name}?{warn}", [("no, keep it", False), (f"yes, delete it and free {gb(size)}", True)])):
+            return
+        try:
+            if loaded:
+                await asyncio.to_thread(s.srv.stop); s.srv.name = "no model"; s.tps = None
+            gone = await asyncio.to_thread(delete_model, kind, ref)
+            s.note(f"▸ deleted {gone}, freed {gb(size)}")
+        except Exception as e:
+            s.note(f"▸ couldn't delete {name}: {e}")
+        s.status()
+
+    async def hf_flow(s):
+        q = await s.push_screen_wait(Ask("Search Hugging Face, or paste org/repo", "e.g. qwen3 gguf, gemma 3 mlx, ggml-org/SmolVLM-256M-Instruct-GGUF"))
+        if not q: return
+        try:
+            if "/" in q: repo = q.removeprefix("https://huggingface.co/").strip("/")
+            else:
+                s.state = "searching…"; s.status()
+                res = await asyncio.to_thread(hf_search, q); s.state = ""; s.status()
+                if not res: return s.notify(f"no GGUF/MLX models for '{q}'")
+                repo = await s.push_screen_wait(Picker(f"results for '{q}'", res))
+                if not repo: return
+            kind, gg, mm, files = await asyncio.to_thread(hf_files, repo)
+        except Exception as e:
+            s.state = ""; s.status(); return s.note(f"▸ Hugging Face error: {e}")
+        if kind is None: return s.note(f"▸ {repo} has no GGUF or MLX weights; minu can't run it")
+        if kind == "mlx":
+            if not MLX_OK: return s.note("▸ MLX models need an Apple Silicon Mac")
+            return s.download_hf(repo, [], kind)
+        pref = lambda f: (not re.search(r"q4_k_m", f, re.I), gg[f])
+        opts = [(f"{f}  {gg[f] / 1e9:.1f} GB", f) for f in sorted(gg, key=pref)]
+        f = opts[0][1] if len(opts) == 1 else await s.push_screen_wait(Picker(f"{repo}: pick a size (Q4_K_M is a good default)", opts))
+        if not f: return
+        part = re.split(r"-00001-of-", f)[0]
+        want = [g for g in files if g.startswith(part) and g.endswith(".gguf")] if "-00001-of-" in f else [f]
+        if mm:  # vision projector: prefer Q8/f16 over f32
+            want.append(sorted(mm, key=lambda m: ("f32" in m.lower(), mm[m]))[0])
+        s.download_hf(repo, want, kind)
+
+    def need(s, tool):  # path to tool, offering to install it if missing
+        if p := which(tool): return p
+        cmd, hint = install_cmd(tool)
+        if not cmd:
+            s.say(f"▸ {tool} isn't installed and minu can't install it here. See {hint}"); return None
+        if not s.ask(f"{tool} isn't installed. Install it with `{cmd}`?"):
+            s.say(f"▸ skipped. To install later: {cmd}"); return None
+        rc, tail = s.proc(cmd, f"installing {tool}")
+        if rc != 0 or not which(tool):
+            s.say("▸ install failed:\n" + "\n".join(tail[-5:]) + f"\nSee {hint}"); return None
+        s.say(f"▸ installed {tool}"); return which(tool)
+
+    def start_ollama(s, ask=False):
+        if ollama_up(): return True
+        exe = s.need("ollama") if ask else which("ollama")
+        if not exe: return False
+        s.ollama_proc = spawn([exe, "serve"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        for _ in range(60):
+            if ollama_up(): return True
+            time.sleep(0.25)
+        return False
+
+    def _load(s, kind, ref):
+        s.set_state(f"loading {Path(ref).name}…")
+        try:
+            if kind == "gguf" and not s.need("llama-server"): raise RuntimeError("llama-server is required for GGUF models")
+            if kind == "mlx" and not importlib.util.find_spec("mlx_lm") and not s.need("mlx_lm.server"):
+                raise RuntimeError("mlx-lm is required for MLX models")
+            if kind == "ollama" and not s.start_ollama(ask=True): raise RuntimeError("Ollama isn't running")
+            s.set_state(f"loading {Path(ref).name}…")
+            s.srv.start(kind, ref); s.say(f"▸ model: {s.srv.name} ({kind})")
+        except Exception as e:
+            s.srv.name = "no model"; s.say(f"▸ failed: {e}")
+        s.set_state("")
+
+    @work(thread=True, exclusive=True, group="load")
+    def load(s, kind, ref): s._load(kind, ref)
+
+    @work(thread=True, exclusive=True, group="load")
+    def download_hf(s, repo, files, kind):
+        s.stop_ev.clear()
+        if not (exe := s.need("hf")): return
+        s.say(f"▸ downloading {repo} {' '.join(files)}  (esc to cancel)")
+        rc, tail = s.proc([exe, "download", repo, *files], f"↓ {repo.split('/')[-1]}")
+        if rc != 0:
+            why = "\n".join(tail[-4:])
+            if re.search(r"401|403|gated|restricted", why, re.I): why += "\nThis repo needs a login: run `hf auth login`, then accept its license on huggingface.co"
+            return s.say(f"▸ download failed:\n{why}")
+        if kind == "mlx": return s._load("mlx", repo)
+        for _, (k, ref) in discover():
+            if k == "gguf" and ref.endswith(Path(files[0]).name): return s._load("gguf", ref)
+        s.say("▸ downloaded, but couldn't find the file in the HF cache (ctrl+o to pick it)")
+
+    @work(thread=True, exclusive=True, group="load")
+    def pull_ollama(s, name):
+        s.stop_ev.clear()
+        if not s.start_ollama(ask=True): return s.say("▸ Ollama isn't running")
+        s.say(f"▸ pulling {name} from Ollama  (esc to cancel)")
+        req = urllib.request.Request(f"{OLLAMA}/api/pull", json.dumps({"model": name}).encode(), {"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=3600) as r:
+                for line in r:
+                    if s.stop_ev.is_set(): s.set_state(""); return s.say("▸ pull cancelled")
+                    j = json.loads(line)
+                    if "error" in j: raise RuntimeError(j["error"])
+                    pct = f" {100 * j['completed'] // j['total']}%" if j.get("total") and j.get("completed") else ""
+                    s.set_state(f"↓ {name}: {j.get('status', '')}{pct}")
+        except Exception as e:
+            s.set_state(""); return s.say(f"▸ pull failed: {e}")
+        s._load("ollama", name)

minu/models.py

@@ -0,0 +1,104 @@
+"""Finding local models (HF cache, Ollama) and searching Hugging Face."""
+import json, re, shutil, urllib.parse, urllib.request
+from pathlib import Path
+
+from .config import HF, MLX_OK, OLLAMA
+from .tools import get
+
+def ollama_up():
+    try: get(f"{OLLAMA}/api/tags", timeout=1); return True
+    except Exception: return False
+
+def discover():
+    ms = []  # (label, (kind, ref))
+    for d in sorted(HF.glob("models--*")) if HF.is_dir() else []:
+        repo = d.name[8:].replace("--", "/")
+        ggufs = {p.name: p for p in d.glob("snapshots/*/**/*.gguf")
+                 if "mmproj" not in p.name.lower() and not re.search(r"-0000[2-9]-of-", p.name)}
+        for n, p in sorted(ggufs.items()):
+            eye = " [vision]" if any(p.parent.glob("*mmproj*.gguf")) else ""
+            ms.append((f"gguf    {repo} · {n}{eye}", ("gguf", str(p))))
+        cfg = next(d.glob("snapshots/*/config.json"), None)
+        if not ggufs and cfg and ("mlx" in repo.lower() or "quantization" in cfg.read_text()):
+            ms.append((f"mlx     {repo}", ("mlx", repo)))
+    try:
+        for m in json.loads(get(f"{OLLAMA}/api/tags", timeout=1))["models"]:
+            ms.append((f"ollama  {m['name']}", ("ollama", m["name"])))
+    except Exception:
+        pass
+    return ms
+
+def gb(n): return f"{n / 1e9:.1f} GB" if n >= 1e8 else f"{n / 1e6:.0f} MB"
+
+def _repo_dir(p):  # .../hub/models--org--name/snapshots/<rev>/x.gguf -> .../hub/models--org--name
+    return next(d for d in Path(p).parents if d.name.startswith("models--"))
+
+def _shards(p):  # a .gguf plus its -0000N-of-M siblings
+    p = Path(p)
+    if not (m := re.match(r"(.*)-00001-of-(\d+)\.gguf$", p.name)): return [p]
+    return sorted(p.parent.glob(f"{m[1]}-*-of-{m[2]}.gguf"))
+
+def _du(d): return sum(f.stat().st_size for f in Path(d).rglob("*") if f.is_file() and not f.is_symlink())
+
+def deletable():  # (label, (kind, ref, name, bytes)) for everything minu can delete
+    out = []
+    for label, (kind, ref) in discover():
+        if kind == "gguf":
+            n = sum(f.resolve().stat().st_size for f in _shards(ref) if f.exists())
+            name = f"{_repo_dir(ref).name[8:].replace('--', '/')} · {Path(ref).name}"
+        elif kind == "mlx":
+            n, name = _du(HF / ("models--" + ref.replace("/", "--"))), ref
+        else: continue
+        out.append((f"{gb(n):>8}  {label}", (kind, ref, name, n)))
+    try:
+        for m in json.loads(get(f"{OLLAMA}/api/tags", timeout=1))["models"]:
+            out.append((f"{gb(m.get('size', 0)):>8}  ollama  {m['name']}", ("ollama", m["name"], m["name"], m.get("size", 0))))
+    except Exception: pass
+    return out
+
+def delete_model(kind, ref):  # -> what was removed
+    if kind == "ollama":
+        req = urllib.request.Request(f"{OLLAMA}/api/delete", json.dumps({"model": ref}).encode(),
+                                     {"Content-Type": "application/json"}, method="DELETE")
+        urllib.request.urlopen(req, timeout=30).close(); return f"ollama model {ref}"
+    if kind == "mlx":
+        repo = HF / ("models--" + ref.replace("/", "--"))
+    else:  # one quant of a GGUF repo: drop it, and the whole repo once no model weights are left
+        repo = _repo_dir(ref)
+        rels = [f.relative_to(next(d for d in f.parents if d.parent.name == "snapshots")) for f in _shards(ref)]
+        links = [g for rel in rels for g in repo.glob(f"snapshots/*/{rel}")]  # same file in every revision
+        blobs = {g.resolve() for g in links}
+        for g in links: g.unlink(missing_ok=True)
+        used = {g.resolve() for g in repo.glob("snapshots/*/**/*") if g.is_symlink()}
+        for b in blobs - used:
+            if b.exists() and b.parent.name == "blobs": b.unlink()
+        left = [g for g in repo.glob("snapshots/*/**/*.gguf") if "mmproj" not in g.name.lower()]
+        if left: return Path(ref).name
+    if HF not in repo.parents: raise RuntimeError(f"refusing to delete {repo}: not in the HF cache")
+    shutil.rmtree(repo); shutil.rmtree(HF / ".locks" / repo.name, ignore_errors=True)
+    return repo.name[8:].replace("--", "/")
+
+def hf_api(path):
+    return json.loads(get("https://huggingface.co/api/" + path, timeout=15))
+
+def hf_search(q):
+    out, kinds = [], ["gguf"] + (["mlx"] if MLX_OK else [])
+    for k in kinds:
+        for m in hf_api(f"models?search={urllib.parse.quote(q)}&filter={k}&sort=downloads&limit=15"):
+            out.append((m.get("downloads", 0), k, m["id"]))
+    out.sort(reverse=True)
+    return [(f"{k:5} {i}  ↓{n:,}", i) for n, k, i in out]
+
+def hf_files(repo):
+    info = hf_api(f"models/{repo}?blobs=true")
+    files = {s["rfilename"]: s.get("size") or 0 for s in info.get("siblings", [])}
+    gg, mm = {}, {}
+    for f, sz in files.items():
+        if not f.endswith(".gguf"): continue
+        if "mmproj" in f.lower(): mm[f] = sz; continue
+        if re.search(r"-0000[2-9]-of-", f): continue
+        part = re.split(r"-00001-of-", f)[0]
+        gg[f] = sum(z for g, z in files.items() if g.startswith(part)) if "-00001-of-" in f else sz
+    tags = info.get("tags", [])
+    kind = "gguf" if gg else ("mlx" if "mlx" in tags or "mlx" in repo.lower() else None)
+    return kind, gg, mm, files

minu/server.py

@@ -0,0 +1,85 @@
+"""Starting/stopping model servers and streaming chat completions."""
+import atexit, importlib.util, json, socket, subprocess, sys, time, urllib.error, urllib.request
+from pathlib import Path
+
+from .config import CTX, DIR, OLLAMA, TOOLS
+from .installs import which
+from .tools import get
+
+CHILDREN = []  # every server minu starts, so they never outlive it
+
+def spawn(cmd, **kw):
+    p = subprocess.Popen(cmd, stdin=subprocess.DEVNULL, **kw); CHILDREN.append(p); return p
+
+@atexit.register
+def kill_children():
+    for p in CHILDREN:
+        if p.poll() is None: p.terminate()
+    for p in CHILDREN:
+        try: p.wait(3)
+        except subprocess.TimeoutExpired: p.kill()
+
+def free_port():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0)); return s.getsockname()[1]
+
+class Server:
+    def __init__(s): s.proc, s.url, s.model, s.name, s.kind, s.ctx, s.resp, s.ref = None, None, None, "no model", None, None, None, None
+
+    def abort(s):  # unblock a thread stuck reading the stream (used on quit)
+        try: s.resp.fp.raw._sock.shutdown(socket.SHUT_RDWR)
+        except Exception: pass
+
+    def stop(s):
+        if s.proc and s.proc.poll() is None:
+            s.proc.terminate()
+            try: s.proc.wait(5)
+            except subprocess.TimeoutExpired: s.proc.kill()
+        s.proc, s.url = None, None
+
+    def start(s, kind, ref):
+        s.stop(); s.ctx, s.kind, s.ref = None, kind, ref
+        if kind == "ollama":
+            s.url, s.model, s.name = f"{OLLAMA}/v1", ref, ref; return
+        if kind == "url":
+            s.url = ref.rstrip("/") + ("" if ref.rstrip("/").endswith("/v1") else "/v1")
+            s.model = json.loads(get(s.url + "/models", timeout=5))["data"][0]["id"]; s.name = s.model; return
+        port = free_port()
+        if kind == "gguf":
+            src = ["-m", ref] if Path(ref).exists() else ["-hf", ref]
+            mm = sorted(Path(ref).parent.glob("*mmproj*.gguf"), key=lambda p: ("f32" in p.name.lower(), p.stat().st_size)) if Path(ref).exists() else []
+            cmd = [which("llama-server"), *src, *(["--mmproj", str(mm[0])] if mm else []), "--jinja", "-c", str(CTX), "--port", str(port)]
+            s.model, s.name, s.ctx, health = "local", Path(ref).name.removesuffix(".gguf"), CTX, "/health"
+        else:  # mlx
+            cmd = [sys.executable, "-m", "mlx_lm.server"] if importlib.util.find_spec("mlx_lm") else [which("mlx_lm.server")]
+            cmd += ["--model", ref, "--port", str(port)]
+            s.model, s.name, health = ref, ref.split("/")[-1], "/v1/models"
+        DIR.mkdir(parents=True, exist_ok=True)
+        log = open(DIR / "server.log", "w")
+        s.proc = spawn(cmd, stdout=log, stderr=subprocess.STDOUT)
+        base = f"http://127.0.0.1:{port}"
+        for _ in range(1200):
+            if s.proc.poll() is not None:
+                tail = (DIR / "server.log").read_text(errors="replace").strip().splitlines()[-3:]
+                raise RuntimeError("server exited: " + " / ".join(tail))
+            try: get(base + health, timeout=1); break
+            except Exception: time.sleep(0.5)
+        else: raise RuntimeError("server start timed out")
+        s.url = base + "/v1"
+
+    def stream(s, msgs, native, stop):
+        body = {"model": s.model, "messages": msgs, "stream": True, "stream_options": {"include_usage": True}}
+        if native: body["tools"] = TOOLS
+        req = urllib.request.Request(s.url + "/chat/completions", json.dumps(body).encode(), {"Content-Type": "application/json"})
+        try: r = urllib.request.urlopen(req, timeout=900)
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"{e.code}: {e.read().decode(errors='replace')[:400]}") from None
+        s.resp = r
+        with r:
+            for line in r:
+                if stop.is_set(): return
+                line = line.strip()
+                if line.startswith(b"data:"):
+                    d = line[5:].strip()
+                    if d == b"[DONE]": return
+                    yield json.loads(d)

minu/sessions.py

@@ -0,0 +1,75 @@
+"""Sessions saved as ~/.minu/sessions/<project>/<timestamp>.jsonl: a meta line, then one message per line."""
+import asyncio, json, re, threading, time
+from pathlib import Path
+
+from textual import work
+from textual.widgets import Markdown, Static
+
+from .config import MINU_HOME
+from .widgets import Picker
+
+ROOT = MINU_HOME / "sessions"
+CWD = Path.cwd().resolve()
+SESS = ROOT / re.sub(r"[^\w.-]", "-", str(CWD))  # one folder per project, e.g. -Users-me-code-app
+LEGACY = CWD / ".minu" / "sessions"              # where older versions saved, still listed
+_lock = threading.Lock()
+
+def read_jsonl(p):
+    out = []
+    for line in Path(p).read_text(errors="replace").splitlines():
+        try: out.append(json.loads(line))
+        except json.JSONDecodeError: pass  # half-written line from a crash
+    return out
+
+def session_files():  # this project's sessions, newest first
+    files = [*SESS.glob("*.jsonl"), *(LEGACY.glob("*.jsonl") if LEGACY.is_dir() else [])]
+    return sorted(files, key=lambda p: p.stat().st_mtime, reverse=True)
+
+def text_of(c): return c if isinstance(c, str) else next((x.get("text", "") for x in c if x.get("type") == "text"), "")
+
+def sessions():  # (label, path) for the picker
+    out = []
+    for p in session_files()[:50]:
+        msgs = [m for m in read_jsonl(p) if "role" in m]
+        first = next((text_of(m["content"]) for m in msgs if m["role"] == "user"), "").replace("\n", " ")[:60]
+        when = time.strftime("%Y-%m-%d %H:%M", time.localtime(p.stat().st_mtime))
+        out.append((f"{when}  ({len(msgs)} msgs)  {first}", p))
+    return out
+
+
+class SessionsMixin:
+    def push(s, m):
+        s.msgs.append(m)
+        with _lock:  # called from the UI and worker threads
+            if not s.session:
+                SESS.mkdir(parents=True, exist_ok=True)
+                stamp = time.strftime("%Y-%m-%d_%H-%M-%S"); p, i = SESS / f"{stamp}.jsonl", 1
+                while p.exists(): p, i = SESS / f"{stamp}-{i}.jsonl", i + 1
+                s.session = p
+                meta = {"cwd": str(CWD), "model": s.srv.name, "created": time.strftime("%Y-%m-%dT%H:%M:%S%z")}
+                with open(p, "a") as f: f.write(json.dumps({"meta": meta}) + "\n")
+            with open(s.session, "a") as f: f.write(json.dumps(m) + "\n")
+
+    def resume(s, path):
+        s.action_clear()
+        msgs = [m for m in read_jsonl(path) if "role" in m]
+        s.msgs, s.session = s.msgs[:1] + [m for m in msgs if m["role"] != "system"], Path(path)
+        for m in s.msgs[1:]:
+            c = m.get("content") or ""
+            if m["role"] == "user" and isinstance(c, str) and c.startswith("Output:\n") or m["role"] == "tool":
+                lines = (c.removeprefix("Output:\n")).splitlines()
+                s.note("\n".join(lines[:15]) + (f"\n… ({len(lines) - 15} more lines)" if len(lines) > 15 else ""), "out")
+            elif m["role"] == "user":
+                txt = c if isinstance(c, str) else text_of(c) + f"  [{len(c) - 1} image(s)]"
+                s.add(Static(f"> {txt}", classes="user", markup=False))
+            elif m["role"] == "assistant":
+                if c: s.add(Markdown(c))
+                for t in m.get("tool_calls") or []:
+                    try: s.note("$ " + json.loads(t["function"]["arguments"]).get("command", ""), "cmd")
+                    except Exception: pass
+        s.note(f"▸ resumed {Path(path).name} ({len(msgs)} messages)")
+
+    @work(exclusive=True, group="pick")
+    async def pick_session(s):
+        items = await asyncio.to_thread(sessions)
+        if p := await s.push_screen_wait(Picker(f"sessions for {CWD.name}", items)): s.resume(p)

minu/tools.py

@@ -0,0 +1,100 @@
+"""The agent's shell tool, web search/fetch, and parsing commands out of replies."""
+import html, json, os, re, shlex, subprocess, sys, time, urllib.parse, urllib.request
+from html.parser import HTMLParser
+
+from .config import DIR, HOME, OUT_MAX, UA
+
+def get(url, data=None, timeout=20, headers=None):
+    req = urllib.request.Request(url, data=data, headers={**UA, **(headers or {})})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return r.read().decode("utf-8", "replace")
+
+class _Text(HTMLParser):
+    SKIP, BR = {"script", "style", "noscript", "svg", "head"}, {"p", "br", "div", "li", "tr", "h1", "h2", "h3", "h4", "pre"}
+    def __init__(s): super().__init__(); s.out, s.skip = [], 0
+    def handle_starttag(s, t, a):
+        if t in s.SKIP: s.skip += 1
+        elif t in s.BR: s.out.append("\n")
+    def handle_endtag(s, t):
+        if t in s.SKIP and s.skip: s.skip -= 1
+    def handle_data(s, d):
+        if not s.skip: s.out.append(d)
+
+def fetch(url):
+    p = _Text(); p.feed(get(url))
+    t = re.sub(r"[ \t]+", " ", "".join(p.out))
+    return re.sub(r"\s*\n\s*", "\n", t).strip()[:8000]
+
+def _ddg(q):
+    for _ in range(2):  # DuckDuckGo throttles bursts; retry once
+        h = get("https://html.duckduckgo.com/html/", urllib.parse.urlencode({"q": q}).encode())
+        if "result__a" in h: break
+        time.sleep(2)
+    out = []
+    for u, t, s in re.findall(r'class="result__a" href="([^"]+)"[^>]*>(.*?)</a>.*?class="result__snippet"[^>]*>(.*?)</a>', h, re.S):
+        out.append((t, urllib.parse.parse_qs(urllib.parse.urlparse(html.unescape(u)).query).get("uddg", [u])[0], s))
+    return out
+
+def _wikipedia(q):
+    j = json.loads(get("https://en.wikipedia.org/w/api.php?" + urllib.parse.urlencode(
+        {"action": "query", "list": "search", "srsearch": q, "format": "json", "srlimit": 5})))
+    return [(r["title"], "https://en.wikipedia.org/wiki/" + urllib.parse.quote(r["title"].replace(" ", "_")), r["snippet"])
+            for r in j["query"]["search"]]
+
+def _searxng(q):  # optional: MINU_SEARXNG=https://your-instance
+    j = json.loads(get(os.environ["MINU_SEARXNG"].rstrip("/") + "/search?" + urllib.parse.urlencode({"q": q, "format": "json"})))
+    return [(r.get("title", ""), r.get("url", ""), r.get("content", "")) for r in j.get("results", [])]
+
+def search(q):  # first engine that answers wins
+    clean = lambda x: html.unescape(re.sub(r"<.*?>", "", x)).strip()
+    engines = ([_searxng] if os.environ.get("MINU_SEARXNG") else []) + [_ddg, _wikipedia]
+    for engine in engines:
+        try: res = engine(q)
+        except Exception: res = []
+        if res:
+            return f"[{engine.__name__[1:]}]\n\n" + "\n\n".join(f"{clean(t)}\n{u}\n{clean(s)}" for t, u, s in res[:8])
+    return "search failed: no engine answered (rate-limited?). Try again shortly, or minu-fetch a URL you know."
+
+def shims():
+    (DIR / "bin").mkdir(parents=True, exist_ok=True)
+    for n in ("search", "fetch"):
+        p = DIR / "bin" / f"minu-{n}"
+        p.write_text(f'#!/bin/sh\nexec "{sys.executable}" -m minu {n} "$*"\n'); p.chmod(0o755)
+
+def sh_env():
+    return {**os.environ, "PATH": f"{DIR / 'bin'}:{os.environ['PATH']}:{HOME}/.local/bin"}
+
+def sh(cmd, timeout=120):
+    try:
+        r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=timeout,
+                           env=sh_env(), executable="/bin/bash", stdin=subprocess.DEVNULL)
+        out = (r.stdout + r.stderr).strip() + ("" if r.returncode == 0 else f"\n[exit {r.returncode}]")
+    except subprocess.TimeoutExpired:
+        out = f"[timed out after {timeout}s]"
+    out = out.strip() or "[no output]"
+    if len(out) > OUT_MAX:
+        out = out[:OUT_MAX // 2] + f"\n...[{len(out) - OUT_MAX} chars cut]...\n" + out[-OUT_MAX // 2:]
+    return out
+
+def to_cmd(m):  # ```sh block, or a model's own <tool_call> / JSON call -> shell command
+    if m.group(1) is not None: return m.group(1).strip()
+    t = m.group(2).strip()
+    try:
+        j = json.loads(t); name, args = j.get("name", ""), j.get("arguments") or {}
+    except json.JSONDecodeError:
+        name = (re.search(r"<function=([^>\s]+)>", t) or re.search(r"(\S+)", t)).group(1)
+        args = dict(re.findall(r"<parameter=([^>]+)>\s*(.*?)\s*</parameter>", t, re.S))
+    if isinstance(args, str): args = {"command": args}
+    if name in ("sh", "bash", "shell", "run", "exec", "terminal") or "command" in args:
+        return str(args.get("command") or next(iter(args.values()), ""))
+    return " ".join([name, *(shlex.quote(str(v)) for v in args.values())])
+
+def split_think(t):  # reply -> (thinking, answer); handles an unclosed <think> while streaming
+    head = t.split("</think>")[0]
+    if "</think>" in t and "<think>" not in head: t = "<think>" + t  # chat template already opened <think>
+    think = "".join(re.findall(r"<think>(.*?)</think>", t, re.S))
+    rest = re.sub(r"<think>.*?</think>", "", t, flags=re.S)
+    if "<think>" in rest: rest, tail = rest.split("<think>", 1); think += tail
+    return think.strip(), rest.strip()
+
+def strip_think(t): return split_think(t)[1]

minu/widgets.py

@@ -0,0 +1,43 @@
+"""Input box, list picker and text prompt."""
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.message import Message
+from textual.screen import ModalScreen
+from textual.widgets import Input, OptionList, Static, TextArea
+
+
+class Prompt(TextArea):  # multi-line input: enter sends, ctrl+j newline; drives the / menu
+    BINDINGS = [Binding("enter", "send", "send", priority=True), Binding("ctrl+j", "newline", "newline", priority=True),
+                Binding("up", "menu(-1)", show=False, priority=True), Binding("down", "menu(1)", show=False, priority=True),
+                Binding("tab", "complete", show=False, priority=True), Binding("escape", "close_menu", show=False, priority=True)]
+    class Submitted(Message):
+        def __init__(s, value): super().__init__(); s.value = value
+    def menu_open(s): return s.app.query_one("#slash").display
+    def check_action(s, action, params):  # menu keys only act while the menu is open
+        return s.menu_open() if action in ("menu", "complete", "close_menu") else True
+    def action_send(s):
+        if s.menu_open(): return s.app.slash_choose()
+        s.post_message(s.Submitted(s.text)); s.clear()
+    def action_newline(s): s.insert("\n")
+    def action_menu(s, d): s.app.slash_move(d)
+    def action_complete(s): s.app.slash_choose(complete_only=True)
+    def action_close_menu(s): s.app.query_one("#slash").display = False
+
+
+class Picker(ModalScreen):
+    CSS = "Picker { align: center middle; } OptionList { width: 90%; max-height: 80%; border: round $accent; }"
+    BINDINGS = [("escape", "dismiss(None)", "close")]
+    def __init__(s, title, items): super().__init__(); s.title_, s.items = title, items
+    def compose(s):
+        ol = OptionList(*[i[0] for i in s.items] or ["(nothing found)"]); ol.border_title = s.title_; yield ol
+    def on_option_list_option_selected(s, e):
+        s.dismiss(s.items[e.option_index][1] if s.items else None)
+
+class Ask(ModalScreen):
+    CSS = "Ask { align: center middle; } #box { width: 80%; height: auto; border: round $accent; padding: 0 1; }"
+    BINDINGS = [("escape", "dismiss(None)", "close")]
+    def __init__(s, title, hint): super().__init__(); s.title_, s.hint = title, hint
+    def compose(s):
+        with Vertical(id="box"):
+            yield Static(s.title_); yield Input(placeholder=s.hint)
+    def on_input_submitted(s, e): e.stop(); s.dismiss(e.value.strip() or None)

minu-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: minu
+Version: 0.1.0
+Summary: Tiny agent harness for local models (llama.cpp, MLX, Ollama)
+Keywords: agent,llm,local-llm,llama.cpp,mlx,ollama,tui,coding-agent
+Author: mr-jones123
+Author-email: mr-jones123 <lacapxyniljhed@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Dist: textual>=1.0
+Requires-Dist: textual-image>=0.8
+Requires-Dist: pillow>=10.3
+Requires-Dist: mlx-lm ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/mr-jones123/minu
+Project-URL: Repository, https://github.com/mr-jones123/minu
+Project-URL: Issues, https://github.com/mr-jones123/minu/issues
+Provides-Extra: mlx
+Description-Content-Type: text/markdown
+
+# minu
+
+A very small agent harness for local models. One tool (`sh`) and a system prompt of about 86 tokens.
+
+```
+uv tool install minu              # or: pipx install minu   (needs Python 3.13; uv fetches it for you)
+minu                              # run it in any project folder
+```
+Upgrade with `uv tool upgrade minu`, remove with `uv tool uninstall minu`. Sessions are saved in `~/.minu/`.
+
+```
+minu                              # opens the model picker
+minu --hf LiquidAI/LFM3-1.7B-GGUF
+minu --mlx mlx-community/Qwen3-1.7B-4bit
+minu --ollama gemma3:4b
+minu --url http://localhost:8080           # server that's already running
+```
+
+`-y` runs commands without asking. `--native` uses the server's tool-call API instead of ```sh blocks.
+
+## Models
+`ctrl+o` (or `/model`) opens the picker. It has:
+- the GGUF and MLX models in your Hugging Face cache, plus your Ollama models
+- **⬇ download from Hugging Face**: search, or paste `org/repo`, then pick a size. For vision repos the `mmproj` file is downloaded too.
+- **⬇ pull from Ollama**: any name from ollama.com/library, with progress shown in the status bar.
+
+Switching models stops the old server and starts the new one. The chat stays.
+
+**✕ delete a model** (in the picker, or `/delete`) lists your downloaded models with their size on disk. It asks before
+deleting (the default is "keep it"). For GGUF it removes that quant, plus the whole repo (mmproj, cache entry) once
+no weights are left in it; MLX repos are removed whole; Ollama models go through `ollama`'s API. A loaded model is stopped first.
+`esc` cancels a download.
+
+If something is missing, minu offers to install it (it always asks first):
+| needed for | tool | install |
+|---|---|---|
+| GGUF | llama-server | `brew install llama.cpp` |
+| MLX (Apple Silicon only) | mlx_lm | `uv tool install mlx-lm` |
+| HF downloads | hf | `uv tool install huggingface_hub` |
+| Ollama | ollama | `brew install ollama` / ollama.com install script |
+
+If Ollama is installed but not running, minu starts `ollama serve` itself and stops it when you quit.
+
+## Images
+Put an image path in your message (dragging a file into the terminal pastes its path):
+`what's in ~/Desktop/shot.png?`
+The image is shown in the chat and sent to the model. That needs a vision model: GGUF repos with an
+mmproj (marked `[vision]` in the picker), or an Ollama vision model such as `gemma3:4b`. MLX models are text only.
+Image files the model mentions in its answer are shown too, and `/view path.png` shows any image.
+Images render as real pixels in Kitty, Ghostty, WezTerm and iTerm2, and as colored blocks in other terminals.
+
+## Sessions
+Each chat is saved to `~/.minu/sessions/<project>/<timestamp>.jsonl` (one folder per project path, e.g.
+`-Users-me-code-app`): a `{"meta": …}` line, then one message per line. Set `MINU_HOME` to move `~/.minu`.
+Sessions from older versions in `./.minu/sessions` still show up in `/resume`.
+`/resume` opens a session picker · `minu -c` continues the latest one · `minu -r FILE` opens a specific file · `/new` (or `ctrl+n`) starts a new session.
+
+## Keys
+`enter` send · `ctrl+j` newline · `ctrl+o` model · `ctrl+y` auto-run · `esc` stop · `ctrl+n` new session · `ctrl+c` quit
+Type `/` for a menu of commands (↑/↓ to move, tab to complete, enter to run, esc to close):
+`/new` `/model` `/delete` `/resume` `/search <query>` `/fetch <url>` `/view <img>` `/auto` `/clear` `/exit`
+
+## Web
+The model can search on its own (`minu-search "q"`, `minu-fetch URL` in its shell). You can also do it yourself:
+`/search <query>` gets results and the model answers from them; `/fetch <url>` reads a page and the model summarizes it.
+Search tries DuckDuckGo first, then Wikipedia's API. DuckDuckGo sometimes rate-limits; for search that never gets blocked,
+point minu at your own SearXNG instance: `MINU_SEARXNG=http://localhost:8888`.
+Env: `MINU_CTX` (llama.cpp context, default 16384), `MINU_HOME` (default `~/.minu`), `OLLAMA_HOST`, `HF_HOME`. Server log: `~/.cache/minu/server.log`.
+
+## Development
+```
+git clone https://github.com/mr-jones123/minu && cd minu
+uv tool install -e .              # global `minu` that runs your checkout (changes to src/ apply right away)
+uv run minu                       # or run it from the repo
+uv build                          # sdist + wheel into dist/
+```
+
+## Releasing to PyPI
+Publishing runs in GitHub Actions (`.github/workflows/publish.yml`) with PyPI Trusted Publishing, so no token is stored.
+One-time setup: on pypi.org → *Your account → Publishing → Add a pending publisher*: project `minu`,
+owner `mr-jones123`, repo `minu`, workflow `publish.yml`, environment `pypi`. Then for each release:
+```
+uv version --bump patch           # or minor / major; edits pyproject.toml
+git commit -am "release v$(uv version --short)" && git tag v$(uv version --short) && git push --follow-tags
+```
+CI builds, smoke-tests the wheel, checks the tag matches the version, and uploads.
+
+## Code layout (`src/minu/`, the `minu` package)
+| file | what it does |
+|---|---|
+| `cli.py` | command-line flags, plus `minu search` / `minu fetch` for the agent's shell |
+| `config.py` | paths, limits, system prompts, banner |
+| `app.py` | the TUI: layout, status bar, input handling |
+| `agent.py` | agent loop: stream a reply, run its command, send the output back |
+| `model_flows.py` | model picker, HF/Ollama downloads, install offers, loading |
+| `sessions.py` | saving and resuming `~/.minu/sessions/<project>/*.jsonl` |
+| `server.py` | starting llama-server / mlx_lm / Ollama and streaming chat |
+| `models.py` | finding local models and searching Hugging Face |
+| `tools.py` | the `sh` tool, web search/fetch, parsing commands from replies |
+| `images.py` | attaching images and showing them |
+| `installs.py` | finding tools and their install commands |
+| `widgets.py` | input box, list picker, text prompt |
+
+## License
+MIT, see [LICENSE](LICENSE).

minu-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+minu/__init__.py,sha256=GyE9d88zAWJoowKwK8J5f7Z_xCtp2t_rC6h_xfNlif8,226
+minu/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+minu/agent.py,sha256=0pqmSmzz6mD3PIFu8z7UmcHhbGHPbpabYU29bW5Cy_o,6509
+minu/app.py,sha256=-51EOKHFy1hHnenN45-ylUAUYDCI5gfSAS2E7NMzu1c,10280
+minu/cli.py,sha256=kYw53JLOuYgHwswZdirGroJl1OIKkclkEx0zU_LbRp4,2652
+minu/config.py,sha256=rZhcl2qWzh6W54huuuyfigm_fd-5qsounOjBNX0kPdA,3087
+minu/images.py,sha256=9jNu5Omw8pYOcFv74TFZlx9whhIs3Aq-uzy42IpJidk,1204
+minu/installs.py,sha256=nVwTl2BSsnZYnOXRg3p1sVvlzSOmkDc0SgUIjtZD0fo,1118
+minu/model_flows.py,sha256=7sk-qA_UqN5S6XZUJ5TydTIYV3y5UaHOuKvP8w3iufE,8195
+minu/models.py,sha256=OZK4hdtYKjEbnb5Ndqf4T3TETwBkjziAWsISLl8ZPyU,5157
+minu/server.py,sha256=fdeph0KW8YFbHjKUG8EbfJDKdN7L9jg4jpJutZIw7tE,4005
+minu/sessions.py,sha256=1u3OZCHKW6D2drnqCli9e7KVWGPADx4y-LAn8oMYMq4,3624
+minu/tools.py,sha256=iNd52HCR785_1Q537x2xrvtQ9PBVhqlhlbZt0QbU4Ak,5078
+minu/widgets.py,sha256=UpwwaKWFWxgWdZcpPcsRgccAVgTpgRf6GJwhAorj7xs,2432
+minu-0.1.0.dist-info/licenses/LICENSE,sha256=crU8zqxRSIoEGZ34dc8XNktSD4NtLdhED1yI0j2VW2Y,1068
+minu-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+minu-0.1.0.dist-info/entry_points.txt,sha256=q6FlCvTV19v7656P8nIU2i92b3KMi7DoiGE-MobyOoU,40
+minu-0.1.0.dist-info/METADATA,sha256=JB4bRPcI-J1OMfTLx-ThhVD6vf0slYo-aJ--Du7gDdE,7098
+minu-0.1.0.dist-info/RECORD,,

minu-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

minu-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+minu = minu.cli:main
+

minu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mr-jones123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.