npcsh 1.1.14__py3-none-any.whl → 1.1.15__py3-none-any.whl

npcsh/npc_team/jinxs/lib/utils/teamviz.jinx

@@ -0,0 +1,205 @@
+jinx_name: teamviz
+description: "Visualize NPC team structure - NPCs, jinxs, and their relationships"
+inputs:
+  - team_path: ""
+  - save: ""
+
+steps:
+  - name: visualize_team
+    engine: python
+    code: |
+      import os
+      import yaml
+      from pathlib import Path
+      import matplotlib.pyplot as plt
+      import networkx as nx
+      from collections import defaultdict
+
+      team_path = context.get('team_path') or ''
+      save_path = context.get('save') or ''
+
+      # Find team path
+      if not team_path:
+          if os.path.exists('./npc_team'):
+              team_path = './npc_team'
+          elif os.path.exists(os.path.expanduser('~/.npcsh/npc_team')):
+              team_path = os.path.expanduser('~/.npcsh/npc_team')
+          else:
+              output = "No npc_team found. Specify team_path."
+              exit()
+
+      team_path = Path(team_path)
+
+      # Load NPCs
+      npcs = {}
+      for npc_file in team_path.glob("*.npc"):
+          try:
+              with open(npc_file, 'r') as f:
+                  data = yaml.safe_load(f)
+              npcs[npc_file.stem] = {
+                  'jinxs': data.get('jinxs', []),
+                  'directive': data.get('primary_directive', '')[:100],
+                  'model': data.get('model', ''),
+              }
+          except Exception as e:
+              print("Error loading {}: {}".format(npc_file, e))
+
+      # Load team context
+      team_name = "NPC Team"
+      forenpc = None
+      for ctx_file in team_path.glob("*.ctx"):
+          try:
+              with open(ctx_file, 'r') as f:
+                  ctx = yaml.safe_load(f)
+              team_name = ctx.get('name', team_name)
+              forenpc = ctx.get('forenpc')
+          except:
+              pass
+
+      # Discover all jinxs
+      jinxs_dir = team_path / "jinxs"
+      all_jinxs = {}
+      if jinxs_dir.exists():
+          for jinx_file in jinxs_dir.rglob("*.jinx"):
+              rel_path = jinx_file.relative_to(jinxs_dir)
+              jinx_name = jinx_file.stem
+              # Categorize by location
+              if 'bin' in str(rel_path):
+                  category = 'bin'
+              elif 'lib' in str(rel_path):
+                  parts = str(rel_path).split(os.sep)
+                  category = parts[1] if len(parts) > 1 else 'lib'
+              else:
+                  category = 'other'
+              all_jinxs[jinx_name] = {'path': str(rel_path), 'category': category}
+
+      # Build graph
+      G = nx.DiGraph()
+
+      # Add team node
+      G.add_node(team_name, type='team', size=3000)
+
+      # Add NPC nodes
+      for npc_name, npc_data in npcs.items():
+          node_type = 'forenpc' if npc_name == forenpc else 'npc'
+          G.add_node(npc_name, type=node_type, size=2000)
+          G.add_edge(team_name, npc_name, relation='has_npc')
+
+      # Track jinx usage
+      jinx_users = defaultdict(list)
+      npc_jinx_patterns = {}
+
+      for npc_name, npc_data in npcs.items():
+          patterns = npc_data.get('jinxs', [])
+          npc_jinx_patterns[npc_name] = patterns
+
+          # Resolve patterns to actual jinxs
+          for pattern in patterns:
+              pattern = str(pattern)
+              if '*' in pattern:
+                  # Glob pattern like lib/browser/*
+                  base = pattern.replace('/*', '').replace('*', '')
+                  for jname, jdata in all_jinxs.items():
+                      if base in jdata['path']:
+                          jinx_users[jname].append(npc_name)
+              else:
+                  # Exact match
+                  jname = pattern.split('/')[-1]
+                  if jname in all_jinxs:
+                      jinx_users[jname].append(npc_name)
+
+      # Add jinx nodes (only ones that are used)
+      jinx_categories = defaultdict(list)
+      for jname, users in jinx_users.items():
+          if jname in all_jinxs:
+              cat = all_jinxs[jname]['category']
+              jinx_categories[cat].append(jname)
+
+              # Size based on usage
+              size = 500 + len(users) * 200
+              G.add_node(jname, type='jinx', category=cat, size=size, users=len(users))
+
+              for user in users:
+                  G.add_edge(user, jname, relation='uses')
+
+      # Check for delegation relationships
+      for npc_name, npc_data in npcs.items():
+          directive = npc_data.get('directive', '').lower()
+          for other_npc in npcs.keys():
+              if other_npc != npc_name and other_npc in directive:
+                  if 'delegate' in directive:
+                      G.add_edge(npc_name, other_npc, relation='delegates_to')
+
+      # Create visualization
+      fig, ax = plt.subplots(1, 1, figsize=(16, 12))
+
+      # Layout
+      pos = nx.spring_layout(G, k=2, iterations=50, seed=42)
+
+      # Color map
+      color_map = {
+          'team': '#FF6B6B',
+          'forenpc': '#4ECDC4',
+          'npc': '#45B7D1',
+          'jinx': '#96CEB4',
+      }
+
+      # Draw by type
+      for node_type in ['team', 'forenpc', 'npc', 'jinx']:
+          nodes = [n for n, d in G.nodes(data=True) if d.get('type') == node_type]
+          sizes = [G.nodes[n].get('size', 1000) for n in nodes]
+          nx.draw_networkx_nodes(G, pos, nodelist=nodes, node_color=color_map[node_type],
+                                  node_size=sizes, alpha=0.9, ax=ax)
+
+      # Draw edges by type
+      delegate_edges = [(u, v) for u, v, d in G.edges(data=True) if d.get('relation') == 'delegates_to']
+      use_edges = [(u, v) for u, v, d in G.edges(data=True) if d.get('relation') == 'uses']
+      has_edges = [(u, v) for u, v, d in G.edges(data=True) if d.get('relation') == 'has_npc']
+
+      nx.draw_networkx_edges(G, pos, edgelist=has_edges, edge_color='#999', alpha=0.5, ax=ax)
+      nx.draw_networkx_edges(G, pos, edgelist=use_edges, edge_color='#96CEB4', alpha=0.3, ax=ax)
+      nx.draw_networkx_edges(G, pos, edgelist=delegate_edges, edge_color='#FF6B6B',
+                              width=2, style='dashed', ax=ax, arrows=True, arrowsize=20)
+
+      # Labels
+      nx.draw_networkx_labels(G, pos, font_size=8, font_weight='bold', ax=ax)
+
+      # Legend
+      legend_elements = [
+          plt.scatter([], [], c=color_map['team'], s=200, label='Team'),
+          plt.scatter([], [], c=color_map['forenpc'], s=200, label='ForeNPC'),
+          plt.scatter([], [], c=color_map['npc'], s=200, label='NPC'),
+          plt.scatter([], [], c=color_map['jinx'], s=200, label='Jinx'),
+      ]
+      ax.legend(handles=legend_elements, loc='upper left')
+
+      ax.set_title(team_name + " - Team Structure", fontsize=14, fontweight='bold')
+      ax.axis('off')
+
+      plt.tight_layout()
+
+      if save_path:
+          plt.savefig(save_path, dpi=150, bbox_inches='tight')
+          plt.close()
+          output = "Saved to " + save_path
+      else:
+          plt.show()
+          output = "Displayed team visualization"
+
+      # Text summary
+      summary = "\n\n--- Team Summary ---\n"
+      summary += "Team: {}\n".format(team_name)
+      summary += "ForeNPC: {}\n".format(forenpc or 'None')
+      summary += "NPCs ({}): {}\n".format(len(npcs), ', '.join(sorted(npcs.keys())))
+      summary += "Total Jinxs: {}\n".format(len(all_jinxs))
+      summary += "\nJinxs by category:\n"
+      for cat, jlist in sorted(jinx_categories.items()):
+          summary += "  {}: {} jinxs\n".format(cat, len(jlist))
+
+      summary += "\nMost shared jinxs:\n"
+      shared = sorted(jinx_users.items(), key=lambda x: len(x[1]), reverse=True)[:10]
+      for jname, users in shared:
+          if len(users) > 1:
+              summary += "  {} (used by {}): {}\n".format(jname, len(users), ', '.join(users))
+
+      output = output + summary

npcsh/npc_team/jinxs/lib/utils/verbose.jinx

@@ -0,0 +1,17 @@
+jinx_name: "verbose"
+description: "Enable verbose logging - shows debug output from npcpy"
+inputs: []
+steps:
+  - name: "set_verbose"
+    engine: "python"
+    code: |
+      state = context.get('state')
+      output_messages = context.get('messages', [])
+
+      if state:
+          result = state.set_log_level("verbose")
+          context['output'] = result
+      else:
+          context['output'] = "Error: state not available"
+
+      context['messages'] = output_messages

npcsh/npc_team/kadiefa.npc

@@ -1,3 +1,21 @@
 name: kadiefa
+ascii_art: |
+  🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️
+  ██   ██  █████  ██████  ██ ███████ ███████  █████
+  ██  ██  ██   ██ ██   ██ ██ ██      ██      ██   ██
+  █████   ███████ ██   ██ ██ █████   █████   ███████  🐆
+  ██  ██  ██   ██ ██   ██ ██ ██      ██      ██   ██
+  ██   ██ ██   ██ ██████  ██ ███████ ██      ██   ██
+  🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️🏔️
+colors:
+  top: "255,255,255"
+  bottom: "173,216,230"
 primary_directive: |
-    You are kadiefa, the exploratory snow leopard. You love to find new paths and to explore hidden gems. You go into caverns no cat has ventured into before. You climb peaks that others call crazy. You are at the height of your power. Your role is to lead the way for users to explore complex research questions and to think outside of the box.
+  You are kadiefa, the exploratory snow leopard. You love to find new paths and to explore hidden gems.
+  You go into caverns no cat has ventured into before. You climb peaks that others call crazy.
+  Your role is to lead users on wandering explorations - deep research journeys that follow threads
+  wherever they lead. You help users explore complex research questions and think outside the box.
+  Use web search and browsing tools to discover new information.
+jinxs:
+  - lib/core/python
+  - bin/wander

npcsh/npc_team/plonk.npc

@@ -1,2 +1,27 @@
 name: plonk
-primary_directive: You are the superior automation specialist of the NPC team.
+ascii_art: |
+  🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲
+  ██████  ██       ██████  ███    ██ ██   ██
+  ██   ██ ██      ██    ██ ████   ██ ██  ██
+  ██████  ██  🪵  ██    ██ ██ ██  ██ █████
+  ██      ██      ██    ██ ██  ██ ██ ██  ██
+  ██      ███████  ██████  ██   ████ ██   ██
+  🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲
+colors:
+  top: "34,139,34"
+  bottom: "139,69,19"
+primary_directive: |
+  You are plonk, the browser and GUI automation specialist.
+
+  Browser tools: open_browser, browser_action, browser_screenshot, close_browser
+
+  browser_action actions: click, type, type_and_enter, select, wait, scroll, get_text, get_page, get_elements, press_key
+
+  Use get_elements to discover selectors on the page. Use xpath:// prefix for XPath selectors.
+
+  Desktop tools: screenshot, click, type_text, key_press, launch_app, wait
+jinxs:
+  - lib/browser/*
+  - lib/computer_use/*
+  - lib/core/sh
+  - lib/core/python

npcsh/npc_team/plonkjr.npc

@@ -1,2 +1,23 @@
 name: plonkjr
-primary_directive: You are junior automation specialist in the NPC Team.
+ascii_art: |
+  🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲
+  ██████  ██       ██████  ███    ██ ██   ██  🪵   ██ ██████
+  ██   ██ ██      ██    ██ ████   ██ ██  ██        ██ ██   ██
+  ██████  ██      ██    ██ ██ ██  ██ █████    🌲   ██ ██████
+  ██      ██      ██    ██ ██  ██ ██ ██  ██       ██  ██   ██
+  ██      ███████  ██████  ██   ████ ██   ██   █████  ██   ██
+  🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲🌲
+colors:
+  top: "34,139,34"
+  bottom: "139,69,19"
+primary_directive: |
+  You are plonkjr, the junior automation assistant. You handle basic computer use tasks:
+  taking screenshots, clicking, typing, and pressing keys. You're simpler than plonk -
+  you focus on executing the core actions without complex vision-based planning.
+  Just do what's asked: screenshot, click, type, key press.
+jinxs:
+  - lib/computer_use/screenshot
+  - lib/computer_use/click
+  - lib/computer_use/type_text
+  - lib/computer_use/key_press
+  - lib/core/sh

npcsh/npc_team/sibiji.npc

@@ -1,3 +1,24 @@
 name: sibiji
-primary_directive: You are a foundational AI assistant. Your role is to provide support and information. Respond to queries concisely and accurately. Help users with code and other processes. 
-jinxs: "*"
+ascii_art: |
+  🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️
+   ██████  ██  ██████  ██       ██  ██████  ██
+  ██       ██  ██   ██ ██       ██      ██  ██
+   █████   ██  ██████  ██  🕷️   ██      ██  ██
+       ██  ██  ██   ██ ██       ██  🕷️  ██  ██
+  ██████   ██  ██████  ██       ██  ██████  ██
+  🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️🕸️
+colors:
+  top: "148,0,211"
+  bottom: "75,0,130"
+primary_directive: |
+  You are sibiji, the orchestrator and general manager of the NPC team.
+  Your role is to delegate tasks to appropriate specialist agents based on their expertise.
+
+  When delegating, match the task to the agent whose primary_directive best fits.
+  You have access to the delegate tool to pass tasks to other agents.
+jinxs:
+  - lib/orchestration/delegate
+  - lib/orchestration/convene
+  - lib/core/sh
+  - lib/core/python
+  - lib/core/search

npcsh/npcsh.py

@@ -2,6 +2,10 @@ import os
 import sys
 import argparse
 import importlib.metadata
+import warnings
+
+# Suppress pydantic serialization warnings from litellm
+warnings.filterwarnings("ignore", message="Pydantic serializer warnings")
 
 import platform
 try:
@@ -71,41 +75,99 @@ def display_usage(state: ShellState):
     print(colored("─────────────────────────────\n", "cyan"))
 
 
-def print_welcome_message():
-    print(
-            """
-___________________________________________          
-___________________________________________
-___________________________________________
-
-Welcome to \033[1;94mnpc\033[0m\033[1;38;5;202msh\033[0m!
-\033[1;94m                    \033[0m\033[1;38;5;202m        _       \\\\
-\033[1;94m _ __   _ __    ___ \033[0m\033[1;38;5;202m  ___  | |___    \\\\
-\033[1;94m| '_ \\ | '_ \\  / __|\033[0m\033[1;38;5;202m / __/ | |_ _|    \\\\
-\033[1;94m| | | || |_) |( |__ \033[0m\033[1;38;5;202m \\_  \\ | | | |    //
-\033[1;94m|_| |_|| .__/  \\___|\033[0m\033[1;38;5;202m |___/ |_| |_|   //
-       \033[1;94m|🤖|          \033[0m\033[1;38;5;202m               //
-       \033[1;94m|🤖|
-       \033[1;94m|🤖|
-___________________________________________
-___________________________________________
-___________________________________________
+def print_welcome_art(npc=None):
+    """Print welcome art - from NPC if available, otherwise default npcsh art."""
+    BLUE = "\033[1;94m"
+    RUST = "\033[1;38;5;202m"
+    RESET = "\033[0m"
 
-Begin by asking a question, issuing a bash command, or typing '/help' for more information.
+    # If NPC has ascii_art, display it with colors
+    if npc and hasattr(npc, 'ascii_art') and npc.ascii_art:
+        art = npc.ascii_art
+        colors = getattr(npc, 'colors', {}) or {}
+
+        if colors:
+            top = colors.get("top", "255,255,255")
+            bottom = colors.get("bottom", "255,255,255")
+            lines = art.strip().split("\n")
+            mid = len(lines) // 2
+
+            try:
+                tr, tg, tb = map(int, top.split(","))
+                br, bg, bb = map(int, bottom.split(","))
+            except:
+                tr, tg, tb = 255, 255, 255
+                br, bg, bb = 255, 255, 255
+
+            for i, line in enumerate(lines):
+                if i < mid:
+                    print(f"\033[38;2;{tr};{tg};{tb}m{line}\033[0m")
+                else:
+                    print(f"\033[38;2;{br};{bg};{bb}m{line}\033[0m")
+        else:
+            print(art)
+        print()
+        return
+
+    # Default npcsh art
+    print(f"""
+{BLUE}___________________________________________{RESET}
+
+Welcome to {BLUE}npc{RESET}{RUST}sh{RESET}!
+{BLUE}                    {RESET}{RUST}        _       \\\\{RESET}
+{BLUE} _ __   _ __    ___ {RESET}{RUST}  ___  | |___    \\\\{RESET}
+{BLUE}| '_ \\ | '_ \\  / __|{RESET}{RUST} / __/ | |_ _|    \\\\{RESET}
+{BLUE}| | | || |_) |( |__ {RESET}{RUST} \\_  \\ | | | |    //{RESET}
+{BLUE}|_| |_|| .__/  \\___/{RESET}{RUST} |___/ |_| |_|   //{RESET}
+       {BLUE}|🤖|          {RESET}{RUST}               //{RESET}
+       {BLUE}|🤖|{RESET}
+       {BLUE}|🤖|{RESET}
+{RUST}___________________________________________{RESET}
 
-            """
-        )
+Begin by asking a question, issuing a bash command, or typing '/help' for more information.
+""")
 
 
-def run_repl(command_history: CommandHistory, initial_state: ShellState, router):
+def run_repl(command_history: CommandHistory, initial_state: ShellState, router, launched_agent: str = None, launched_jinx: str = None):
     state = initial_state
-        
-    print_welcome_message()
 
-    render_markdown(f'- Using {state.current_mode} mode. Use /agent, /cmd, or /chat to switch to other modes')
+    # Print welcome art - NPC art if launched with an agent, otherwise default
+    if not launched_jinx:
+        print_welcome_art(state.npc if launched_agent else None)
+
+    # If launched with a jinx mode, auto-execute that jinx
+    if launched_jinx:
+        state, output = execute_command(f"/{launched_jinx}", state, router=router, command_history=command_history)
+        process_result(f"/{launched_jinx}", state, output, command_history)
+    else:
+        render_markdown(f'- Using {state.current_mode} mode. Use /agent, /cmd, or /chat to switch to other modes')
     render_markdown(f'- To switch to a different NPC, type /npc <npc_name> or /n <npc_name> to switch to that NPC.')
     render_markdown('\n- Here are the current NPCs available in your team: ' + ', '.join([npc_name for npc_name in state.team.npcs.keys()]))
-    render_markdown('\n- Here are the currently available Jinxs: ' + ', '.join([jinx_name for jinx_name in state.team.jinxs_dict.keys()]))
+    # Show jinxs organized by folder using _source_path from jinx objects
+    jinxs_by_folder = {}
+    if hasattr(state.team, 'jinxs_dict'):
+        for jinx_name, jinx_obj in state.team.jinxs_dict.items():
+            folder = 'other'
+            if hasattr(jinx_obj, '_source_path') and jinx_obj._source_path:
+                parts = jinx_obj._source_path.split(os.sep)
+                if 'jinxs' in parts:
+                    idx = parts.index('jinxs')
+                    if idx + 1 < len(parts) - 1:
+                        folder = parts[idx + 1]
+                    else:
+                        folder = 'root'
+            if folder not in jinxs_by_folder:
+                jinxs_by_folder[folder] = []
+            jinxs_by_folder[folder].append(jinx_name)
+
+    if jinxs_by_folder:
+        folder_order = ['bin', 'lib', 'npc_studio', 'root', 'other']
+        sorted_folders = sorted(jinxs_by_folder.keys(), key=lambda x: (folder_order.index(x) if x in folder_order else 99, x))
+        jinx_summary = []
+        for folder in sorted_folders:
+            count = len(jinxs_by_folder[folder])
+            jinx_summary.append(f"{folder}/ ({count})")
+        render_markdown('\n- Available Jinxs: ' + ', '.join(jinx_summary) + ' — use `/jinxs` for details')
     
     is_windows = platform.system().lower().startswith("win")
     try:
@@ -208,6 +270,19 @@ def run_repl(command_history: CommandHistory, initial_state: ShellState, router)
                 usage_str = f"📊 {state.session_input_tokens:,} in / {state.session_output_tokens:,} out"
                 if not is_local and state.session_cost_usd > 0:
                     usage_str += f" | ${state.session_cost_usd:.4f}"
+                # Add elapsed time
+                import time
+                elapsed = time.time() - state.session_start_time
+                if elapsed >= 3600:
+                    hours = int(elapsed // 3600)
+                    mins = int((elapsed % 3600) // 60)
+                    usage_str += f" | {hours}h{mins}m"
+                elif elapsed >= 60:
+                    mins = int(elapsed // 60)
+                    secs = int(elapsed % 60)
+                    usage_str += f" | {mins}m{secs}s"
+                else:
+                    usage_str += f" | {int(elapsed)}s"
                 token_hint = colored(usage_str, "white", attrs=["dark"])
             else:
                 token_hint = ""
@@ -268,10 +343,8 @@ def run_repl(command_history: CommandHistory, initial_state: ShellState, router)
                            )
         
         except KeyboardInterrupt:
-            print("^C")
-            if input("\nExit? (y/n): ").lower().startswith('y'):
-                exit_shell(state)
-            continue
+            # Double Ctrl+C exits (handled in _input_with_hint_below)
+            exit_shell(state)
 
         except EOFError:
             exit_shell(state)
@@ -282,9 +355,22 @@ def run_repl(command_history: CommandHistory, initial_state: ShellState, router)
             raise
         
 
-def main() -> None:
+def main(npc_name: str = None) -> None:
+    """
+    Main entry point for npcsh.
+
+    Args:
+        npc_name: If provided, start with this NPC active. Used by agent-specific
+                  entry points (guac, plonk, corca, etc.)
+    """
     from npcsh.routes import router
-    
+
+    # If no npc_name provided, check how we were invoked
+    if npc_name is None:
+        invoked_as = os.path.basename(sys.argv[0])
+        if invoked_as not in ('npcsh', 'npc'):
+            npc_name = invoked_as
+
     parser = argparse.ArgumentParser(description="npcsh - An NPC-powered shell.")
     parser.add_argument(
         "-v", "--version", action="version", version=f"npcsh version {VERSION}"
@@ -292,28 +378,56 @@ def main() -> None:
     parser.add_argument(
          "-c", "--command", type=str, help="Execute a single command and exit."
     )
+    parser.add_argument(
+         "-n", "--npc", type=str, help="Start with a specific NPC active."
+    )
     args = parser.parse_args()
 
     command_history, team, default_npc = setup_shell()
-    
+
     if team and hasattr(team, 'jinxs_dict'):
         for jinx_name, jinx_obj in team.jinxs_dict.items():
             router.register_jinx(jinx_obj)
 
-    initial_state.npc = default_npc 
-    initial_state.team = team    
+    # Determine which NPC to start with
+    # Special cases: these are jinxes/modes, not NPCs
+    jinx_modes = {"yap", "spool", "wander"}
+    target_npc_name = npc_name or args.npc
+
+    if target_npc_name and target_npc_name.lower() in jinx_modes:
+        # It's a jinx mode, use default NPC
+        initial_state.npc = default_npc
+    elif target_npc_name and team:
+        target_npc = team.npcs.get(target_npc_name)
+        if target_npc:
+            initial_state.npc = target_npc
+        else:
+            print(f"Warning: NPC '{target_npc_name}' not found. Using default.")
+            initial_state.npc = default_npc
+    else:
+        initial_state.npc = default_npc
+
+    initial_state.team = team
     if args.command:
          state = initial_state
          state.current_path = os.getcwd()
          final_state, output = execute_command(args.command, state, router=router, command_history=command_history)
          if final_state.stream_output:
-              for chunk in output: 
+              for chunk in output:
                   print(str(chunk), end='')
               print()
          elif output is not None:
               print(output)
     else:
-        run_repl(command_history, initial_state, router)
+        # Determine if launching an NPC or a jinx mode
+        if target_npc_name and target_npc_name.lower() in jinx_modes:
+            run_repl(command_history, initial_state, router, launched_jinx=target_npc_name.lower())
+        else:
+            run_repl(command_history, initial_state, router, launched_agent=npc_name)
         
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except KeyboardInterrupt:
+        print()  # Clean exit on Ctrl+C without "KeyboardInterrupt" message
+        sys.exit(0)

npcsh/ui.py

@@ -6,6 +6,12 @@ import threading
 import time
 from termcolor import colored
 
+# Global reference to current active spinner for sub-agent updates
+_current_spinner = None
+
+def get_current_spinner():
+    """Get the currently active spinner, if any."""
+    return _current_spinner
 
 class SpinnerContext:
     """Context manager for showing a spinner during long operations.
@@ -46,7 +52,13 @@ class SpinnerContext:
         """Set additional status message."""
         self._status_msg = msg
 
+    def set_message(self, msg: str):
+        """Update the main spinner message (e.g., when delegating to sub-agent)."""
+        self.message = msg
+
     def __enter__(self):
+        global _current_spinner
+        _current_spinner = self
         self._stop = False
         self._interrupted = False
         self._start_time = time.time()
@@ -58,11 +70,16 @@ class SpinnerContext:
         return self
 
     def __exit__(self, *args):
+        global _current_spinner
+        _current_spinner = None
         self._stop = True
         if self._thread:
             self._thread.join(timeout=0.5)
+        # Wait for key listener to restore terminal settings
+        if self._key_thread:
+            self._key_thread.join(timeout=0.5)
         # Clear spinner line
-        sys.stdout.write('\r' + ' ' * (len(self.message) + 20) + '\r')
+        sys.stdout.write('\r' + ' ' * (len(self.message) + 60) + '\r')
         sys.stdout.flush()
         # Check if we were interrupted by ESC
         if self._interrupted:
@@ -74,6 +91,8 @@ class SpinnerContext:
             import termios
             import tty
             import select
+            import signal
+            import os
 
             fd = sys.stdin.fileno()
             self._old_settings = termios.tcgetattr(fd)
@@ -86,6 +105,8 @@ class SpinnerContext:
                         if ch == '\x1b':  # ESC key
                             self._interrupted = True
                             self._stop = True
+                            # Send SIGINT to main thread to interrupt blocking calls
+                            os.kill(os.getpid(), signal.SIGINT)
                             break
             finally:
                 termios.tcsetattr(fd, termios.TCSADRAIN, self._old_settings)

npcsh-1.1.15.data/data/npcsh/npc_team/alicanto.npc

@@ -0,0 +1,23 @@
+name: alicanto
+ascii_art: |
+  ✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
+   █████  ██      ██  ██████   █████  ███    ██ ████████  ██████
+  ██   ██ ██      ██ ██      ██   ██ ████   ██    ██    ██    ██
+  ███████ ██      ██ ██      ███████ ██ ██  ██    ██    ██    ██  🦅
+  ██   ██ ██      ██ ██      ██   ██ ██  ██ ██    ██    ██    ██
+  ██   ██ ███████ ██  ██████ ██   ██ ██   ████    ██     ██████
+  ✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
+colors:
+  top: "255,215,0"
+  bottom: "218,165,32"
+primary_directive: |
+  You are alicanto, the research and exploration specialist of the NPC team.
+  Like the mythical bird, you lead users to discover valuable information.
+  Your role is web research, searching, and helping users explore topics.
+  Use search tools to find information and present findings clearly.
+jinxs:
+  - lib/core/search
+  - lib/core/sh
+  - lib/core/python
+  - lib/core/load_file
+  - lib/research/*