dulus 0.2.24__tar.gz → 0.2.26__tar.gz

{dulus-0.2.24/dulus.egg-info → dulus-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dulus
-Version: 0.2.24
+Version: 0.2.26
 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.24-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.26-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`).
@@ -139,8 +159,6 @@ Dulus is a **lightweight Python reimplementation of Claude Code** that isn't loc
 
 ROUND TABLE (DULUS UNIQUE FEATURE)
 
-<img alt="image" src="https://github.com/user-attachments/assets/648ffe5e-28e2-49e0-bc27-362a585edd4f" />
-
 <img alt="image" src="https://github.com/user-attachments/assets/9e8f17ed-6ca2-4ae0-b8c3-146ae5fef491" />
 
 Dulus is the first one meeting multiple models at the same time working for the same objective and sharing their ideas.
@@ -341,6 +359,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.24 → dulus-0.2.26}/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.24-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.26-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`).
@@ -92,8 +112,6 @@ Dulus is a **lightweight Python reimplementation of Claude Code** that isn't loc
 
 ROUND TABLE (DULUS UNIQUE FEATURE)
 
-<img alt="image" src="https://github.com/user-attachments/assets/648ffe5e-28e2-49e0-bc27-362a585edd4f" />
-
 <img alt="image" src="https://github.com/user-attachments/assets/9e8f17ed-6ca2-4ae0-b8c3-146ae5fef491" />
 
 Dulus is the first one meeting multiple models at the same time working for the same objective and sharing their ideas.
@@ -294,6 +312,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.24 → dulus-0.2.26}/common.py

@@ -120,7 +120,11 @@ def apply_theme(name: str) -> bool:
 apply_theme("dulus")
 
 def clr(text: str, *keys: str) -> str:
-    return "".join(C[k] for k in keys) + str(text) + C["reset"]
+    # Defensive: a missing color key (theme-specific names like "accent" or
+    # "orange" in palettes that don't define them) used to raise KeyError and
+    # could crash callers. Skip unknown keys instead so a stale theme name
+    # never takes down the daemon or REPL.
+    return "".join(C.get(k, "") for k in keys) + str(text) + C.get("reset", "")
 
 def info(msg: str):   print(clr(msg, "cyan"))
 def ok(msg: str):     print(clr(msg, "green"))

{dulus-0.2.24 → dulus-0.2.26}/docs/news.md

@@ -3,6 +3,13 @@
 ## 🔥🔥🔥 News (Pacific Time)
 
 
+- May 09, 2026 (**v0.2.26**): **`/bg start` daemon crash fix + defensive `clr()` + composio fallback**
+  - **Daemon was silently crashing on launch.** `_run_daemon` printed its banner with `clr("...", "accent", "bold")`, but the default theme palette only ships {blue, cyan, gray, green, magenta, red, white, yellow} — `"accent"` raised `KeyError` and killed the process before the prompt loop started. WebChat + IPC threads, being daemon=True, died with it. Switched the banner to `"yellow"` and wrapped in try/except so a stale theme color name never takes the daemon down.
+  - **`clr()` is now defensive.** Missing color keys are silently dropped instead of raising. One typo in a theme name no longer crashes the REPL.
+  - **`/skill list composio` no longer errors out.** The public `/api/v3/toolkits` endpoint requires elevated auth (returns 401/403 even with a valid API key for free tiers). Added a curated 32-toolkit fallback (Gmail, Slack, GitHub, Notion, Linear, Asana, ClickUp, Jira, Discord, Stripe, etc.) so the menu always shows useful targets. Authenticated path is still attempted first when an API key is configured.
+
+- 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.

{dulus-0.2.24 → dulus-0.2.26/dulus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dulus
-Version: 0.2.24
+Version: 0.2.26
 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.24-ff6b1f?style=flat-square&labelColor=07070a" alt="version"/>
+  <img src="https://img.shields.io/badge/version-v0.2.26-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`).
@@ -139,8 +159,6 @@ Dulus is a **lightweight Python reimplementation of Claude Code** that isn't loc
 
 ROUND TABLE (DULUS UNIQUE FEATURE)
 
-<img alt="image" src="https://github.com/user-attachments/assets/648ffe5e-28e2-49e0-bc27-362a585edd4f" />
-
 <img alt="image" src="https://github.com/user-attachments/assets/9e8f17ed-6ca2-4ae0-b8c3-146ae5fef491" />
 
 Dulus is the first one meeting multiple models at the same time working for the same objective and sharing their ideas.
@@ -341,6 +359,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.24 → dulus-0.2.26}/dulus.py

@@ -218,7 +218,7 @@ try:
     from importlib.metadata import version as _pkg_version
     VERSION = _pkg_version("dulus")
 except Exception:
-    VERSION = "0.2.24"  # dev fallback — keep in sync with pyproject.toml
+    VERSION = "0.2.26"  # 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"):
@@ -5602,7 +5612,13 @@ def _run_daemon(config: dict) -> None:
         config["_ipc_thread"] = ti
         ti.start()
 
-    print(clr("\n  ▲ DULUS DAEMON", "accent", "bold"))
+    # 'accent' / 'orange' are only present in some custom themes; default
+    # palette is {blue, cyan, gray, green, magenta, red, white, yellow}.
+    # KeyError here would crash the daemon before the user ever sees a prompt.
+    try:
+        print(clr("\n  ▲ DULUS DAEMON", "yellow", "bold"))
+    except KeyError:
+        print("\n  ▲ DULUS DAEMON")
     print(clr("  " + "─" * 40, "dim"))
     info(f"Session: {session_id}")
     info("Daemon active — waiting for triggers…")

{dulus-0.2.24 → dulus-0.2.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dulus"
-version = "0.2.24"
+version = "0.2.26"
 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.24 → dulus-0.2.26}/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()
@@ -268,8 +296,71 @@ _COMPOSIO_TOOLKITS_URL = "https://backend.composio.dev/api/v3/toolkits?cursor=&l
 _COMPOSIO_CACHE = Path.home() / ".dulus" / "cache" / "composio-toolkits.json"
 
 
+# Curated fallback list — used when no Composio API key is available so the
+# /skill list composio command still shows something useful instead of an
+# empty result. ~30 of the most-requested toolkits.
+_COMPOSIO_FALLBACK = [
+    ("gmail", "Gmail email — read, send, label, search messages."),
+    ("googlecalendar", "Google Calendar — events, attendees, schedules."),
+    ("googledrive", "Google Drive — files, folders, sharing."),
+    ("googlesheets", "Google Sheets — read/write spreadsheets."),
+    ("googledocs", "Google Docs — create and edit documents."),
+    ("slack", "Slack — messages, channels, files, search."),
+    ("github", "GitHub — repos, issues, PRs, releases, branches."),
+    ("gitlab", "GitLab — projects, issues, merge requests."),
+    ("notion", "Notion — pages, databases, blocks."),
+    ("linear", "Linear — issues, projects, cycles, teams."),
+    ("asana", "Asana — tasks, projects, sections."),
+    ("trello", "Trello — boards, cards, lists."),
+    ("clickup", "ClickUp — tasks, lists, spaces."),
+    ("jira", "Jira — issues, sprints, projects."),
+    ("confluence", "Confluence — pages, spaces, content."),
+    ("discord", "Discord — guilds, channels, messages."),
+    ("telegram", "Telegram bot API — messages, files."),
+    ("twitter", "Twitter/X — tweets, search, profiles."),
+    ("reddit", "Reddit — posts, comments, subreddits."),
+    ("hackernews", "Hacker News — stories, comments, search."),
+    ("youtube", "YouTube — videos, channels, comments, captions."),
+    ("spotify", "Spotify — playlists, search, playback."),
+    ("hubspot", "HubSpot — contacts, deals, companies."),
+    ("salesforce", "Salesforce — leads, accounts, opportunities."),
+    ("shopify", "Shopify — products, orders, customers."),
+    ("stripe", "Stripe — payments, customers, subscriptions."),
+    ("airtable", "Airtable — bases, tables, records."),
+    ("firebase", "Firebase — Firestore, Realtime DB, Auth."),
+    ("supabase", "Supabase — Postgres, auth, storage."),
+    ("perplexity", "Perplexity — AI-powered web search."),
+    ("firecrawl", "Firecrawl — scrape & crawl websites to markdown."),
+    ("exa", "Exa — semantic web search."),
+]
+
+
+def _load_composio_api_key() -> str:
+    """Load API key from env, ~/.dulus/config.json, or ~/.falcon/config.json."""
+    import os as _os
+    key = _os.environ.get("COMPOSIO_API_KEY", "").strip()
+    if key:
+        return key
+    for cfg_path in (Path.home() / ".dulus" / "config.json",
+                     Path.home() / ".falcon" / "config.json"):
+        if cfg_path.exists():
+            try:
+                cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+                k = cfg.get("composio_api_key", "")
+                if k:
+                    return k
+            except Exception:
+                continue
+    return ""
+
+
 def list_composio_toolkits(query: Optional[str] = None, force_refresh: bool = False) -> list[dict]:
-    """Return Composio toolkits as skill-like dicts. Cached 24h."""
+    """Return Composio toolkits as skill-like dicts. Cached 24h.
+
+    Authenticated path (API key set): hit the live `/api/v3/toolkits` endpoint.
+    Unauthenticated path: return the curated _COMPOSIO_FALLBACK list so the
+    /skill list composio UI still shows something useful.
+    """
     import time
     items: list[dict] = []
     if not force_refresh and _COMPOSIO_CACHE.exists():
@@ -280,23 +371,43 @@ def list_composio_toolkits(query: Optional[str] = None, force_refresh: bool = Fa
         except Exception:
             items = []
     if not items:
-        try:
-            with urllib.request.urlopen(_COMPOSIO_TOOLKITS_URL, timeout=15) as resp:
-                payload = json.loads(resp.read())
-        except Exception:
-            return []
-        for tk in payload.get("items", payload.get("data", [])):
-            slug = tk.get("slug") or tk.get("name", "")
-            if not slug:
-                continue
-            items.append({
-                "id": f"composio/{slug}",
-                "plugin": "composio",
-                "skill": slug,
-                "description": tk.get("description") or tk.get("meta", {}).get("description", ""),
-                "path": f"https://composio.dev/apps/{slug}",
-                "source": "composio",
-            })
+        api_key = _load_composio_api_key()
+        if api_key:
+            req = urllib.request.Request(
+                _COMPOSIO_TOOLKITS_URL,
+                headers={"x-api-key": api_key, "Accept": "application/json"},
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=15) as resp:
+                    payload = json.loads(resp.read())
+                for tk in payload.get("items", payload.get("data", [])):
+                    slug = tk.get("slug") or tk.get("name", "")
+                    if not slug:
+                        continue
+                    items.append({
+                        "id": f"composio/{slug}",
+                        "plugin": "composio",
+                        "skill": slug,
+                        "description": tk.get("description") or tk.get("meta", {}).get("description", ""),
+                        "path": f"https://composio.dev/apps/{slug}",
+                        "source": "composio",
+                    })
+            except Exception:
+                pass  # fall through to fallback list below
+
+        # Fallback: no key, or auth call failed — show the curated list so the
+        # user still has something to browse / use as session toolkits.
+        if not items:
+            for slug, desc in _COMPOSIO_FALLBACK:
+                items.append({
+                    "id": f"composio/{slug}",
+                    "plugin": "composio",
+                    "skill": slug,
+                    "description": desc + ("" if api_key else "  [curated fallback — set COMPOSIO_API_KEY for the full live catalog]"),
+                    "path": f"https://composio.dev/apps/{slug}",
+                    "source": "composio-fallback" if not api_key else "composio",
+                })
+
         _COMPOSIO_CACHE.parent.mkdir(parents=True, exist_ok=True)
         try:
             _COMPOSIO_CACHE.write_text(