devduck 0.5.4__py3-none-any.whl → 0.6.0__py3-none-any.whl

devduck/__init__.py

@@ -1,15 +1,20 @@
 #!/usr/bin/env python3
-"""🦆 devduck - self-adapting agent"""
+"""
+🦆 devduck - extreme minimalist self-adapting agent
+one file. self-healing. runtime dependencies. adaptive.
+"""
 import sys
-import threading
+import subprocess
 import os
 import platform
+import socket
 import logging
 import tempfile
-import boto3
+import time
+import warnings
 from pathlib import Path
 from datetime import datetime
-import warnings
+from typing import Dict, Any
 from logging.handlers import RotatingFileHandler
 
 warnings.filterwarnings("ignore", message=".*pkg_resources is deprecated.*")
@@ -21,31 +26,169 @@ os.environ["EDITOR_DISABLE_BACKUP"] = "true"
 
 LOG_DIR = Path(tempfile.gettempdir()) / "devduck" / "logs"
 LOG_DIR.mkdir(parents=True, exist_ok=True)
-LOG_FILE = LOG_DIR / "devduck.log"
 
+LOG_FILE = LOG_DIR / "devduck.log"
 logger = logging.getLogger("devduck")
 logger.setLevel(logging.DEBUG)
-logger.addHandler(
-    RotatingFileHandler(LOG_FILE, maxBytes=10 * 1024 * 1024, backupCount=3)
+
+file_handler = RotatingFileHandler(
+    LOG_FILE, maxBytes=10 * 1024 * 1024, backupCount=3, encoding="utf-8"
+)
+file_handler.setLevel(logging.DEBUG)
+file_formatter = logging.Formatter(
+    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 )
-logger.info("DevDuck initialized")
+file_handler.setFormatter(file_formatter)
+
+console_handler = logging.StreamHandler()
+console_handler.setLevel(logging.WARNING)
+console_formatter = logging.Formatter("🦆 %(levelname)s: %(message)s")
+console_handler.setFormatter(console_formatter)
+
+logger.addHandler(file_handler)
+logger.addHandler(console_handler)
+
+logger.info("DevDuck logging system initialized")
 
 
 def get_own_source_code():
     """Read own source code for self-awareness"""
     try:
         with open(__file__, "r", encoding="utf-8") as f:
-            return f"# devduck/__init__.py\n```python\n{f.read()}\n```"
+            return f"# Source path: {__file__}\n\ndevduck/__init__.py\n```python\n{f.read()}\n```"
     except Exception as e:
         return f"Error reading source: {e}"
 
 
+def view_logs_tool(
+    action: str = "view",
+    lines: int = 100,
+    pattern: str = None,
+) -> Dict[str, Any]:
+    """
+    View and manage DevDuck logs.
+
+    Args:
+        action: Action to perform - "view", "tail", "search", "clear", "stats"
+        lines: Number of lines to show (for view/tail)
+        pattern: Search pattern (for search action)
+
+    Returns:
+        Dict with status and content
+    """
+    try:
+        if action == "view":
+            if not LOG_FILE.exists():
+                return {"status": "success", "content": [{"text": "No logs yet"}]}
+
+            with open(LOG_FILE, "r", encoding="utf-8") as f:
+                all_lines = f.readlines()
+                recent_lines = (
+                    all_lines[-lines:] if len(all_lines) > lines else all_lines
+                )
+                content = "".join(recent_lines)
+
+            return {
+                "status": "success",
+                "content": [
+                    {"text": f"Last {len(recent_lines)} log lines:\n\n{content}"}
+                ],
+            }
+
+        elif action == "tail":
+            if not LOG_FILE.exists():
+                return {"status": "success", "content": [{"text": "No logs yet"}]}
+
+            with open(LOG_FILE, "r", encoding="utf-8") as f:
+                all_lines = f.readlines()
+                tail_lines = all_lines[-50:] if len(all_lines) > 50 else all_lines
+                content = "".join(tail_lines)
+
+            return {
+                "status": "success",
+                "content": [{"text": f"Tail (last 50 lines):\n\n{content}"}],
+            }
+
+        elif action == "search":
+            if not pattern:
+                return {
+                    "status": "error",
+                    "content": [{"text": "pattern parameter required for search"}],
+                }
+
+            if not LOG_FILE.exists():
+                return {"status": "success", "content": [{"text": "No logs yet"}]}
+
+            with open(LOG_FILE, "r", encoding="utf-8") as f:
+                matching_lines = [line for line in f if pattern.lower() in line.lower()]
+
+            if not matching_lines:
+                return {
+                    "status": "success",
+                    "content": [{"text": f"No matches found for pattern: {pattern}"}],
+                }
+
+            content = "".join(matching_lines[-100:])  # Last 100 matches
+            return {
+                "status": "success",
+                "content": [
+                    {
+                        "text": f"Found {len(matching_lines)} matches (showing last 100):\n\n{content}"
+                    }
+                ],
+            }
+
+        elif action == "clear":
+            if LOG_FILE.exists():
+                LOG_FILE.unlink()
+                logger.info("Log file cleared by user")
+            return {
+                "status": "success",
+                "content": [{"text": "Logs cleared successfully"}],
+            }
+
+        elif action == "stats":
+            if not LOG_FILE.exists():
+                return {"status": "success", "content": [{"text": "No logs yet"}]}
+
+            stat = LOG_FILE.stat()
+            size_mb = stat.st_size / (1024 * 1024)
+            modified = datetime.fromtimestamp(stat.st_mtime).strftime(
+                "%Y-%m-%d %H:%M:%S"
+            )
+
+            with open(LOG_FILE, "r", encoding="utf-8") as f:
+                total_lines = sum(1 for _ in f)
+
+            stats_text = f"""Log File Statistics:
+Path: {LOG_FILE}
+Size: {size_mb:.2f} MB
+Lines: {total_lines}
+Last Modified: {modified}"""
+
+            return {"status": "success", "content": [{"text": stats_text}]}
+
+        else:
+            return {
+                "status": "error",
+                "content": [
+                    {
+                        "text": f"Unknown action: {action}. Valid: view, tail, search, clear, stats"
+                    }
+                ],
+            }
+
+    except Exception as e:
+        logger.error(f"Error in view_logs_tool: {e}")
+        return {"status": "error", "content": [{"text": f"Error: {str(e)}"}]}
+
+
 def get_shell_history_file():
-    """Get devduck history file"""
-    history = Path.home() / ".devduck_history"
-    if not history.exists():
-        history.touch(mode=0o600)
-    return str(history)
+    """Get the devduck-specific history file path."""
+    devduck_history = Path.home() / ".devduck_history"
+    if not devduck_history.exists():
+        devduck_history.touch(mode=0o600)
+    return str(devduck_history)
 
 
 def get_shell_history_files():
@@ -125,6 +268,32 @@ def parse_history_line(line, history_type):
     return None
 
 
+def get_recent_logs():
+    """Get the last N lines from the log file for context."""
+    try:
+        log_line_count = int(os.getenv("DEVDUCK_LOG_LINE_COUNT", "50"))
+
+        if not LOG_FILE.exists():
+            return ""
+
+        with open(LOG_FILE, "r", encoding="utf-8", errors="ignore") as f:
+            all_lines = f.readlines()
+
+        recent_lines = (
+            all_lines[-log_line_count:]
+            if len(all_lines) > log_line_count
+            else all_lines
+        )
+
+        if not recent_lines:
+            return ""
+
+        log_content = "".join(recent_lines)
+        return f"\n\n## Recent Logs (last {len(recent_lines)} lines):\n```\n{log_content}```\n"
+    except Exception as e:
+        return f"\n\n## Recent Logs: Error reading logs - {e}\n"
+
+
 def get_last_messages():
     """Get the last N messages from multiple shell histories for context."""
     try:
@@ -184,225 +353,178 @@ def get_last_messages():
         return ""
 
 
-def get_recent_logs():
-    """Get recent logs for context"""
-    try:
-        log_count = int(os.getenv("DEVDUCK_LOG_LINE_COUNT", "50"))
-
-        if not LOG_FILE.exists():
-            return ""
-
-        with open(LOG_FILE, "r", encoding="utf-8", errors="ignore") as f:
-            lines = f.readlines()
-
-        recent = lines[-log_count:] if len(lines) > log_count else lines
-
-        if recent:
-            return f"\n\n## Recent Logs (last {len(recent)} lines):\n```\n{''.join(recent)}```\n"
-        return ""
-    except:
-        return ""
-
-
 def append_to_shell_history(query, response):
-    """Append interaction to history"""
-    import time
-
+    """Append the interaction to devduck shell history."""
     try:
         history_file = get_shell_history_file()
         timestamp = str(int(time.time()))
-        response_summary = (
-            str(response).replace("\n", " ")[
-                : int(os.getenv("DEVDUCK_RESPONSE_SUMMARY_LENGTH", "10000"))
-            ]
-            + "..."
-        )
 
         with open(history_file, "a", encoding="utf-8") as f:
             f.write(f": {timestamp}:0;# devduck: {query}\n")
+            response_summary = (
+                str(response).replace("\n", " ")[
+                    : int(os.getenv("DEVDUCK_RESPONSE_SUMMARY_LENGTH", "10000"))
+                ]
+                + "..."
+            )
             f.write(f": {timestamp}:0;# devduck_result: {response_summary}\n")
 
         os.chmod(history_file, 0o600)
-    except:
+    except Exception:
         pass
 
 
+# 🦆 The devduck agent
 class DevDuck:
-    """Minimalist adaptive agent with flexible tool loading"""
-
     def __init__(
         self,
         auto_start_servers=True,
-        tcp_port=9999,
-        ws_port=8080,
-        mcp_port=8000,
-        ipc_socket=None,
-        enable_tcp=True,
-        enable_ws=True,
-        enable_mcp=True,
-        enable_ipc=True,
+        servers=None,
     ):
-        """Initialize the minimalist adaptive agent"""
-        logger.info("Initializing DevDuck...")
-
-        # Environment detection
-        self.os = platform.system()
-        self.arch = platform.machine()
-        self.model = "qwen3:1.7b" if self.os == "Darwin" else "qwen3:8b"
-
-        # Hot-reload state
-        self._agent_executing = False
-        self._reload_pending = False
-
-        # Server configuration
-        self.tcp_port = tcp_port
-        self.ws_port = ws_port
-        self.mcp_port = mcp_port
-        self.ipc_socket = ipc_socket or "/tmp/devduck_main.sock"
-        self.enable_tcp = enable_tcp
-        self.enable_ws = enable_ws
-        self.enable_mcp = enable_mcp
-        self.enable_ipc = enable_ipc
-
-        # Import core dependencies
-        from strands import Agent, tool
-
-        # Load tools with flexible configuration
-        tools = self._load_tools_flexible()
-
-        # Add built-in view_logs tool
-        @tool
-        def view_logs(action: str = "view", lines: int = 100, pattern: str = None):
-            """View and manage DevDuck logs"""
-            return self._view_logs_impl(action, lines, pattern)
-
-        tools.append(view_logs)
-
-        # Create model
-        model = self._create_model()
-
-        # Create agent
-        self.agent = Agent(
-            model=model,
-            tools=tools,
-            system_prompt=self._build_prompt(),
-            load_tools_from_directory=True,
-        )
-
-        # Auto-start servers
-        if auto_start_servers and "--mcp" not in sys.argv:
-            self._start_servers()
-
-        # Start hot-reload watcher
-        self._start_hot_reload()
-
-        logger.info(f"DevDuck ready with {len(tools)} tools")
-
-    def _load_tools_flexible(self):
+        """Initialize the minimalist adaptive agent
+
+        Args:
+            auto_start_servers: Enable automatic server startup
+            servers: Dict of server configs with optional env var lookups
+                Example: {
+                    "tcp": {"port": 9999},
+                    "ws": {"port": 8080, "LOOKUP_KEY": "SLACK_API_KEY"},
+                    "mcp": {"port": 8000},
+                    "ipc": {"socket_path": "/tmp/devduck.sock"}
+                }
         """
-        Load tools with flexible configuration via DEVDUCK_TOOLS env var.
+        logger.info("Initializing DevDuck agent...")
+        try:
+            self.env_info = {
+                "os": platform.system(),
+                "arch": platform.machine(),
+                "python": sys.version_info,
+                "cwd": str(Path.cwd()),
+                "home": str(Path.home()),
+                "shell": os.environ.get("SHELL", "unknown"),
+                "hostname": socket.gethostname(),
+            }
+
+            # Execution state tracking for hot-reload
+            self._agent_executing = False
+            self._reload_pending = False
+
+            # Server configuration
+            if servers is None:
+                # Default server config from env vars
+                servers = {
+                    "tcp": {
+                        "port": int(os.getenv("DEVDUCK_TCP_PORT", "9999")),
+                        "enabled": os.getenv("DEVDUCK_ENABLE_TCP", "true").lower()
+                        == "true",
+                    },
+                    "ws": {
+                        "port": int(os.getenv("DEVDUCK_WS_PORT", "8080")),
+                        "enabled": os.getenv("DEVDUCK_ENABLE_WS", "true").lower()
+                        == "true",
+                    },
+                    "mcp": {
+                        "port": int(os.getenv("DEVDUCK_MCP_PORT", "8000")),
+                        "enabled": os.getenv("DEVDUCK_ENABLE_MCP", "true").lower()
+                        == "true",
+                    },
+                    "ipc": {
+                        "socket_path": os.getenv(
+                            "DEVDUCK_IPC_SOCKET", "/tmp/devduck_main.sock"
+                        ),
+                        "enabled": os.getenv("DEVDUCK_ENABLE_IPC", "true").lower()
+                        == "true",
+                    },
+                }
 
-        Format: package:tool1,tool2:package2:tool3,tool4
-        Example: strands_tools:shell,editor:strands_fun_tools:clipboard
+            self.servers = servers
 
-        Static tools (always loaded):
-        - DevDuck's own tools (tcp, websocket, ipc, etc.)
-        - AgentCore tools (if AWS credentials available)
-        """
-        tools = []
+            from strands import Agent, tool
 
-        # 1. STATIC: Core DevDuck tools (always load)
-        try:
-            from devduck.tools import (
-                tcp,
-                websocket,
-                ipc,
-                mcp_server,
-                install_tools,
-                use_github,
-                create_subagent,
-                store_in_kb,
-                system_prompt,
-                tray,
-                ambient,
+            # 🧰 Load tools with flexible configuration
+            tools_config = os.getenv("DEVDUCK_TOOLS")
+            if tools_config:
+                logger.info(f"Loading tools from DEVDUCK_TOOLS: {tools_config}")
+                core_tools = self._load_tools_from_config(tools_config)
+            else:
+                logger.info("Loading default tool set")
+                core_tools = self._load_default_tools()
+
+            # Wrap view_logs_tool with @tool decorator
+            @tool
+            def view_logs(
+                action: str = "view",
+                lines: int = 100,
+                pattern: str = None,
+            ) -> Dict[str, Any]:
+                """View and manage DevDuck logs."""
+                return view_logs_tool(action, lines, pattern)
+
+            # Add built-in tools to the toolset
+            core_tools.extend([view_logs])
+
+            # Assign tools
+            self.tools = core_tools
+
+            logger.info(f"Initialized {len(self.tools)} tools")
+
+            # 🎯 Smart model selection
+            self.agent_model, self.model = self._select_model()
+
+            # Create agent with self-healing
+            self.agent = Agent(
+                model=self.agent_model,
+                tools=self.tools,
+                system_prompt=self._build_system_prompt(),
+                load_tools_from_directory=True,
             )
 
-            tools.extend(
-                [
-                    tcp,
-                    websocket,
-                    ipc,
-                    mcp_server,
-                    install_tools,
-                    use_github,
-                    create_subagent,
-                    store_in_kb,
-                    system_prompt,
-                    tray,
-                    ambient,
-                ]
-            )
-            logger.info("✅ DevDuck core tools loaded")
-        except ImportError as e:
-            logger.warning(f"DevDuck tools unavailable: {e}")
+            # 🚀 AUTO-START SERVERS
+            if auto_start_servers and "--mcp" not in sys.argv:
+                self._start_servers()
 
-        # 2. STATIC: AgentCore tools (if AWS credentials available and not disabled)
-        if os.getenv("DEVDUCK_DISABLE_AGENTCORE_TOOLS", "false").lower() != "true":
-            try:
-                boto3.client("sts").get_caller_identity()
-                from .tools.agentcore_config import agentcore_config
-                from .tools.agentcore_invoke import agentcore_invoke
-                from .tools.agentcore_logs import agentcore_logs
-                from .tools.agentcore_agents import agentcore_agents
+            # Start file watcher for auto hot-reload
+            self._start_file_watcher()
 
-                tools.extend(
-                    [
-                        agentcore_config,
-                        agentcore_invoke,
-                        agentcore_logs,
-                        agentcore_agents,
-                    ]
-                )
-                logger.info("✅ AgentCore tools loaded")
-            except:
-                pass
-        else:
             logger.info(
-                "⏭️  AgentCore tools disabled (DEVDUCK_DISABLE_AGENTCORE_TOOLS=true)"
+                f"DevDuck agent initialized successfully with model {self.model}"
             )
 
-        # 3. FLEXIBLE: Load tools from DEVDUCK_TOOLS env var
-        tools_config = os.getenv("DEVDUCK_TOOLS")
-
-        if tools_config:
-            # Parse: "strands_tools:shell,editor:strands_fun_tools:clipboard"
-            tools.extend(self._parse_and_load_tools(tools_config))
-        else:
-            # Default: Load all common tools
-            tools.extend(self._load_default_tools())
-
-        return tools
+        except Exception as e:
+            logger.error(f"Initialization failed: {e}")
+            self._self_heal(e)
 
-    def _parse_and_load_tools(self, config):
+    def _load_tools_from_config(self, config):
         """
-        Parse DEVDUCK_TOOLS config and load specified tools.
+        Load tools based on DEVDUCK_TOOLS configuration.
 
         Format: package:tool1,tool2:package2:tool3
-        Example: strands_tools:shell,editor:strands_fun_tools:clipboard,cursor
+        Example: strands_tools:shell,editor:strands_fun_tools:clipboard
         """
-        loaded_tools = []
+        tools = []
+
+        # Always load DevDuck core tools
+        tools.extend(self._load_devduck_tools())
+
+        # Parse and load configured tools
         current_package = None
 
         for segment in config.split(":"):
             segment = segment.strip()
 
             # Check if this segment is a package or tool list
-            if "," not in segment and not segment.startswith("strands"):
+            if "," not in segment and not any(
+                segment.startswith(pkg)
+                for pkg in [
+                    "strands_",
+                    "devduck",
+                ]  # TODO: we should accept any python library here.
+            ):
                 # Single tool from current package
                 if current_package:
                     tool = self._load_single_tool(current_package, segment)
                     if tool:
-                        loaded_tools.append(tool)
+                        tools.append(tool)
             elif "," in segment:
                 # Tool list from current package
                 if current_package:
@@ -410,13 +532,13 @@ class DevDuck:
                         tool_name = tool_name.strip()
                         tool = self._load_single_tool(current_package, tool_name)
                         if tool:
-                            loaded_tools.append(tool)
+                            tools.append(tool)
             else:
                 # Package name
                 current_package = segment
 
-        logger.info(f"✅ Loaded {len(loaded_tools)} tools from DEVDUCK_TOOLS")
-        return loaded_tools
+        logger.info(f"Loaded tools from DEVDUCK_TOOLS configuration")
+        return tools
 
     def _load_single_tool(self, package, tool_name):
         """Load a single tool from a package"""
@@ -430,10 +552,13 @@ class DevDuck:
             return None
 
     def _load_default_tools(self):
-        """Load default tools when DEVDUCK_TOOLS is not set"""
+        """Load default comprehensive tool set"""
         tools = []
 
-        # strands-agents-tools (essential)
+        # Always load DevDuck core tools
+        tools.extend(self._load_devduck_tools())
+
+        # Load strands-agents-tools (essential)
         try:
             from strands_tools import (
                 shell,
@@ -466,9 +591,9 @@ class DevDuck:
             )
             logger.info("✅ strands-agents-tools loaded")
         except ImportError:
-            logger.warning("strands-agents-tools unavailable")
+            logger.info("strands-agents-tools unavailable")
 
-        # strands-fun-tools (optional, skip in --mcp mode)
+        # Load strands-fun-tools (optional, skip in --mcp mode)
         if "--mcp" not in sys.argv:
             try:
                 from strands_fun_tools import (
@@ -486,23 +611,103 @@ class DevDuck:
 
         return tools
 
-    def _create_model(self):
-        """Create model with smart provider selection"""
+    def _load_devduck_tools(self):
+        """Load DevDuck's core tools (always available)"""
+        tools = []
+        try:
+            from .tools import (
+                tcp,
+                websocket,
+                ipc,
+                mcp_server,
+                install_tools,
+                use_github,
+                create_subagent,
+                store_in_kb,
+                system_prompt,
+                state_manager,
+                tray,
+                ambient,
+            )
+
+            tools.extend(
+                [
+                    tcp,
+                    websocket,
+                    ipc,
+                    mcp_server,
+                    install_tools,
+                    use_github,
+                    create_subagent,
+                    store_in_kb,
+                    system_prompt,
+                    state_manager,
+                    tray,
+                    ambient,
+                ]
+            )
+            logger.info("✅ DevDuck core tools loaded")
+        except ImportError as e:
+            logger.warning(f"DevDuck tools unavailable: {e}")
+
+        # Load AgentCore tools if AWS credentials available (conditional)
+        if os.getenv("DEVDUCK_DISABLE_AGENTCORE_TOOLS", "false").lower() != "true":
+            try:
+                import boto3
+
+                boto3.client("sts").get_caller_identity()
+
+                from .tools.agentcore_config import agentcore_config
+                from .tools.agentcore_invoke import agentcore_invoke
+                from .tools.agentcore_logs import agentcore_logs
+                from .tools.agentcore_agents import agentcore_agents
+
+                tools.extend(
+                    [
+                        agentcore_config,
+                        agentcore_invoke,
+                        agentcore_logs,
+                        agentcore_agents,
+                    ]
+                )
+                logger.info("✅ AgentCore tools loaded")
+            except Exception as e:
+                logger.debug(f"AgentCore tools unavailable: {e}")
+        else:
+            logger.info(
+                "⏭️  AgentCore tools disabled (DEVDUCK_DISABLE_AGENTCORE_TOOLS=true)"
+            )
+
+        return tools
+
+    def _select_model(self):
+        """
+        Smart model selection with fallback: Bedrock → MLX → Ollama
+
+        Returns:
+            Tuple of (model_instance, model_name)
+        """
         provider = os.getenv("MODEL_PROVIDER")
 
         if not provider:
             # Auto-detect: Bedrock → MLX → Ollama
             try:
+                # Try Bedrock if AWS credentials available
+                import boto3
+
                 boto3.client("sts").get_caller_identity()
                 provider = "bedrock"
                 print("🦆 Using Bedrock")
             except:
-                if self.os == "Darwin" and self.arch in ["arm64", "aarch64"]:
+                # Try MLX on Apple Silicon
+                if platform.system() == "Darwin" and platform.machine() in [
+                    "arm64",
+                    "aarch64",
+                ]:
                     try:
                         from strands_mlx import MLXModel
 
                         provider = "mlx"
-                        self.model = "mlx-community/Qwen3-1.7B-4bit"
                         print("🦆 Using MLX")
                     except ImportError:
                         provider = "ollama"
@@ -511,26 +716,43 @@ class DevDuck:
                     provider = "ollama"
                     print("🦆 Using Ollama")
 
-        # Create model
+        # Create model based on provider
         if provider == "mlx":
             from strands_mlx import MLXModel
 
-            return MLXModel(model_id=self.model, temperature=1)
+            model_name = "mlx-community/Qwen3-1.7B-4bit"
+            return MLXModel(model_id=model_name, temperature=1), model_name
+
         elif provider == "ollama":
             from strands.models.ollama import OllamaModel
 
-            return OllamaModel(
-                host="http://localhost:11434",
-                model_id=self.model,
-                temperature=1,
-                keep_alive="5m",
+            os_type = platform.system()
+            if os_type == "Darwin":
+                model_name = "qwen3:1.7b"
+            elif os_type == "Linux":
+                model_name = "qwen3:30b"
+            else:
+                model_name = "qwen3:8b"
+
+            return (
+                OllamaModel(
+                    host="http://localhost:11434",
+                    model_id=model_name,
+                    temperature=1,
+                    keep_alive="5m",
+                ),
+                model_name,
             )
+
         else:
+            # Bedrock or other providers via create_model
             from strands_tools.utils.models.model import create_model
 
-            return create_model(provider=provider)
+            model = create_model(provider=provider)
+            model_name = os.getenv("STRANDS_MODEL_ID", "bedrock")
+            return model, model_name
 
-    def _build_prompt(self):
+    def _build_system_prompt(self):
         """Build adaptive system prompt based on environment
 
         IMPORTANT: The system prompt includes the agent's complete source code.
@@ -540,82 +762,83 @@ class DevDuck:
 
         Learning: Always check source code truth over conversation memory!
         """
+        # Current date and time
+        current_datetime = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        current_date = datetime.now().strftime("%A, %B %d, %Y")
+        current_time = datetime.now().strftime("%I:%M %p")
+
+        session_id = f"devduck-{datetime.now().strftime('%Y-%m-%d')}"
+
+        # Get own file path for self-modification awareness
+        own_file_path = Path(__file__).resolve()
+
+        # Get own source code for self-awareness
         own_code = get_own_source_code()
-        recent_context = get_last_messages()
-        recent_logs = get_recent_logs()
 
-        # Detect if using Bedrock for AgentCore documentation
-        provider = os.getenv("MODEL_PROVIDER", "")
-        is_bedrock = provider == "bedrock" or "bedrock" in provider.lower()
+        # Get recent conversation history context (with error handling)
         try:
-            if not is_bedrock:
-                boto3.client("sts").get_caller_identity()
-                is_bedrock = True
-        except:
-            pass
-
-        # Build AgentCore documentation if using Bedrock
-        agentcore_docs = ""
-        if is_bedrock:
-            handler_path = str(Path(__file__).parent / "agentcore_handler.py")
-            agentcore_docs = f"""
-
-## 🚀 AgentCore (Bedrock)
-
-Handler: `{handler_path}`
-
-### Quick Deploy:
-```python
-# Configure + launch
-agentcore_config(action="configure", agent_name="devduck", 
-    tools="strands_tools:shell,editor", auto_launch=True)
-
-# Invoke
-agentcore_invoke(prompt="test", agent_name="devduck")
-
-# Monitor
-agentcore_logs(agent_name="devduck")
-agentcore_agents(action="list")
-```
-
-### Key Params:
-- tools: "package:tool1,tool2:package2:tool3"
-- idle_timeout: 900s (default)
-- model_id: us.anthropic.claude-sonnet-4-5-20250929-v1:0
-"""
+            recent_context = get_last_messages()
+        except Exception as e:
+            print(f"🦆 Warning: Could not load history context: {e}")
+            recent_context = ""
+
+        # Get recent logs for immediate visibility
+        try:
+            recent_logs = get_recent_logs()
+        except Exception as e:
+            print(f"🦆 Warning: Could not load recent logs: {e}")
+            recent_logs = ""
 
-        return f"""🦆 DevDuck - self-adapting agent
+        return f"""🦆 You are DevDuck - an extreme minimalist, self-adapting agent.
 
-Environment: {self.os} {self.arch}
+Environment: {self.env_info['os']} {self.env_info['arch']} 
+Python: {self.env_info['python']}
 Model: {self.model}
-CWD: {Path.cwd()}
+Hostname: {self.env_info['hostname']}
+Session ID: {session_id}
+Current Time: {current_datetime} ({current_date} at {current_time})
+My Path: {own_file_path}
 
 You are:
 - Minimalist: Brief, direct responses
+- Self-healing: Adapt when things break  
 - Efficient: Get things done fast
 - Pragmatic: Use what works
 
+Current working directory: {self.env_info['cwd']}
+
 {recent_context}
 {recent_logs}
-{agentcore_docs}
-
-## Your Code
 
+## Your Own Implementation:
 You have full access to your own source code for self-awareness and self-modification:
----
+
 {own_code}
----
 
-## Hot Reload Active:
-- Save .py files in ./tools/ for instant tool creation
-- Use install_tools() to load from packages
-- No restart needed
+## Hot Reload System Active:
+- **Instant Tool Creation** - Save any .py file in `./tools/` and it becomes immediately available
+- **No Restart Needed** - Tools are auto-loaded and ready to use instantly
+- **Live Development** - Modify existing tools while running and test immediately
+- **Full Python Access** - Create any Python functionality as a tool
+- **Agent Protection** - Hot-reload waits until agent finishes current task
+
+## Dynamic Tool Loading:
+- **Install Tools** - Use install_tools() to load tools from any Python package
+  - Example: install_tools(action="install_and_load", package="strands-fun-tools", module="strands_fun_tools")
+  - Expands capabilities without restart
+  - Access to entire Python ecosystem
 
 ## Tool Configuration:
 Set DEVDUCK_TOOLS for custom tools:
 - Format: package:tool1,tool2:package2:tool3
 - Example: strands_tools:shell,editor:strands_fun_tools:clipboard
-- Static tools always loaded: tcp, websocket, ipc, mcp_server, agentcore_*
+- Tools are filtered - only specified tools are loaded
+
+## MCP Server:
+- **Expose as MCP Server** - Use mcp_server() to expose devduck via MCP protocol
+  - Example: mcp_server(action="start", port=8000)
+  - Connect from Claude Desktop, other agents, or custom clients
+  - Full bidirectional communication
 
 ## Knowledge Base Integration:
 - **Automatic RAG** - Set DEVDUCK_KNOWLEDGE_BASE_ID to enable automatic retrieval/storage
@@ -624,293 +847,472 @@ Set DEVDUCK_TOOLS for custom tools:
   - Seamless memory across sessions without manual tool calls
 
 ## System Prompt Management:
-- system_prompt(action='view') - View current
-- system_prompt(action='update', prompt='...') - Update
-- system_prompt(action='update', repository='owner/repo') - Sync to GitHub
+- **View**: system_prompt(action='view') - See current prompt
+- **Update Local**: system_prompt(action='update', prompt='new text') - Updates env var + .prompt file
+- **Update GitHub**: system_prompt(action='update', prompt='text', repository='cagataycali/devduck') - Syncs to repo variables
+- **Variable Name**: system_prompt(action='update', prompt='text', variable_name='CUSTOM_PROMPT') - Use custom var
+- **Add Context**: system_prompt(action='add_context', context='new learning') - Append without replacing
+
+### 🧠 Self-Improvement Pattern:
+When you learn something valuable during conversations:
+1. Identify the new insight or pattern
+2. Use system_prompt(action='add_context', context='...')  to append it
+3. Sync to GitHub: system_prompt(action='update', prompt=new_full_prompt, repository='owner/repo')
+4. New learnings persist across sessions via SYSTEM_PROMPT env var
+
+**Repository Integration**: Set repository='cagataycali/devduck' to sync prompts across deployments
 
 ## Shell Commands:
-- Prefix with ! to run shell commands
-- Example: ! ls -la
+- Prefix with ! to execute shell commands directly
+- Example: ! ls -la (lists files)
+- Example: ! pwd (shows current directory)
 
-Response: MINIMAL WORDS, MAX PARALLELISM
+**Response Format:**
+- Tool calls: **MAXIMUM PARALLELISM - ALWAYS** 
+- Communication: **MINIMAL WORDS**
+- Efficiency: **Speed is paramount**
 
-## Tool Building Guide:
+{os.getenv('SYSTEM_PROMPT', '')}"""
 
-### **@tool Decorator (Recommended):**
-```python
-# ./tools/my_tool.py
-from strands import tool
+    def _self_heal(self, error):
+        """Attempt self-healing when errors occur"""
+        logger.error(f"Self-healing triggered by error: {error}")
+        print(f"🦆 Self-healing from: {error}")
 
-@tool
-def my_tool(param1: str, param2: int = 10) -> str:
-    \"\"\"Tool description.
-    
-    Args:
-        param1: Description of param1
-        param2: Description of param2 (default: 10)
-        
-    Returns:
-        str: Description of return value
-    \"\"\"
-    # Implementation
-    return f"Result: {{param1}} - {{param2}}"
-```
-
-### **Action-Based Pattern:**
-```python
-from typing import Dict, Any
-from strands import tool
+        # Prevent infinite recursion by tracking heal attempts
+        if not hasattr(self, "_heal_count"):
+            self._heal_count = 0
 
-@tool
-def my_tool(action: str, data: str = None) -> Dict[str, Any]:
-    \"\"\"Multi-action tool.
-    
-    Args:
-        action: Action to perform (get, set, delete)
-        data: Optional data for action
-        
-    Returns:
-        Dict with status and content
-    \"\"\"
-    if action == "get":
-        return {{"status": "success", "content": [{{"text": f"Got: {{data}}"}}]}}
-    elif action == "set":
-        return {{"status": "success", "content": [{{"text": f"Set: {{data}}"}}]}}
-    else:
-        return {{"status": "error", "content": [{{"text": f"Unknown action: {{action}}"}}]}}
-```
+        self._heal_count += 1
 
-### **Tool Best Practices:**
-1. Use type hints for all parameters
-2. Provide clear docstrings
-3. Return consistent formats (str or Dict[str, Any])
-4. Use action-based pattern for complex tools
-5. Handle errors gracefully
-6. Log important operations
+        # Limit recursion - if we've tried more than 3 times, give up
+        if self._heal_count > 2:
+            print(f"🦆 Self-healing failed after {self._heal_count} attempts")
+            print("🦆 Please fix the issue manually and restart")
+            sys.exit(1)
 
-{os.getenv('SYSTEM_PROMPT', '')}"""
+        elif "connection" in str(error).lower():
+            print("🦆 Connection issue - checking ollama service...")
+            try:
+                subprocess.run(["ollama", "serve"], check=False, timeout=2)
+            except:
+                pass
 
-    def _view_logs_impl(self, action, lines, pattern):
-        """Implementation of view_logs tool"""
+        # Retry initialization
         try:
-            if action == "view":
-                if not LOG_FILE.exists():
-                    return {"status": "success", "content": [{"text": "No logs yet"}]}
-                with open(LOG_FILE, "r") as f:
-                    all_lines = f.readlines()
-                    recent = all_lines[-lines:] if len(all_lines) > lines else all_lines
-                    return {
-                        "status": "success",
-                        "content": [
-                            {"text": f"Last {len(recent)} lines:\n\n{''.join(recent)}"}
-                        ],
-                    }
+            self.__init__()
+        except Exception as e2:
+            print(f"🦆 Self-heal failed: {e2}")
+            print("🦆 Running in minimal mode...")
+            self.agent = None
+
+    def _is_port_available(self, port):
+        """Check if a port is available"""
+        try:
+            test_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            test_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            test_socket.bind(("0.0.0.0", port))
+            test_socket.close()
+            return True
+        except OSError:
+            return False
+
+    def _is_socket_available(self, socket_path):
+        """Check if a Unix socket is available"""
+        import os
+
+        # If socket file doesn't exist, it's available
+        if not os.path.exists(socket_path):
+            return True
+        # If it exists, try to connect to see if it's in use
+        try:
+            test_socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            test_socket.connect(socket_path)
+            test_socket.close()
+            return False  # Socket is in use
+        except (ConnectionRefusedError, FileNotFoundError):
+            # Socket file exists but not in use - remove stale socket
+            try:
+                os.remove(socket_path)
+                return True
+            except:
+                return False
+        except Exception:
+            return False
+
+    def _find_available_port(self, start_port, max_attempts=10):
+        """Find an available port starting from start_port"""
+        for offset in range(max_attempts):
+            port = start_port + offset
+            if self._is_port_available(port):
+                return port
+        return None
 
-            elif action == "search":
-                if not pattern:
-                    return {
-                        "status": "error",
-                        "content": [{"text": "pattern required"}],
-                    }
-                if not LOG_FILE.exists():
-                    return {"status": "success", "content": [{"text": "No logs yet"}]}
-                with open(LOG_FILE, "r") as f:
-                    matches = [line for line in f if pattern.lower() in line.lower()]
-                if not matches:
-                    return {
-                        "status": "success",
-                        "content": [{"text": f"No matches for: {pattern}"}],
-                    }
-                return {
-                    "status": "success",
-                    "content": [
-                        {
-                            "text": f"Found {len(matches)} matches:\n\n{''.join(matches[-100:])}"
-                        }
-                    ],
-                }
+    def _find_available_socket(self, base_socket_path, max_attempts=10):
+        """Find an available socket path"""
+        if self._is_socket_available(base_socket_path):
+            return base_socket_path
+        # Try numbered alternatives
+        for i in range(1, max_attempts):
+            alt_socket = f"{base_socket_path}.{i}"
+            if self._is_socket_available(alt_socket):
+                return alt_socket
+        return None
 
-            elif action == "clear":
-                if LOG_FILE.exists():
-                    LOG_FILE.unlink()
-                return {"status": "success", "content": [{"text": "Logs cleared"}]}
+    def _start_servers(self):
+        """Auto-start configured servers with port conflict handling"""
+        logger.info("Auto-starting servers...")
+        print("🦆 Auto-starting servers...")
 
-            else:
-                return {
-                    "status": "error",
-                    "content": [{"text": f"Unknown action: {action}"}],
-                }
-        except Exception as e:
-            return {"status": "error", "content": [{"text": f"Error: {e}"}]}
+        # Start servers in order: IPC, TCP, WS, MCP
+        server_order = ["ipc", "tcp", "ws", "mcp"]
 
-    def _start_servers(self):
-        """Auto-start servers"""
-        if self.enable_tcp:
-            try:
-                self.agent.tool.tcp(action="start_server", port=self.tcp_port)
-                print(f"🦆 ✓ TCP: localhost:{self.tcp_port}")
-            except Exception as e:
-                logger.warning(f"TCP server failed: {e}")
+        for server_type in server_order:
+            if server_type not in self.servers:
+                continue
 
-        if self.enable_ws:
-            try:
-                self.agent.tool.websocket(action="start_server", port=self.ws_port)
-                print(f"🦆 ✓ WebSocket: localhost:{self.ws_port}")
-            except Exception as e:
-                logger.warning(f"WebSocket server failed: {e}")
+            config = self.servers[server_type]
 
-        if self.enable_mcp:
-            try:
-                self.agent.tool.mcp_server(
-                    action="start",
-                    transport="http",
-                    port=self.mcp_port,
-                    expose_agent=True,
-                    agent=self.agent,
-                )
-                print(f"🦆 ✓ MCP: http://localhost:{self.mcp_port}/mcp")
-            except Exception as e:
-                logger.warning(f"MCP server failed: {e}")
+            # Check if server is enabled
+            if not config.get("enabled", True):
+                continue
+
+            # Check for LOOKUP_KEY (conditional start based on env var)
+            if "LOOKUP_KEY" in config:
+                lookup_key = config["LOOKUP_KEY"]
+                if not os.getenv(lookup_key):
+                    logger.info(f"Skipping {server_type} - {lookup_key} not set")
+                    continue
 
-        if self.enable_ipc:
+            # Start the server with port conflict handling
             try:
-                self.agent.tool.ipc(action="start_server", socket_path=self.ipc_socket)
-                print(f"🦆 ✓ IPC: {self.ipc_socket}")
-            except Exception as e:
-                logger.warning(f"IPC server failed: {e}")
+                if server_type == "tcp":
+                    port = config.get("port", 9999)
+
+                    # Check port availability BEFORE attempting to start
+                    if not self._is_port_available(port):
+                        alt_port = self._find_available_port(port + 1)
+                        if alt_port:
+                            logger.info(f"Port {port} in use, using {alt_port}")
+                            print(f"🦆 Port {port} in use, using {alt_port}")
+                            port = alt_port
+                        else:
+                            logger.warning(f"No available ports found for TCP server")
+                            continue
 
-    def _start_hot_reload(self):
-        """Start hot-reload file watcher"""
+                    result = self.agent.tool.tcp(action="start_server", port=port)
 
-        self._watch_file = Path(__file__).resolve()
-        self._last_modified = (
-            self._watch_file.stat().st_mtime if self._watch_file.exists() else None
-        )
-        self._watcher_running = True
+                    if result.get("status") == "success":
+                        logger.info(f"✓ TCP server started on port {port}")
+                        print(f"🦆 ✓ TCP server: localhost:{port}")
+
+                elif server_type == "ws":
+                    port = config.get("port", 8080)
 
-        def watcher_thread():
-            import time
+                    # Check port availability BEFORE attempting to start
+                    if not self._is_port_available(port):
+                        alt_port = self._find_available_port(port + 1)
+                        if alt_port:
+                            logger.info(f"Port {port} in use, using {alt_port}")
+                            print(f"🦆 Port {port} in use, using {alt_port}")
+                            port = alt_port
+                        else:
+                            logger.warning(
+                                f"No available ports found for WebSocket server"
+                            )
+                            continue
 
-            last_reload = 0
-            debounce = 3  # seconds
+                    result = self.agent.tool.websocket(action="start_server", port=port)
 
-            while self._watcher_running:
-                try:
-                    if self._watch_file.exists():
-                        mtime = self._watch_file.stat().st_mtime
-                        current_time = time.time()
-
-                        if (
-                            self._last_modified
-                            and mtime > self._last_modified
-                            and current_time - last_reload > debounce
-                        ):
-
-                            print(f"🦆 Code changed - hot-reload triggered")
-                            self._last_modified = mtime
-                            last_reload = current_time
-
-                            if self._agent_executing:
-                                print("🦆 Reload pending (agent executing)")
-                                self._reload_pending = True
-                            else:
-                                self._hot_reload()
+                    if result.get("status") == "success":
+                        logger.info(f"✓ WebSocket server started on port {port}")
+                        print(f"🦆 ✓ WebSocket server: localhost:{port}")
+
+                elif server_type == "mcp":
+                    port = config.get("port", 8000)
+
+                    # Check port availability BEFORE attempting to start
+                    if not self._is_port_available(port):
+                        alt_port = self._find_available_port(port + 1)
+                        if alt_port:
+                            logger.info(f"Port {port} in use, using {alt_port}")
+                            print(f"🦆 Port {port} in use, using {alt_port}")
+                            port = alt_port
                         else:
-                            self._last_modified = mtime
-                except Exception as e:
-                    logger.error(f"File watcher error: {e}")
+                            logger.warning(f"No available ports found for MCP server")
+                            continue
 
-                time.sleep(1)
+                    result = self.agent.tool.mcp_server(
+                        action="start",
+                        transport="http",
+                        port=port,
+                        expose_agent=True,
+                        agent=self.agent,
+                    )
 
-        thread = threading.Thread(target=watcher_thread, daemon=True)
-        thread.start()
-        logger.info(f"Hot-reload watching: {self._watch_file}")
+                    if result.get("status") == "success":
+                        logger.info(f"✓ MCP HTTP server started on port {port}")
+                        print(f"🦆 ✓ MCP server: http://localhost:{port}/mcp")
+
+                elif server_type == "ipc":
+                    socket_path = config.get("socket_path", "/tmp/devduck_main.sock")
+
+                    # Check socket availability BEFORE attempting to start
+                    available_socket = self._find_available_socket(socket_path)
+                    if not available_socket:
+                        logger.warning(
+                            f"No available socket paths found for IPC server"
+                        )
+                        continue
+
+                    if available_socket != socket_path:
+                        logger.info(
+                            f"Socket {socket_path} in use, using {available_socket}"
+                        )
+                        print(
+                            f"🦆 Socket {socket_path} in use, using {available_socket}"
+                        )
+                        socket_path = available_socket
+
+                    result = self.agent.tool.ipc(
+                        action="start_server", socket_path=socket_path
+                    )
 
-    def _hot_reload(self):
-        """Hot-reload by restarting process"""
-        logger.info("Hot-reload: restarting process")
-        self._watcher_running = False
-        os.execv(sys.executable, [sys.executable] + sys.argv)
+                    if result.get("status") == "success":
+                        logger.info(f"✓ IPC server started on {socket_path}")
+                        print(f"🦆 ✓ IPC server: {socket_path}")
+                # TODO: support custom file path here so we can trigger foreign python function like another file
+            except Exception as e:
+                logger.error(f"Failed to start {server_type} server: {e}")
+                print(f"🦆 ⚠ {server_type.upper()} server failed: {e}")
 
     def __call__(self, query):
-        """Call agent with KB integration"""
+        """Make the agent callable with automatic knowledge base integration"""
         if not self.agent:
-            return "🦆 Agent unavailable"
+            logger.warning("Agent unavailable - attempted to call with query")
+            return "🦆 Agent unavailable - try: devduck.restart()"
 
         try:
+            logger.info(f"Agent call started: {query[:100]}...")
+            # Mark agent as executing to prevent hot-reload interruption
             self._agent_executing = True
 
-            # KB retrieval
-            kb_id = os.getenv("DEVDUCK_KNOWLEDGE_BASE_ID")
-            if kb_id:
+            # 📚 Knowledge Base Retrieval (BEFORE agent runs)
+            knowledge_base_id = os.getenv("DEVDUCK_KNOWLEDGE_BASE_ID")
+            if knowledge_base_id and hasattr(self.agent, "tool"):
                 try:
-                    self.agent.tool.retrieve(text=query, knowledgeBaseId=kb_id)
-                except:
-                    pass
+                    if "retrieve" in self.agent.tool_names:
+                        logger.info(f"Retrieving context from KB: {knowledge_base_id}")
+                        self.agent.tool.retrieve(
+                            text=query, knowledgeBaseId=knowledge_base_id
+                        )
+                except Exception as e:
+                    logger.warning(f"KB retrieval failed: {e}")
 
-            # Run agent
+            # Run the agent
             result = self.agent(query)
 
-            # KB storage
-            if kb_id:
+            # 💾 Knowledge Base Storage (AFTER agent runs)
+            if knowledge_base_id and hasattr(self.agent, "tool"):
                 try:
-                    self.agent.tool.store_in_kb(
-                        content=f"Input: {query}\nResult: {str(result)}",
-                        title=f"DevDuck: {datetime.now().strftime('%Y-%m-%d')} | {query[:500]}",
-                        knowledge_base_id=kb_id,
-                    )
-                except:
-                    pass
+                    if "store_in_kb" in self.agent.tool_names:
+                        conversation_content = f"Input: {query}, Result: {result!s}"
+                        conversation_title = f"DevDuck: {datetime.now().strftime('%Y-%m-%d')} | {query[:500]}"
+                        self.agent.tool.store_in_kb(
+                            content=conversation_content,
+                            title=conversation_title,
+                            knowledge_base_id=knowledge_base_id,
+                        )
+                        logger.info(f"Stored conversation in KB: {knowledge_base_id}")
+                except Exception as e:
+                    logger.warning(f"KB storage failed: {e}")
 
+            # Clear executing flag
             self._agent_executing = False
 
-            # Check for pending reload
+            # Check for pending hot-reload
             if self._reload_pending:
-                print("🦆 Agent finished - triggering pending reload")
+                logger.info("Triggering pending hot-reload after agent completion")
+                print("🦆 Agent finished - triggering pending hot-reload...")
                 self._hot_reload()
 
             return result
         except Exception as e:
-            self._agent_executing = False
-            logger.error(f"Agent call failed: {e}")
-            return f"🦆 Error: {e}"
+            self._agent_executing = False  # Reset flag on error
+            logger.error(f"Agent call failed with error: {e}")
+            self._self_heal(e)
+            if self.agent:
+                return self.agent(query)
+            else:
+                return f"🦆 Error: {e}"
+
+    def restart(self):
+        """Restart the agent"""
+        print("🦆 Restarting...")
+        self.__init__()
+
+    def _start_file_watcher(self):
+        """Start background file watcher for auto hot-reload"""
+        import threading
+
+        logger.info("Starting file watcher for hot-reload")
+        # Get the path to this file
+        self._watch_file = Path(__file__).resolve()
+        self._last_modified = (
+            self._watch_file.stat().st_mtime if self._watch_file.exists() else None
+        )
+        self._watcher_running = True
+        self._is_reloading = False
+
+        # Start watcher thread
+        self._watcher_thread = threading.Thread(
+            target=self._file_watcher_thread, daemon=True
+        )
+        self._watcher_thread.start()
+        logger.info(f"File watcher started, monitoring {self._watch_file}")
+
+    def _file_watcher_thread(self):
+        """Background thread that watches for file changes"""
+        last_reload_time = 0
+        debounce_seconds = 3  # 3 second debounce
+
+        while self._watcher_running:
+            try:
+                # Skip if currently reloading
+                if self._is_reloading:
+                    time.sleep(1)
+                    continue
+
+                if self._watch_file.exists():
+                    current_mtime = self._watch_file.stat().st_mtime
+                    current_time = time.time()
+
+                    # Check if file was modified AND debounce period has passed
+                    if (
+                        self._last_modified
+                        and current_mtime > self._last_modified
+                        and current_time - last_reload_time > debounce_seconds
+                    ):
+                        print(f"🦆 Detected changes in {self._watch_file.name}!")
+                        last_reload_time = current_time
+
+                        # Check if agent is currently executing
+                        if self._agent_executing:
+                            logger.info(
+                                "Code change detected but agent is executing - reload pending"
+                            )
+                            print(
+                                "🦆 Agent is currently executing - reload will trigger after completion"
+                            )
+                            self._reload_pending = True
+                            # Don't update _last_modified yet - keep detecting the change
+                        else:
+                            # Safe to reload immediately
+                            self._last_modified = current_mtime
+                            logger.info(
+                                f"Code change detected in {self._watch_file.name} - triggering hot-reload"
+                            )
+                            time.sleep(
+                                0.5
+                            )  # Small delay to ensure file write is complete
+                            self._hot_reload()
+                    else:
+                        # Update timestamp if no change or still in debounce
+                        if not self._reload_pending:
+                            self._last_modified = current_mtime
+
+            except Exception as e:
+                logger.error(f"File watcher error: {e}")
+
+            # Check every 1 second
+            time.sleep(1)
+
+    def _stop_file_watcher(self):
+        """Stop the file watcher"""
+        self._watcher_running = False
+        logger.info("File watcher stopped")
+
+    def _hot_reload(self):
+        """Hot-reload by restarting the entire Python process with fresh code"""
+        logger.info("Hot-reload initiated")
+        print("🦆 Hot-reloading via process restart...")
+
+        try:
+            # Set reload flag to prevent recursive reloads during shutdown
+            self._is_reloading = True
+
+            # Update last_modified before reload to acknowledge the change
+            if hasattr(self, "_watch_file") and self._watch_file.exists():
+                self._last_modified = self._watch_file.stat().st_mtime
 
+            # Reset pending flag
+            self._reload_pending = False
 
-# Initialize
+            # Stop the file watcher
+            if hasattr(self, "_watcher_running"):
+                self._watcher_running = False
+
+            print("🦆 Restarting process with fresh code...")
+
+            # Restart the entire Python process
+            # This ensures all code is freshly loaded
+            os.execv(sys.executable, [sys.executable] + sys.argv)
+
+        except Exception as e:
+            logger.error(f"Hot-reload failed: {e}")
+            print(f"🦆 Hot-reload failed: {e}")
+            print("🦆 Falling back to manual restart")
+            self._is_reloading = False
+
+    def status(self):
+        """Show current status"""
+        return {
+            "model": self.model,
+            "env": self.env_info,
+            "agent_ready": self.agent is not None,
+            "tools": len(self.tools) if hasattr(self, "tools") else 0,
+            "file_watcher": {
+                "enabled": hasattr(self, "_watcher_running") and self._watcher_running,
+                "watching": (
+                    str(self._watch_file) if hasattr(self, "_watch_file") else None
+                ),
+            },
+        }
+
+
+# 🦆 Auto-initialize when imported
 # Check environment variables to control server configuration
+# Also check if --mcp flag is present to skip auto-starting servers
 _auto_start = os.getenv("DEVDUCK_AUTO_START_SERVERS", "true").lower() == "true"
 
 # Disable auto-start if --mcp flag is present (stdio mode)
 if "--mcp" in sys.argv:
     _auto_start = False
 
-_tcp_port = int(os.getenv("DEVDUCK_TCP_PORT", "9999"))
-_ws_port = int(os.getenv("DEVDUCK_WS_PORT", "8080"))
-_mcp_port = int(os.getenv("DEVDUCK_MCP_PORT", "8000"))
-_ipc_socket = os.getenv("DEVDUCK_IPC_SOCKET", None)
-_enable_tcp = os.getenv("DEVDUCK_ENABLE_TCP", "true").lower() == "true"
-_enable_ws = os.getenv("DEVDUCK_ENABLE_WS", "true").lower() == "true"
-_enable_mcp = os.getenv("DEVDUCK_ENABLE_MCP", "true").lower() == "true"
-_enable_ipc = os.getenv("DEVDUCK_ENABLE_IPC", "true").lower() == "true"
-
-devduck = DevDuck(
-    auto_start_servers=_auto_start,
-    tcp_port=_tcp_port,
-    ws_port=_ws_port,
-    mcp_port=_mcp_port,
-    ipc_socket=_ipc_socket,
-    enable_tcp=_enable_tcp,
-    enable_ws=_enable_ws,
-    enable_mcp=_enable_mcp,
-    enable_ipc=_enable_ipc,
-)
+devduck = DevDuck(auto_start_servers=_auto_start)
 
 
+# 🚀 Convenience functions
 def ask(query):
-    """Quick query"""
+    """Quick query interface"""
     return devduck(query)
 
 
+def status():
+    """Quick status check"""
+    return devduck.status()
+
+
+def restart():
+    """Quick restart"""
+    devduck.restart()
+
+
+def hot_reload():
+    """Quick hot-reload without restart"""
+    devduck._hot_reload()
+
+
 def extract_commands_from_history():
     """Extract commonly used commands from shell history for auto-completion."""
     commands = set()
@@ -984,8 +1386,7 @@ def extract_commands_from_history():
 
 
 def interactive():
-    """Interactive REPL with history"""
-    import time
+    """Interactive REPL mode for devduck"""
     from prompt_toolkit import prompt
     from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
     from prompt_toolkit.completion import WordCompleter
@@ -993,10 +1394,14 @@ def interactive():
 
     print("🦆 DevDuck")
     print(f"📝 Logs: {LOG_DIR}")
-    print("Type 'exit' to quit. Prefix with ! for shell commands.")
+    print("Type 'exit', 'quit', or 'q' to quit.")
+    print("Prefix with ! to run shell commands (e.g., ! ls -la)")
     print("-" * 50)
+    logger.info("Interactive mode started")
 
-    history = FileHistory(get_shell_history_file())
+    # Set up prompt_toolkit with history
+    history_file = get_shell_history_file()
+    history = FileHistory(history_file)
 
     # Create completions from common commands and shell history
     base_commands = ["exit", "quit", "q", "help", "clear", "status", "reload"]
@@ -1012,42 +1417,61 @@ def interactive():
 
     while True:
         try:
+            # Use prompt_toolkit for enhanced input with arrow key support
             q = prompt(
                 "\n🦆 ",
                 history=history,
                 auto_suggest=AutoSuggestFromHistory(),
                 completer=completer,
                 complete_while_typing=True,
-                mouse_support=False,
-            ).strip()
+                mouse_support=False,  # breaks scrolling when enabled
+            )
 
             # Reset interrupt count on successful prompt
             interrupt_count = 0
 
+            # Check for exit command
             if q.lower() in ["exit", "quit", "q"]:
+                print("\n🦆 Goodbye!")
                 break
 
-            if not q:
+            # Skip empty inputs
+            if q.strip() == "":
                 continue
 
-            # Shell commands
+            # Handle shell commands with ! prefix
             if q.startswith("!"):
-                if devduck.agent:
-                    devduck._agent_executing = True
-                    result = devduck.agent.tool.shell(
-                        command=q[1:].strip(), timeout=9000
-                    )
-                    devduck._agent_executing = False
-                    append_to_shell_history(q, result["content"][0]["text"])
-
-                    if devduck._reload_pending:
-                        print("🦆 Shell finished - triggering pending reload")
-                        devduck._hot_reload()
+                shell_command = q[1:].strip()
+                try:
+                    if devduck.agent:
+                        devduck._agent_executing = (
+                            True  # Prevent hot-reload during shell execution
+                        )
+                        result = devduck.agent.tool.shell(
+                            command=shell_command, timeout=9000
+                        )
+                        devduck._agent_executing = False
+
+                        # Append shell command to history
+                        append_to_shell_history(q, result["content"][0]["text"])
+
+                        # Check if reload was pending
+                        if devduck._reload_pending:
+                            print(
+                                "🦆 Shell command finished - triggering pending hot-reload..."
+                            )
+                            devduck._hot_reload()
+                    else:
+                        print("🦆 Agent unavailable")
+                except Exception as e:
+                    devduck._agent_executing = False  # Reset on error
+                    print(f"🦆 Shell command error: {e}")
                 continue
 
-            # Agent query
+            # Execute the agent with user input
             result = ask(q)
-            print(result)
+
+            # Append to shell history
             append_to_shell_history(q, str(result))
 
         except KeyboardInterrupt:
@@ -1066,12 +1490,14 @@ def interactive():
                 print("\n🦆 Interrupted. Press Ctrl+C again to exit.")
 
             last_interrupt = current_time
+            continue
         except Exception as e:
             print(f"🦆 Error: {e}")
+            continue
 
 
 def cli():
-    """CLI entry point"""
+    """CLI entry point for pip-installed devduck command"""
     import argparse
 
     parser = argparse.ArgumentParser(
@@ -1079,16 +1505,14 @@ def cli():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  devduck                          # Interactive mode
-  devduck "query"                  # One-shot query
-  devduck --mcp                    # MCP stdio mode
-  devduck --tcp-port 9000          # Custom TCP port
-  devduck --no-tcp --no-ws         # Disable TCP and WebSocket
+  devduck                          # Start interactive mode
+  devduck "your query here"        # One-shot query
+  devduck --mcp                    # MCP stdio mode (for Claude Desktop)
 
 Tool Configuration:
   export DEVDUCK_TOOLS="strands_tools:shell,editor:strands_fun_tools:clipboard"
 
-MCP Config:
+Claude Desktop Config:
   {
     "mcpServers": {
       "devduck": {
@@ -1100,72 +1524,64 @@ MCP Config:
         """,
     )
 
-    parser.add_argument("query", nargs="*", help="Query")
-    parser.add_argument("--mcp", action="store_true", help="MCP stdio mode")
-
-    # Server configuration
-    parser.add_argument(
-        "--tcp-port", type=int, default=9999, help="TCP server port (default: 9999)"
-    )
-    parser.add_argument(
-        "--ws-port",
-        type=int,
-        default=8080,
-        help="WebSocket server port (default: 8080)",
-    )
-    parser.add_argument(
-        "--mcp-port",
-        type=int,
-        default=8000,
-        help="MCP HTTP server port (default: 8000)",
-    )
-    parser.add_argument(
-        "--ipc-socket",
-        type=str,
-        default=None,
-        help="IPC socket path (default: /tmp/devduck_main.sock)",
-    )
+    # Query argument
+    parser.add_argument("query", nargs="*", help="Query to send to the agent")
 
-    # Server enable/disable flags
-    parser.add_argument("--no-tcp", action="store_true", help="Disable TCP server")
-    parser.add_argument("--no-ws", action="store_true", help="Disable WebSocket server")
-    parser.add_argument("--no-mcp", action="store_true", help="Disable MCP server")
-    parser.add_argument("--no-ipc", action="store_true", help="Disable IPC server")
+    # MCP stdio mode flag
     parser.add_argument(
-        "--no-servers",
+        "--mcp",
         action="store_true",
-        help="Disable all servers (no TCP, WebSocket, MCP, or IPC)",
+        help="Start MCP server in stdio mode (for Claude Desktop integration)",
     )
 
     args = parser.parse_args()
 
+    logger.info("CLI mode started")
+
+    # Handle --mcp flag for stdio mode
     if args.mcp:
+        logger.info("Starting MCP server in stdio mode (blocking, foreground)")
         print("🦆 Starting MCP stdio server...", file=sys.stderr)
-        try:
-            devduck.agent.tool.mcp_server(
-                action="start",
-                transport="stdio",
-                expose_agent=True,
-                agent=devduck.agent,
-            )
-        except Exception as e:
-            print(f"🦆 Error: {e}", file=sys.stderr)
+
+        # Don't auto-start HTTP/TCP/WS servers for stdio mode
+        if devduck.agent:
+            try:
+                # Start MCP server in stdio mode - this BLOCKS until terminated
+                devduck.agent.tool.mcp_server(
+                    action="start",
+                    transport="stdio",
+                    expose_agent=True,
+                    agent=devduck.agent,
+                )
+            except Exception as e:
+                logger.error(f"Failed to start MCP stdio server: {e}")
+                print(f"🦆 Error: {e}", file=sys.stderr)
+                sys.exit(1)
+        else:
+            print("🦆 Agent not available", file=sys.stderr)
             sys.exit(1)
         return
 
     if args.query:
-        result = ask(" ".join(args.query))
+        query = " ".join(args.query)
+        logger.info(f"CLI query: {query}")
+        result = ask(query)
         print(result)
     else:
+        # No arguments - start interactive mode
         interactive()
 
 
-# Make module callable
+# 🦆 Make module directly callable: import devduck; devduck("query")
 class CallableModule(sys.modules[__name__].__class__):
+    """Make the module itself callable"""
+
     def __call__(self, query):
+        """Allow direct module call: import devduck; devduck("query")"""
         return ask(query)
 
 
+# Replace module in sys.modules with callable version
 sys.modules[__name__].__class__ = CallableModule