Merge branch 'main' of github.com:NousResearch/hermes-agent into feat/ink-refactor

hermes_cli/banner.py

@@ -295,10 +295,16 @@ def _format_context_length(tokens: int) -> str:
     """Format a token count for display (e.g. 128000 → '128K', 1048576 → '1M')."""
     if tokens >= 1_000_000:
         val = tokens / 1_000_000
-        return f"{val:g}M"
+        rounded = round(val)
+        if abs(val - rounded) < 0.05:
+            return f"{rounded}M"
+        return f"{val:.1f}M"
     elif tokens >= 1_000:
         val = tokens / 1_000
-        return f"{val:g}K"
+        rounded = round(val)
+        if abs(val - rounded) < 0.05:
+            return f"{rounded}K"
+        return f"{val:.1f}K"
     return str(tokens)
 
 

hermes_cli/commands.py

@@ -129,7 +129,7 @@ COMMAND_REGISTRY: list[CommandDef] = [
     CommandDef("commands", "Browse all commands and skills (paginated)", "Info",
                gateway_only=True, args_hint="[page]"),
     CommandDef("help", "Show available commands", "Info"),
-    CommandDef("usage", "Show token usage for the current session", "Info"),
+    CommandDef("usage", "Show token usage and rate limits for the current session", "Info"),
     CommandDef("insights", "Show usage insights and analytics", "Info",
                args_hint="[days]"),
     CommandDef("platforms", "Show gateway/messaging platform status", "Info",

hermes_cli/config.py

@@ -39,6 +39,7 @@ _EXTRA_ENV_KEYS = frozenset({
     "DINGTALK_CLIENT_ID", "DINGTALK_CLIENT_SECRET",
     "FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_ENCRYPT_KEY", "FEISHU_VERIFICATION_TOKEN",
     "WECOM_BOT_ID", "WECOM_SECRET",
+    "BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD",
     "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT",
     "WHATSAPP_MODE", "WHATSAPP_ENABLED",
     "MATTERMOST_HOME_CHANNEL", "MATTERMOST_REPLY_MODE",
@@ -230,6 +231,10 @@ DEFAULT_CONFIG = {
         # (force on/off for all models), or a list of model-name substrings
         # to match (e.g. ["gpt", "codex", "gemini", "qwen"]).
         "tool_use_enforcement": "auto",
+        # Staged inactivity warning: send a warning to the user at this
+        # threshold before escalating to a full timeout.  The warning fires
+        # once per run and does not interrupt the agent.  0 = disable warning.
+        "gateway_timeout_warning": 900,
     },
     
     "terminal": {
@@ -392,6 +397,7 @@ DEFAULT_CONFIG = {
         "show_cost": False,       # Show $ cost in the status bar (off by default)
         "skin": "default",
         "tool_progress_command": False,  # Enable /verbose command in messaging gateway
+        "tool_progress_overrides": {},  # Per-platform overrides: {"signal": "off", "telegram": "all"}
         "tool_preview_length": 0,  # Max chars for tool call previews (0 = no limit, show full paths/commands)
     },
 
@@ -563,7 +569,7 @@ DEFAULT_CONFIG = {
     },
 
     # Config schema version - bump this when adding new required fields
-    "_config_version": 12,
+    "_config_version": 13,
 }
 
 # =============================================================================
@@ -1119,6 +1125,27 @@ OPTIONAL_ENV_VARS = {
         "category": "messaging",
         "advanced": True,
     },
+    "BLUEBUBBLES_SERVER_URL": {
+        "description": "BlueBubbles server URL for iMessage integration (e.g. http://192.168.1.10:1234)",
+        "prompt": "BlueBubbles server URL",
+        "url": "https://bluebubbles.app/",
+        "password": False,
+        "category": "messaging",
+    },
+    "BLUEBUBBLES_PASSWORD": {
+        "description": "BlueBubbles server password (from BlueBubbles Server → Settings → API)",
+        "prompt": "BlueBubbles server password",
+        "url": None,
+        "password": True,
+        "category": "messaging",
+    },
+    "BLUEBUBBLES_ALLOWED_USERS": {
+        "description": "Comma-separated iMessage addresses (email or phone) allowed to use the bot",
+        "prompt": "Allowed iMessage addresses (comma-separated)",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+    },
     "GATEWAY_ALLOW_ALL_USERS": {
         "description": "Allow all users to interact with messaging bots (true/false). Default: false.",
         "prompt": "Allow all users (true/false)",
@@ -1190,7 +1217,7 @@ OPTIONAL_ENV_VARS = {
         "category": "setting",
     },
     "SUDO_PASSWORD": {
-        "description": "Sudo password for terminal commands requiring root access",
+        "description": "Sudo password for terminal commands requiring root access; set to an explicit empty string to try empty without prompting",
         "prompt": "Sudo password",
         "url": None,
         "password": True,
@@ -1674,6 +1701,21 @@ def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, A
                         ep = providers_dict[key]
                         print(f"    → {key}: {ep.get('api', '')}")
 
+    # ── Version 12 → 13: clear dead LLM_MODEL / OPENAI_MODEL from .env ──
+    # These env vars were written by the old setup wizard but nothing reads
+    # them anymore (config.yaml is the sole source of truth since March 2026).
+    # Stale entries cause user confusion — see issue report.
+    if current_ver < 13:
+        for dead_var in ("LLM_MODEL", "OPENAI_MODEL"):
+            try:
+                old_val = get_env_value(dead_var)
+                if old_val:
+                    save_env_value(dead_var, "")
+                    if not quiet:
+                        print(f"  ✓ Cleared {dead_var} from .env (no longer used — config.yaml is source of truth)")
+            except Exception:
+                pass
+
     if current_ver < latest_ver and not quiet:
         print(f"Config version: {current_ver} → {latest_ver}")
     

hermes_cli/dump.py

@@ -0,0 +1,337 @@
+"""
+Dump command for hermes CLI.
+
+Outputs a compact, plain-text summary of the user's Hermes setup
+that can be copy-pasted into Discord/GitHub/Telegram for support context.
+No ANSI colors, no checkmarks — just data.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+from hermes_cli.config import get_hermes_home, get_env_path, get_project_root, load_config
+from hermes_constants import display_hermes_home
+
+
+def _get_git_commit(project_root: Path) -> str:
+    """Return short git commit hash, or '(unknown)'."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short=8", "HEAD"],
+            capture_output=True, text=True, timeout=5,
+            cwd=str(project_root),
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return "(unknown)"
+
+
+def _key_present(name: str) -> str:
+    """Return 'set' or 'not set' for an env var."""
+    return "set" if os.getenv(name) else "not set"
+
+
+def _redact(value: str) -> str:
+    """Redact all but first 4 and last 4 chars."""
+    if not value:
+        return ""
+    if len(value) < 12:
+        return "***"
+    return value[:4] + "..." + value[-4:]
+
+
+def _gateway_status() -> str:
+    """Return a short gateway status string."""
+    if sys.platform.startswith("linux"):
+        try:
+            from hermes_cli.gateway import get_service_name
+            svc = get_service_name()
+        except Exception:
+            svc = "hermes-gateway"
+        try:
+            r = subprocess.run(
+                ["systemctl", "--user", "is-active", svc],
+                capture_output=True, text=True, timeout=5,
+            )
+            return "running (systemd)" if r.stdout.strip() == "active" else "stopped"
+        except Exception:
+            return "unknown"
+    elif sys.platform == "darwin":
+        try:
+            from hermes_cli.gateway import get_launchd_label
+            r = subprocess.run(
+                ["launchctl", "list", get_launchd_label()],
+                capture_output=True, text=True, timeout=5,
+            )
+            return "loaded (launchd)" if r.returncode == 0 else "not loaded"
+        except Exception:
+            return "unknown"
+    return "N/A"
+
+
+def _count_skills(hermes_home: Path) -> int:
+    """Count installed skills."""
+    skills_dir = hermes_home / "skills"
+    if not skills_dir.is_dir():
+        return 0
+    count = 0
+    for item in skills_dir.rglob("SKILL.md"):
+        count += 1
+    return count
+
+
+def _count_mcp_servers(config: dict) -> int:
+    """Count configured MCP servers."""
+    mcp = config.get("mcp", {})
+    servers = mcp.get("servers", {})
+    return len(servers)
+
+
+def _cron_summary(hermes_home: Path) -> str:
+    """Return cron jobs summary."""
+    jobs_file = hermes_home / "cron" / "jobs.json"
+    if not jobs_file.exists():
+        return "0"
+    try:
+        with open(jobs_file, encoding="utf-8") as f:
+            data = json.load(f)
+        jobs = data.get("jobs", [])
+        active = sum(1 for j in jobs if j.get("enabled", True))
+        return f"{active} active / {len(jobs)} total"
+    except Exception:
+        return "(error reading)"
+
+
+def _configured_platforms() -> list[str]:
+    """Return list of configured messaging platform names."""
+    checks = {
+        "telegram": "TELEGRAM_BOT_TOKEN",
+        "discord": "DISCORD_BOT_TOKEN",
+        "slack": "SLACK_BOT_TOKEN",
+        "whatsapp": "WHATSAPP_ENABLED",
+        "signal": "SIGNAL_HTTP_URL",
+        "email": "EMAIL_ADDRESS",
+        "sms": "TWILIO_ACCOUNT_SID",
+        "matrix": "MATRIX_HOMESERVER_URL",
+        "mattermost": "MATTERMOST_URL",
+        "homeassistant": "HASS_TOKEN",
+        "dingtalk": "DINGTALK_CLIENT_ID",
+        "feishu": "FEISHU_APP_ID",
+        "wecom": "WECOM_BOT_ID",
+    }
+    return [name for name, env in checks.items() if os.getenv(env)]
+
+
+def _memory_provider(config: dict) -> str:
+    """Return the active memory provider name."""
+    mem = config.get("memory", {})
+    provider = mem.get("provider", "")
+    return provider if provider else "built-in"
+
+
+def _get_model_and_provider(config: dict) -> tuple[str, str]:
+    """Extract model and provider from config."""
+    model_cfg = config.get("model", "")
+    if isinstance(model_cfg, dict):
+        model = model_cfg.get("default") or model_cfg.get("model") or model_cfg.get("name") or "(not set)"
+        provider = model_cfg.get("provider") or "(auto)"
+    elif isinstance(model_cfg, str):
+        model = model_cfg or "(not set)"
+        provider = "(auto)"
+    else:
+        model = "(not set)"
+        provider = "(auto)"
+    return model, provider
+
+
+def _config_overrides(config: dict) -> dict[str, str]:
+    """Find non-default config values worth reporting.
+    
+    Returns a flat dict of dotpath -> value for interesting overrides.
+    """
+    from hermes_cli.config import DEFAULT_CONFIG
+
+    overrides = {}
+
+    # Sections with interesting user-facing overrides
+    interesting_paths = [
+        ("agent", "max_turns"),
+        ("agent", "gateway_timeout"),
+        ("agent", "tool_use_enforcement"),
+        ("terminal", "backend"),
+        ("terminal", "docker_image"),
+        ("terminal", "persistent_shell"),
+        ("browser", "allow_private_urls"),
+        ("compression", "enabled"),
+        ("compression", "threshold"),
+        ("display", "streaming"),
+        ("display", "skin"),
+        ("display", "show_reasoning"),
+        ("smart_model_routing", "enabled"),
+        ("privacy", "redact_pii"),
+        ("tts", "provider"),
+    ]
+
+    for section, key in interesting_paths:
+        default_section = DEFAULT_CONFIG.get(section, {})
+        user_section = config.get(section, {})
+        if not isinstance(default_section, dict) or not isinstance(user_section, dict):
+            continue
+        default_val = default_section.get(key)
+        user_val = user_section.get(key)
+        if user_val is not None and user_val != default_val:
+            overrides[f"{section}.{key}"] = str(user_val)
+
+    # Toolsets (if different from default)
+    default_toolsets = DEFAULT_CONFIG.get("toolsets", [])
+    user_toolsets = config.get("toolsets", [])
+    if user_toolsets != default_toolsets:
+        overrides["toolsets"] = str(user_toolsets)
+
+    # Fallback providers
+    fallbacks = config.get("fallback_providers", [])
+    if fallbacks:
+        overrides["fallback_providers"] = str(fallbacks)
+
+    return overrides
+
+
+def run_dump(args):
+    """Output a compact, copy-pasteable setup summary."""
+    show_keys = getattr(args, "show_keys", False)
+
+    # Load env from .env file so key checks work
+    from dotenv import load_dotenv
+    env_path = get_env_path()
+    if env_path.exists():
+        try:
+            load_dotenv(env_path, encoding="utf-8")
+        except UnicodeDecodeError:
+            load_dotenv(env_path, encoding="latin-1")
+    # Also try project .env as dev fallback
+    load_dotenv(get_project_root() / ".env", override=False, encoding="utf-8")
+
+    project_root = get_project_root()
+    hermes_home = get_hermes_home()
+
+    try:
+        from hermes_cli import __version__, __release_date__
+    except ImportError:
+        __version__ = "(unknown)"
+        __release_date__ = ""
+
+    commit = _get_git_commit(project_root)
+
+    try:
+        config = load_config()
+    except Exception:
+        config = {}
+
+    model, provider = _get_model_and_provider(config)
+
+    # Profile
+    try:
+        from hermes_cli.profiles import get_active_profile_name
+        profile = get_active_profile_name() or "(default)"
+    except Exception:
+        profile = "(default)"
+
+    # Terminal backend
+    terminal_cfg = config.get("terminal", {})
+    backend = terminal_cfg.get("backend", "local")
+
+    # OpenAI SDK version
+    try:
+        import openai
+        openai_ver = openai.__version__
+    except ImportError:
+        openai_ver = "not installed"
+
+    # OS info
+    os_info = f"{platform.system()} {platform.release()} {platform.machine()}"
+
+    lines = []
+    lines.append("--- hermes dump ---")
+    ver_str = f"{__version__}"
+    if __release_date__:
+        ver_str += f" ({__release_date__})"
+    ver_str += f" [{commit}]"
+    lines.append(f"version:          {ver_str}")
+    lines.append(f"os:               {os_info}")
+    lines.append(f"python:           {sys.version.split()[0]}")
+    lines.append(f"openai_sdk:       {openai_ver}")
+    lines.append(f"profile:          {profile}")
+    lines.append(f"hermes_home:      {display_hermes_home()}")
+    lines.append(f"model:            {model}")
+    lines.append(f"provider:         {provider}")
+    lines.append(f"terminal:         {backend}")
+
+    # API keys
+    lines.append("")
+    lines.append("api_keys:")
+    api_keys = [
+        ("OPENROUTER_API_KEY", "openrouter"),
+        ("OPENAI_API_KEY", "openai"),
+        ("ANTHROPIC_API_KEY", "anthropic"),
+        ("ANTHROPIC_TOKEN", "anthropic_token"),
+        ("NOUS_API_KEY", "nous"),
+        ("GLM_API_KEY", "glm/zai"),
+        ("ZAI_API_KEY", "zai"),
+        ("KIMI_API_KEY", "kimi"),
+        ("MINIMAX_API_KEY", "minimax"),
+        ("DEEPSEEK_API_KEY", "deepseek"),
+        ("DASHSCOPE_API_KEY", "dashscope"),
+        ("HF_TOKEN", "huggingface"),
+        ("AI_GATEWAY_API_KEY", "ai_gateway"),
+        ("OPENCODE_ZEN_API_KEY", "opencode_zen"),
+        ("OPENCODE_GO_API_KEY", "opencode_go"),
+        ("KILOCODE_API_KEY", "kilocode"),
+        ("FIRECRAWL_API_KEY", "firecrawl"),
+        ("TAVILY_API_KEY", "tavily"),
+        ("BROWSERBASE_API_KEY", "browserbase"),
+        ("FAL_KEY", "fal"),
+        ("ELEVENLABS_API_KEY", "elevenlabs"),
+        ("GITHUB_TOKEN", "github"),
+    ]
+
+    for env_var, label in api_keys:
+        val = os.getenv(env_var, "")
+        if show_keys and val:
+            display = _redact(val)
+        else:
+            display = "set" if val else "not set"
+        lines.append(f"  {label:<20} {display}")
+
+    # Features summary
+    lines.append("")
+    lines.append("features:")
+
+    toolsets = config.get("toolsets", ["hermes-cli"])
+    lines.append(f"  toolsets:           {', '.join(toolsets) if toolsets else '(default)'}")
+    lines.append(f"  mcp_servers:        {_count_mcp_servers(config)}")
+    lines.append(f"  memory_provider:    {_memory_provider(config)}")
+    lines.append(f"  gateway:            {_gateway_status()}")
+
+    platforms = _configured_platforms()
+    lines.append(f"  platforms:          {', '.join(platforms) if platforms else 'none'}")
+    lines.append(f"  cron_jobs:          {_cron_summary(hermes_home)}")
+    lines.append(f"  skills:             {_count_skills(hermes_home)}")
+
+    # Config overrides (non-default values)
+    overrides = _config_overrides(config)
+    if overrides:
+        lines.append("")
+        lines.append("config_overrides:")
+        for key, val in overrides.items():
+            lines.append(f"  {key}: {val}")
+
+    lines.append("--- end dump ---")
+
+    output = "\n".join(lines)
+    print(output)

hermes_cli/gateway.py

@@ -1588,6 +1588,34 @@ _PLATFORMS = [
              "help": "Chat ID for scheduled results and notifications."},
         ],
     },
+    {
+        "key": "bluebubbles",
+        "label": "BlueBubbles (iMessage)",
+        "emoji": "💬",
+        "token_var": "BLUEBUBBLES_SERVER_URL",
+        "setup_instructions": [
+            "1. Install BlueBubbles on a Mac that will act as your iMessage server:",
+            "   https://bluebubbles.app/",
+            "2. Complete the BlueBubbles setup wizard — sign in with your Apple ID",
+            "3. In BlueBubbles Settings → API, note the Server URL and password",
+            "4. The server URL is typically http://<your-mac-ip>:1234",
+            "5. Hermes connects via the BlueBubbles REST API and receives",
+            "   incoming messages via a local webhook",
+            "6. To authorize users, use DM pairing: hermes pairing generate bluebubbles",
+            "   Share the code — the user sends it via iMessage to get approved",
+        ],
+        "vars": [
+            {"name": "BLUEBUBBLES_SERVER_URL", "prompt": "BlueBubbles server URL (e.g. http://192.168.1.10:1234)", "password": False,
+             "help": "The URL shown in BlueBubbles Settings → API."},
+            {"name": "BLUEBUBBLES_PASSWORD", "prompt": "BlueBubbles server password", "password": True,
+             "help": "The password shown in BlueBubbles Settings → API."},
+            {"name": "BLUEBUBBLES_ALLOWED_USERS", "prompt": "Pre-authorized phone numbers or iMessage IDs (comma-separated, or leave empty for DM pairing)", "password": False,
+             "is_allowlist": True,
+             "help": "Optional — pre-authorize specific users. Leave empty to use DM pairing instead (recommended)."},
+            {"name": "BLUEBUBBLES_HOME_CHANNEL", "prompt": "Home channel (phone number or iMessage ID for cron/notifications, or empty)", "password": False,
+             "help": "Phone number or Apple ID to deliver cron results and notifications to."},
+        ],
+    },
 ]
 
 

hermes_cli/main.py

@@ -1585,7 +1585,11 @@ def _model_flow_custom(config):
             f"Hermes will still save it."
         )
         if probe.get("suggested_base_url"):
-            print(f"  If this server expects /v1, try base URL: {probe['suggested_base_url']}")
+            suggested = probe["suggested_base_url"]
+            if suggested.endswith("/v1"):
+                print(f"  If this server expects /v1 in the path, try base URL: {suggested}")
+            else:
+                print(f"  If /v1 should not be in the base URL, try: {suggested}")
 
     # Select model — use probe results when available, fall back to manual input
     model_name = ""
@@ -2750,6 +2754,12 @@ def cmd_doctor(args):
     run_doctor(args)
 
 
+def cmd_dump(args):
+    """Dump setup summary for support/debugging."""
+    from hermes_cli.dump import run_dump
+    run_dump(args)
+
+
 def cmd_config(args):
     """Configuration management."""
     from hermes_cli.config import config_command
@@ -4843,6 +4853,22 @@ For more help on a command:
         help="Attempt to fix issues automatically"
     )
     doctor_parser.set_defaults(func=cmd_doctor)
+
+    # =========================================================================
+    # dump command
+    # =========================================================================
+    dump_parser = subparsers.add_parser(
+        "dump",
+        help="Dump setup summary for support/debugging",
+        description="Output a compact, plain-text summary of your Hermes setup "
+                    "that can be copy-pasted into Discord/GitHub for support context"
+    )
+    dump_parser.add_argument(
+        "--show-keys",
+        action="store_true",
+        help="Show redacted API key prefixes (first/last 4 chars) instead of just set/not set"
+    )
+    dump_parser.set_defaults(func=cmd_dump)
     
     # =========================================================================
     # config command

hermes_cli/model_switch.py

@@ -537,8 +537,11 @@ def switch_model(
                     )
             else:
                 # --- Step c: On aggregator, convert vendor:model to vendor/model ---
+                # Only convert when there's no slash — a slash means the name
+                # is already in vendor/model format and the colon is a variant
+                # tag (:free, :extended, :fast) that must be preserved.
                 colon_pos = raw_input.find(":")
-                if colon_pos > 0 and is_aggregator(current_provider):
+                if colon_pos > 0 and "/" not in raw_input and is_aggregator(current_provider):
                     left = raw_input[:colon_pos].strip().lower()
                     right = raw_input[colon_pos + 1:].strip()
                     if left and right:

hermes_cli/models.py

@@ -1532,7 +1532,7 @@ def probe_api_models(
 
     return {
         "models": None,
-        "probed_url": tried[-1] if tried else normalized.rstrip("/") + "/models",
+        "probed_url": tried[0] if tried else normalized.rstrip("/") + "/models",
         "resolved_base_url": normalized,
         "suggested_base_url": alternate_base if alternate_base != normalized else None,
         "used_fallback": False,

hermes_cli/profiles.py

@@ -102,7 +102,7 @@ _RESERVED_NAMES = frozenset({
 # Hermes subcommands that cannot be used as profile names/aliases
 _HERMES_SUBCOMMANDS = frozenset({
     "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
-    "status", "cron", "doctor", "config", "pairing", "skills", "tools",
+    "status", "cron", "doctor", "dump", "config", "pairing", "skills", "tools",
     "mcp", "sessions", "insights", "version", "update", "uninstall",
     "profile", "plugins", "honcho", "acp",
 })
@@ -1007,7 +1007,7 @@ _hermes_completion() {
 
     # Top-level subcommands
     if [[ "$COMP_CWORD" == 1 ]]; then
-        local commands="chat model gateway setup status cron doctor config skills tools mcp sessions profile update version"
+        local commands="chat model gateway setup status cron doctor dump config skills tools mcp sessions profile update version"
         COMPREPLY=($(compgen -W "$commands" -- "$cur"))
     fi
 }
@@ -1032,7 +1032,7 @@ _hermes() {
     _arguments \\
         '-p[Profile name]:profile:($profiles)' \\
         '--profile[Profile name]:profile:($profiles)' \\
-        '1:command:(chat model gateway setup status cron doctor config skills tools mcp sessions profile update version)' \\
+        '1:command:(chat model gateway setup status cron doctor dump config skills tools mcp sessions profile update version)' \\
         '*::arg:->args'
 
     case $words[1] in

hermes_cli/setup.py

@@ -2167,6 +2167,71 @@ def _setup_whatsapp():
         print_info("or personal self-chat) and pair via QR code.")
 
 
+def _setup_bluebubbles():
+    """Configure BlueBubbles iMessage gateway."""
+    print_header("BlueBubbles (iMessage)")
+    existing = get_env_value("BLUEBUBBLES_SERVER_URL")
+    if existing:
+        print_info("BlueBubbles: already configured")
+        if not prompt_yes_no("Reconfigure BlueBubbles?", False):
+            return
+
+    print_info("Connects Hermes to iMessage via BlueBubbles — a free, open-source")
+    print_info("macOS server that bridges iMessage to any device.")
+    print_info("   Requires a Mac running BlueBubbles Server v1.0.0+")
+    print_info("   Download: https://bluebubbles.app/")
+    print()
+    print_info("In BlueBubbles Server → Settings → API, note your Server URL and Password.")
+    print()
+
+    server_url = prompt("BlueBubbles server URL (e.g. http://192.168.1.10:1234)")
+    if not server_url:
+        print_warning("Server URL is required — skipping BlueBubbles setup")
+        return
+    save_env_value("BLUEBUBBLES_SERVER_URL", server_url.rstrip("/"))
+
+    password = prompt("BlueBubbles server password", password=True)
+    if not password:
+        print_warning("Password is required — skipping BlueBubbles setup")
+        return
+    save_env_value("BLUEBUBBLES_PASSWORD", password)
+    print_success("BlueBubbles credentials saved")
+
+    print()
+    print_info("🔒 Security: Restrict who can message your bot")
+    print_info("   Use iMessage addresses: email (user@icloud.com) or phone (+15551234567)")
+    print()
+    allowed_users = prompt("Allowed iMessage addresses (comma-separated, leave empty for open access)")
+    if allowed_users:
+        save_env_value("BLUEBUBBLES_ALLOWED_USERS", allowed_users.replace(" ", ""))
+        print_success("BlueBubbles allowlist configured")
+    else:
+        print_info("⚠️  No allowlist set — anyone who can iMessage you can use the bot!")
+
+    print()
+    print_info("📬 Home Channel: phone or email for cron job delivery and notifications.")
+    print_info("   You can also set this later with /set-home in your iMessage chat.")
+    home_channel = prompt("Home channel address (leave empty to set later)")
+    if home_channel:
+        save_env_value("BLUEBUBBLES_HOME_CHANNEL", home_channel)
+
+    print()
+    print_info("Advanced settings (defaults are fine for most setups):")
+    if prompt_yes_no("Configure webhook listener settings?", False):
+        webhook_port = prompt("Webhook listener port (default: 8645)")
+        if webhook_port:
+            try:
+                save_env_value("BLUEBUBBLES_WEBHOOK_PORT", str(int(webhook_port)))
+                print_success(f"Webhook port set to {webhook_port}")
+            except ValueError:
+                print_warning("Invalid port number, using default 8645")
+
+    print()
+    print_info("Requires the BlueBubbles Private API helper for typing indicators,")
+    print_info("read receipts, and tapback reactions. Basic messaging works without it.")
+    print_info("   Install: https://docs.bluebubbles.app/helper-bundle/installation")
+
+
 def _setup_webhooks():
     """Configure webhook integration."""
     print_header("Webhooks")
@@ -2221,6 +2286,7 @@ _GATEWAY_PLATFORMS = [
     ("Matrix", "MATRIX_ACCESS_TOKEN", _setup_matrix),
     ("Mattermost", "MATTERMOST_TOKEN", _setup_mattermost),
     ("WhatsApp", "WHATSAPP_ENABLED", _setup_whatsapp),
+    ("BlueBubbles (iMessage)", "BLUEBUBBLES_SERVER_URL", _setup_bluebubbles),
     ("Webhooks (GitHub, GitLab, etc.)", "WEBHOOK_ENABLED", _setup_webhooks),
 ]
 
@@ -2264,6 +2330,7 @@ def setup_gateway(config: dict):
         or get_env_value("MATRIX_ACCESS_TOKEN")
         or get_env_value("MATRIX_PASSWORD")
         or get_env_value("WHATSAPP_ENABLED")
+        or get_env_value("BLUEBUBBLES_SERVER_URL")
         or get_env_value("WEBHOOK_ENABLED")
     )
     if any_messaging:
@@ -2283,6 +2350,8 @@ def setup_gateway(config: dict):
             missing_home.append("Discord")
         if get_env_value("SLACK_BOT_TOKEN") and not get_env_value("SLACK_HOME_CHANNEL"):
             missing_home.append("Slack")
+        if get_env_value("BLUEBUBBLES_SERVER_URL") and not get_env_value("BLUEBUBBLES_HOME_CHANNEL"):
+            missing_home.append("BlueBubbles")
 
         if missing_home:
             print()
@@ -2453,6 +2522,8 @@ def _get_section_config_summary(config: dict, section_key: str) -> Optional[str]
             platforms.append("WhatsApp")
         if get_env_value("SIGNAL_ACCOUNT"):
             platforms.append("Signal")
+        if get_env_value("BLUEBUBBLES_SERVER_URL"):
+            platforms.append("BlueBubbles")
         if platforms:
             return ", ".join(platforms)
         return None  # No platforms configured — section must run

hermes_cli/skills_config.py

@@ -23,6 +23,7 @@ PLATFORMS = {
     "slack":    "💼 Slack",
     "whatsapp": "📱 WhatsApp",
     "signal":   "📡 Signal",
+    "bluebubbles": "💬 BlueBubbles",
     "email":    "📧 Email",
     "homeassistant": "🏠 Home Assistant",
     "mattermost": "💬 Mattermost",

hermes_cli/status.py

@@ -302,6 +302,7 @@ def show_status(args):
         "DingTalk": ("DINGTALK_CLIENT_ID", None),
         "Feishu": ("FEISHU_APP_ID", "FEISHU_HOME_CHANNEL"),
         "WeCom": ("WECOM_BOT_ID", "WECOM_HOME_CHANNEL"),
+        "BlueBubbles": ("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_HOME_CHANNEL"),
     }
     
     for name, (token_var, home_var) in platforms.items():

hermes_cli/tools_config.py

@@ -126,6 +126,7 @@ PLATFORMS = {
     "slack":    {"label": "💼 Slack",      "default_toolset": "hermes-slack"},
     "whatsapp": {"label": "📱 WhatsApp",   "default_toolset": "hermes-whatsapp"},
     "signal":   {"label": "📡 Signal",     "default_toolset": "hermes-signal"},
+    "bluebubbles": {"label": "💙 BlueBubbles", "default_toolset": "hermes-bluebubbles"},
     "homeassistant": {"label": "🏠 Home Assistant", "default_toolset": "hermes-homeassistant"},
     "email":    {"label": "📧 Email",      "default_toolset": "hermes-email"},
     "matrix":   {"label": "💬 Matrix",     "default_toolset": "hermes-matrix"},