dulus 0.2.23__tar.gz → 0.2.25__tar.gz

{dulus-0.2.23/dulus.egg-info → dulus-0.2.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dulus
-Version: 0.2.23
+Version: 0.2.25
 Summary: Spanish-first multi-provider AI CLI — 14 NVIDIA models free, Mesa Redonda, voice, TTS, RTK token reducer, MemPalace
 Author: KevRojo
 License: GPL-3.0
@@ -69,7 +69,7 @@ SET /sticky_input ON since the first run for the best experience!
   <a href="https://pypi.org/project/dulus/"><img src="https://static.pepy.tech/badge/dulus?style=flat-square" alt="downloads"/></a>
   <img src="https://img.shields.io/badge/python-3.11+-ff6b1f?style=flat-square&labelColor=07070a" alt="python"/>
   <img src="https://img.shields.io/badge/license-GPLv3-ff6b1f?style=flat-square&labelColor=07070a" alt="license"/>
-  <img src="https://img.shields.io/badge/version-v0.2.23-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.25-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
   <img src="https://img.shields.io/badge/providers-11-ff6b1f?style=flat-square&labelColor=07070a" alt="providers"/>
   <img src="https://img.shields.io/badge/tools-27-ff6b1f?style=flat-square&labelColor=07070a" alt="tools"/>
   <img src="https://img.shields.io/badge/tests-263+-ff6b1f?style=flat-square&labelColor=07070a" alt="tests"/>
@@ -103,6 +103,26 @@ Use claude-code as an API without the new 'extra-usage' wall <3
   <sub>⚡ <b>Saves you Claude tokens?</b> Throw a sat — BTC: <code>1JzatQDn9fMLnKTd3KYgztsLHC95bJEzSN</code></sub>
 </p>
 
+
+Another reminder of a Dulus magic spell: 
+Wanna get stock prices, history , etc? 
+
+/plugin install yfinance@https://github.com/ranaroussi/yfinance
+
+them:
+/plugin reload
+
+dulus get the prices of NVDA, TSLA, SP500:
+
+<img width="2094" height="1365" alt="image" src="https://github.com/user-attachments/assets/1551d651-9d69-4607-bac0-4adbde645783" />
+
+Be creative!!! 
+
+Dulus adapt any python repository <3
+
+<p align="center"><img src="https://raw.githubusercontent.com/KevRojo/Dulus/main/docs/divider.svg" alt="" width="100%"></p>
+
+
 Dulus is a **lightweight Python reimplementation of Claude Code** that isn't locked to Claude. It ships the whole loop — REPL, tool dispatch, streaming, context compaction, checkpoints, sub-agents, voice, Telegram bridge, MCP, plugins — in roughly **12K lines you can actually read**. Fork it. Bend it. Run it offline against Qwen on your M2.
 
 > **v0.2.22 — May 9, 2026** — `/bg start` spawns one detached Dulus daemon that serves CLI (IPC), Web (browser at `127.0.0.1:5000`), and Telegram simultaneously — all sharing the same session. WebChat now defaults to **loopback-only** (opt-in to LAN exposure with `/webchat lan on`).
@@ -341,6 +361,23 @@ Dulus's **Auto-Adapter** reads a random Python repo and figures out its tools on
 
 Adapt-and-install runs in under a second. New tools register **live**, no restart.
 
+Example adapting Sherlock repo:
+
+<img width="1765" height="166" alt="image" src="https://github.com/user-attachments/assets/c67dc15e-a2e3-4575-be34-8c9b54045510" />
+
+-----
+
+<img width="1327" height="751" alt="image" src="https://github.com/user-attachments/assets/676a0ef5-3699-4960-98a4-14a55fbef081" />
+
+-----
+
+<img width="885" height="301" alt="image" src="https://github.com/user-attachments/assets/52c02444-2606-41dc-bc33-ebe26ac41e5e" />
+
+----
+
+<img width="1006" height="271" alt="image" src="https://github.com/user-attachments/assets/d823428e-6344-4414-bf42-14ed3128f763" />
+
+
 ## MCP
 
 Drop a `.mcp.json` in your project root (or `~/.dulus/mcp.json` for user-wide):

{dulus-0.2.23 → dulus-0.2.25}/README.md

@@ -22,7 +22,7 @@ SET /sticky_input ON since the first run for the best experience!
   <a href="https://pypi.org/project/dulus/"><img src="https://static.pepy.tech/badge/dulus?style=flat-square" alt="downloads"/></a>
   <img src="https://img.shields.io/badge/python-3.11+-ff6b1f?style=flat-square&labelColor=07070a" alt="python"/>
   <img src="https://img.shields.io/badge/license-GPLv3-ff6b1f?style=flat-square&labelColor=07070a" alt="license"/>
-  <img src="https://img.shields.io/badge/version-v0.2.23-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.25-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
   <img src="https://img.shields.io/badge/providers-11-ff6b1f?style=flat-square&labelColor=07070a" alt="providers"/>
   <img src="https://img.shields.io/badge/tools-27-ff6b1f?style=flat-square&labelColor=07070a" alt="tools"/>
   <img src="https://img.shields.io/badge/tests-263+-ff6b1f?style=flat-square&labelColor=07070a" alt="tests"/>
@@ -56,6 +56,26 @@ Use claude-code as an API without the new 'extra-usage' wall <3
   <sub>⚡ <b>Saves you Claude tokens?</b> Throw a sat — BTC: <code>1JzatQDn9fMLnKTd3KYgztsLHC95bJEzSN</code></sub>
 </p>
 
+
+Another reminder of a Dulus magic spell: 
+Wanna get stock prices, history , etc? 
+
+/plugin install yfinance@https://github.com/ranaroussi/yfinance
+
+them:
+/plugin reload
+
+dulus get the prices of NVDA, TSLA, SP500:
+
+<img width="2094" height="1365" alt="image" src="https://github.com/user-attachments/assets/1551d651-9d69-4607-bac0-4adbde645783" />
+
+Be creative!!! 
+
+Dulus adapt any python repository <3
+
+<p align="center"><img src="https://raw.githubusercontent.com/KevRojo/Dulus/main/docs/divider.svg" alt="" width="100%"></p>
+
+
 Dulus is a **lightweight Python reimplementation of Claude Code** that isn't locked to Claude. It ships the whole loop — REPL, tool dispatch, streaming, context compaction, checkpoints, sub-agents, voice, Telegram bridge, MCP, plugins — in roughly **12K lines you can actually read**. Fork it. Bend it. Run it offline against Qwen on your M2.
 
 > **v0.2.22 — May 9, 2026** — `/bg start` spawns one detached Dulus daemon that serves CLI (IPC), Web (browser at `127.0.0.1:5000`), and Telegram simultaneously — all sharing the same session. WebChat now defaults to **loopback-only** (opt-in to LAN exposure with `/webchat lan on`).
@@ -294,6 +314,23 @@ Dulus's **Auto-Adapter** reads a random Python repo and figures out its tools on
 
 Adapt-and-install runs in under a second. New tools register **live**, no restart.
 
+Example adapting Sherlock repo:
+
+<img width="1765" height="166" alt="image" src="https://github.com/user-attachments/assets/c67dc15e-a2e3-4575-be34-8c9b54045510" />
+
+-----
+
+<img width="1327" height="751" alt="image" src="https://github.com/user-attachments/assets/676a0ef5-3699-4960-98a4-14a55fbef081" />
+
+-----
+
+<img width="885" height="301" alt="image" src="https://github.com/user-attachments/assets/52c02444-2606-41dc-bc33-ebe26ac41e5e" />
+
+----
+
+<img width="1006" height="271" alt="image" src="https://github.com/user-attachments/assets/d823428e-6344-4414-bf42-14ed3128f763" />
+
+
 ## MCP
 
 Drop a `.mcp.json` in your project root (or `~/.dulus/mcp.json` for user-wide):

{dulus-0.2.23 → dulus-0.2.25}/docs/news.md

@@ -3,6 +3,15 @@
 ## 🔥🔥🔥 News (Pacific Time)
 
 
+- May 09, 2026 (**v0.2.25**): **`/skill list awesome` no longer hangs** — was fetching 235 SKILL.md files sequentially (50-120 seconds, looked frozen). Now uses one GitHub tree API call (instant, <1s, names only) by default; pass `--full` to also pull per-skill descriptions in parallel via a 12-worker thread pool (~5s instead of 120s). Cache stores the with_descriptions flag so future calls reuse the right data.
+
+- May 09, 2026 (**v0.2.24**): **Auto-adapter prompt — 5 fixes from a sherlock postmortem**
+  - **Reconciled `limit` default** — the prompt had two contradictory rules ("default: 50, max: 200" vs "default: 10, NOT 50"). Models burned tokens reasoning about which to follow. Unified on `default: 10, hard max: 200` everywhere.
+  - **"READ the source first" rule** at the top of the wrapper guidelines. Adapters were inferring upstream function signatures from class names and shipping plugins that compile/import/export cleanly but crash at runtime due to type-shape mismatches. Now the prompt explicitly tells the model to read the consumer code (`param.get(...)` / `for x in param`) before guessing shapes.
+  - **Notifier/callback pattern hint** — when the upstream library has a notify/callback class, prefer collecting results via that callback over parsing the return value. Callbacks tend to stay stable; return shapes drift between versions.
+  - **`ADAPTATION_GUIDE.md` now requires a `## Type Contracts` section** documenting the exact shape of every non-trivial parameter. Read by the verifier and by future re-adaptations — eliminates blind re-guessing.
+  - **Verifier checklist explicitly flags the smoke test as THE BAR.** Compile / import / exports / ToolDef-shape are necessary but not sufficient. The new header in `ADAPTATION_TODO.md` warns the model not to celebrate after the syntactic checks — most real bugs are type-shape mismatches that only the smoke test catches.
+
 - May 09, 2026 (**v0.2.23**): **Auto-adapter teaches new plugins to declare TmuxOffload-worthy tools**
   - **The adapter prompt now requires** the model to estimate per-tool runtime. Any tool that typically takes more than ~15 seconds (sherlock, holehe, OSINT crawls, video downloads, full-repo analysis, etc.) must end its `description` with the literal marker `[long-running — wrap in TmuxOffload]`.
   - **System prompt now honors that marker** at runtime. When the agent sees a tool with that suffix, it wraps the call in TmuxOffload automatically instead of blocking the REPL. No more 90-second sherlock freezes pretending to be productive.

{dulus-0.2.23 → dulus-0.2.25/dulus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dulus
-Version: 0.2.23
+Version: 0.2.25
 Summary: Spanish-first multi-provider AI CLI — 14 NVIDIA models free, Mesa Redonda, voice, TTS, RTK token reducer, MemPalace
 Author: KevRojo
 License: GPL-3.0
@@ -69,7 +69,7 @@ SET /sticky_input ON since the first run for the best experience!
   <a href="https://pypi.org/project/dulus/"><img src="https://static.pepy.tech/badge/dulus?style=flat-square" alt="downloads"/></a>
   <img src="https://img.shields.io/badge/python-3.11+-ff6b1f?style=flat-square&labelColor=07070a" alt="python"/>
   <img src="https://img.shields.io/badge/license-GPLv3-ff6b1f?style=flat-square&labelColor=07070a" alt="license"/>
-  <img src="https://img.shields.io/badge/version-v0.2.23-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.25-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
   <img src="https://img.shields.io/badge/providers-11-ff6b1f?style=flat-square&labelColor=07070a" alt="providers"/>
   <img src="https://img.shields.io/badge/tools-27-ff6b1f?style=flat-square&labelColor=07070a" alt="tools"/>
   <img src="https://img.shields.io/badge/tests-263+-ff6b1f?style=flat-square&labelColor=07070a" alt="tests"/>
@@ -103,6 +103,26 @@ Use claude-code as an API without the new 'extra-usage' wall <3
   <sub>⚡ <b>Saves you Claude tokens?</b> Throw a sat — BTC: <code>1JzatQDn9fMLnKTd3KYgztsLHC95bJEzSN</code></sub>
 </p>
 
+
+Another reminder of a Dulus magic spell: 
+Wanna get stock prices, history , etc? 
+
+/plugin install yfinance@https://github.com/ranaroussi/yfinance
+
+them:
+/plugin reload
+
+dulus get the prices of NVDA, TSLA, SP500:
+
+<img width="2094" height="1365" alt="image" src="https://github.com/user-attachments/assets/1551d651-9d69-4607-bac0-4adbde645783" />
+
+Be creative!!! 
+
+Dulus adapt any python repository <3
+
+<p align="center"><img src="https://raw.githubusercontent.com/KevRojo/Dulus/main/docs/divider.svg" alt="" width="100%"></p>
+
+
 Dulus is a **lightweight Python reimplementation of Claude Code** that isn't locked to Claude. It ships the whole loop — REPL, tool dispatch, streaming, context compaction, checkpoints, sub-agents, voice, Telegram bridge, MCP, plugins — in roughly **12K lines you can actually read**. Fork it. Bend it. Run it offline against Qwen on your M2.
 
 > **v0.2.22 — May 9, 2026** — `/bg start` spawns one detached Dulus daemon that serves CLI (IPC), Web (browser at `127.0.0.1:5000`), and Telegram simultaneously — all sharing the same session. WebChat now defaults to **loopback-only** (opt-in to LAN exposure with `/webchat lan on`).
@@ -341,6 +361,23 @@ Dulus's **Auto-Adapter** reads a random Python repo and figures out its tools on
 
 Adapt-and-install runs in under a second. New tools register **live**, no restart.
 
+Example adapting Sherlock repo:
+
+<img width="1765" height="166" alt="image" src="https://github.com/user-attachments/assets/c67dc15e-a2e3-4575-be34-8c9b54045510" />
+
+-----
+
+<img width="1327" height="751" alt="image" src="https://github.com/user-attachments/assets/676a0ef5-3699-4960-98a4-14a55fbef081" />
+
+-----
+
+<img width="885" height="301" alt="image" src="https://github.com/user-attachments/assets/52c02444-2606-41dc-bc33-ebe26ac41e5e" />
+
+----
+
+<img width="1006" height="271" alt="image" src="https://github.com/user-attachments/assets/d823428e-6344-4414-bf42-14ed3128f763" />
+
+
 ## MCP
 
 Drop a `.mcp.json` in your project root (or `~/.dulus/mcp.json` for user-wide):

{dulus-0.2.23 → dulus-0.2.25}/dulus.py

@@ -218,7 +218,7 @@ try:
     from importlib.metadata import version as _pkg_version
     VERSION = _pkg_version("dulus")
 except Exception:
-    VERSION = "0.2.23"  # dev fallback — keep in sync with pyproject.toml
+    VERSION = "0.2.25"  # dev fallback — keep in sync with pyproject.toml
 
 # ── ANSI helpers (used even with rich for non-markdown output) ─────────────
 from common import C, clr, info, ok, warn, err, stream_thinking, print_tool_start, print_tool_end, sanitize_text
@@ -4251,17 +4251,27 @@ def cmd_skill(args: str, state, config) -> bool:
 
         if rest.startswith("awesome"):
             query = rest[7:].strip()
-            info("Fetching awesome skills from GitHub (cached 24h)...")
-            skills = list_awesome_remote(query)
+            # `--full` flag pulls per-skill descriptions in parallel (slower but
+            # informative). Default lists names only — instant.
+            full = False
+            if "--full" in query.split():
+                full = True
+                query = " ".join(t for t in query.split() if t != "--full").strip()
+            if full:
+                info("Fetching awesome skills + descriptions from GitHub (parallel, ~5s)...")
+            else:
+                info("Fetching awesome skill list from GitHub (instant)...")
+            skills = list_awesome_remote(query, with_descriptions=full)
             if not skills:
                 err("Could not fetch awesome skills (network or rate-limit).")
                 return True
             lines = [
-                f"  {clr(s['id'], 'cyan'):55s}  {s['description'][:80]}"
+                f"  {clr(s['id'], 'cyan'):55s}  {s.get('description', '')[:80]}"
                 for s in skills
             ]
             header = f"Awesome skills ({len(skills)})" + (f" matching '{query}'" if query else "")
-            _pager(f"{header} — n=next q=quit", lines)
+            hint = "" if full else " — add `--full` for descriptions"
+            _pager(f"{header}{hint} — n=next q=quit", lines)
             return True
 
         if rest.startswith("composio"):

{dulus-0.2.23 → dulus-0.2.25}/plugin/autoadapter.py

@@ -250,6 +250,13 @@ GOAL: Generate `plugin.json`, `plugin_tool.py`, and `ADAPTATION_GUIDE.md`.
 
 GUIDELINES FOR plugin_tool.py:
 
+0. READ THE SOURCE FIRST (critical — skip and you'll waste 10+ retry rounds):
+   - Before writing the wrapper, READ the actual function/class definitions you'll be calling.
+   - Note the EXACT shape each parameter expects: raw dict-of-dicts vs object-of-objects vs list of objects.
+   - DO NOT infer shapes from class names. Read the consumer code that does `param.get(...)` or `for x in param: ...`.
+   - When the upstream library has a notifier/callback/observer class, PREFER collecting results via that callback over parsing the return value — callbacks are usually consistent across versions, return shapes are not.
+   - Common gotcha: a class called `XInformation` often *wraps* the raw dict in `.information` or `.data`. The downstream function may expect the raw dict, not the wrapper. Verify by reading the function body.
+
 1. EXPORTS (mandatory):
    - `TOOL_DEFS`: list of `ToolDef(name, schema, func)` objects
    - `TOOL_SCHEMAS`: `[t.schema for t in TOOL_DEFS]`
@@ -272,7 +279,7 @@ GUIDELINES FOR plugin_tool.py:
 
 4. SCHEMA DESIGN:
    - Each param gets its own property. Never bundle into single "data" string
-   - Include `limit`/`max_results` (default: 10, NOT 50) and `verbose` (default: False) on every tool
+   - Include `limit`/`max_results` (default: 10, hard max: 200) and `verbose` (default: False) on every tool
 
 5. TOOL GRANULARITY:
    - Multiple specific tools > one mega-tool
@@ -362,6 +369,19 @@ TMUX-OFFLOAD HINT (important for UX):
 Respond with the delimited format:
 ---FILE: ADAPTATION_GUIDE.md---
 (Overview, tool design decisions, error patterns, validation)
+
+The ADAPTATION_GUIDE.md MUST include a `## Type Contracts` section that documents,
+for each upstream function/class you call, the EXACT shape of every non-trivial
+parameter. Example:
+
+## Type Contracts
+- `sherlock(username, site_data, ...)` expects `site_data: Dict[str, Dict[str, Any]]`
+  (NOT `Dict[str, SiteInformation]` — extract `.information` from each SiteInformation first).
+- `notifier.update(result)` is called once per site with a `QueryResult` object.
+  Collect via a `_SilentNotify(QueryNotify)` subclass instead of parsing the return dict.
+
+This section is read by the verifier and by future re-adaptations, so be precise.
+
 ---FILE: plugin.json---
 (JSON manifest)
 ---FILE: plugin_tool.py---
@@ -399,7 +419,7 @@ Respond with the delimited format:
             "- Always encoding='utf-8', errors='replace' for file/subprocess I/O\n"
             "- Never lowercase true/false/null in Python — always True/False/None\n\n"
             "TOKEN OPTIMIZATION RULES — plugins MUST be efficient:\n"
-            "- Every tool MUST accept a 'limit' or 'max_results' parameter (default: 50, max: 200)\n"
+            "- Every tool MUST accept a 'limit' or 'max_results' parameter (default: 10, hard max: 200)\n"
             "- Every tool MUST accept a 'verbose' parameter (default: False)\n"
             "- When verbose=False, return ONLY essential data — no debug info, no banners\n"
             "- Lists/arrays MUST be truncated before returning — never return unlimited items\n"
@@ -807,6 +827,14 @@ def _write_todo_file(plugin_dir: Path, safe_name: str, items: list[dict]) -> Pat
         "Auto-generated checklist verifying the AI-generated plugin works.",
         "Each task is verified by the adapter worker; failures trigger a fix attempt.",
         "",
+        "⚠ THE BAR IS THE SMOKE TEST. Compile / import / exports / ToolDef-shape",
+        "checks are necessary but NOT sufficient — they only prove the file is",
+        "syntactically a Python module that exports something callable. They do",
+        "NOT prove the wrapper passes the right shapes to upstream functions.",
+        "If a smoke test fails after the syntactic checks pass, the bug is almost",
+        "always a TYPE-SHAPE mismatch (e.g. passing wrapper objects where the",
+        "function expected raw dicts). Re-read the source code before guessing.",
+        "",
     ]
     for item in items:
         lines.append(f"- [ ] {item['title']}")

{dulus-0.2.23 → dulus-0.2.25}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dulus"
-version = "0.2.23"
+version = "0.2.25"
 description = "Spanish-first multi-provider AI CLI — 14 NVIDIA models free, Mesa Redonda, voice, TTS, RTK token reducer, MemPalace"
 readme = "README.md"
 requires-python = ">=3.11"

{dulus-0.2.23 → dulus-0.2.25}/skill/clawhub.py

@@ -172,9 +172,14 @@ _AWESOME_EXCLUDE_REMOTE = {
 }
 
 
-def _fetch_awesome_remote() -> list[dict]:
-    """Hit the GitHub tree API + raw URLs to build an awesome skills catalog.
-    Returns [] on any network/parse error so callers can fall back gracefully.
+def _fetch_awesome_remote(with_descriptions: bool = False) -> list[dict]:
+    """Hit the GitHub tree API to list awesome skills.
+
+    Default (with_descriptions=False): ONE API call, instant, no descriptions.
+    Returns 235 entries with name + url ready in <1s.
+
+    with_descriptions=True: also pulls each SKILL.md's frontmatter via
+    raw.githubusercontent.com — done with a thread pool so it stays under ~5s.
     """
     import time
     tree_url = (
@@ -199,6 +204,7 @@ def _fetch_awesome_remote() -> list[dict]:
             continue
         skill_paths.append(path)
 
+    # Build the skill list from paths alone — instant, no per-file fetch.
     skills = []
     for path in skill_paths:
         rel_dir = "/".join(path.split("/")[:-1])
@@ -207,26 +213,43 @@ def _fetch_awesome_remote() -> list[dict]:
             f"https://raw.githubusercontent.com/{_AWESOME_REPO}/"
             f"{_AWESOME_BRANCH}/{path}"
         )
-        try:
-            with urllib.request.urlopen(raw_url, timeout=10) as r:
-                raw = r.read().decode("utf-8", errors="ignore")
-        except Exception:
-            continue
-        meta = _parse_frontmatter(raw)
         skills.append({
             "id": f"awesome/{rel_dir}",
             "plugin": "awesome",
             "skill": skill_name,
-            "description": meta.get("description", ""),
+            "description": "",  # filled in below if with_descriptions
             "path": raw_url,
             "source": "awesome-remote",
             "_remote_dir": rel_dir,
         })
 
+    if with_descriptions and skills:
+        # Pull frontmatter in parallel via raw.githubusercontent.com (no
+        # rate limit). 12 workers keeps GitHub happy and 235 fetches done
+        # in 3-5 seconds instead of the original 50-120 seconds.
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+
+        def _fetch_one(s):
+            try:
+                with urllib.request.urlopen(s["path"], timeout=8) as r:
+                    raw = r.read().decode("utf-8", errors="ignore")
+                meta = _parse_frontmatter(raw)
+                s["description"] = meta.get("description", "")
+            except Exception:
+                pass
+            return s
+
+        with ThreadPoolExecutor(max_workers=12) as pool:
+            list(pool.map(_fetch_one, skills))
+
     _AWESOME_CACHE.parent.mkdir(parents=True, exist_ok=True)
     try:
         _AWESOME_CACHE.write_text(
-            json.dumps({"fetched_at": time.time(), "skills": skills}, indent=2),
+            json.dumps({
+                "fetched_at": time.time(),
+                "with_descriptions": with_descriptions,
+                "skills": skills,
+            }, indent=2),
             encoding="utf-8",
         )
     except Exception:
@@ -234,21 +257,26 @@ def _fetch_awesome_remote() -> list[dict]:
     return skills
 
 
-def list_awesome_remote(query: Optional[str] = None, force_refresh: bool = False) -> list[dict]:
-    """Return the awesome-skills catalog (cached). Falls through to live fetch
-    when cache is missing or older than 24h.
+def list_awesome_remote(query: Optional[str] = None, force_refresh: bool = False, with_descriptions: bool = False) -> list[dict]:
+    """Return the awesome-skills catalog (cached).
+
+    Default: one GitHub tree call (~1s, no descriptions), cached 24h.
+    with_descriptions=True: also fetches each SKILL.md frontmatter in parallel.
     """
     import time
     skills: list[dict] = []
+    cache_has_descriptions = False
     if not force_refresh and _AWESOME_CACHE.exists():
         try:
             data = json.loads(_AWESOME_CACHE.read_text(encoding="utf-8"))
             if time.time() - float(data.get("fetched_at", 0)) < _AWESOME_TTL_SEC:
                 skills = data.get("skills", [])
+                cache_has_descriptions = bool(data.get("with_descriptions"))
         except Exception:
             skills = []
-    if not skills:
-        skills = _fetch_awesome_remote()
+    # Refetch if no cache, or if user wants descriptions but cache doesn't have them.
+    if not skills or (with_descriptions and not cache_has_descriptions):
+        skills = _fetch_awesome_remote(with_descriptions=with_descriptions)
 
     if query:
         q = query.lower()