honcho-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-23
+
+### Added
+
+- `honcho install` finds the AI agents on this machine, shows which already have Honcho, and offers a checkbox picker. Claude Code, Hermes Agent, OpenClaw and Pi get their Honcho plugin and Codex the Honcho MCP server and skill, each through the agent's own commands and the API key in `~/.honcho/config.json`. If that file has no `peerName` yet, it asks what agents should call you (default: your OS username) and saves it there for every agent to share. Other agents it finds link to their setup guide, and `honcho install grok-bot` copies a setup prompt for Grok Bot. Run from inside Claude Code or Codex, it sets up that agent without prompting. `honcho install all` or `honcho install <id>...` skips the picker; `--list` and `--json` only report
+
+### Security
+
+- Requires `certifi` 2026.10.19 or newer, the first CA bundle without the emSign root behind the compromised eMudhra intermediates. Upgrading the CLI now upgrades the bundle it verifies TLS with, including under `pip install -U`, which otherwise leaves dependencies alone
+- A local stack keeps the Honcho image it pinned on first `honcho start`, so a stack set up before this release can still be running an image with the old bundle. Move to the patched image with `honcho stop`, then `honcho start --image ghcr.io/plastic-labs/honcho:v3.4.1`; data is kept
+
 ## [0.2.1] - 2026-10-20
 
 ### Fixed

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: honcho-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: A terminal for Honcho — memory that reasons.
 Project-URL: Homepage, https://github.com/plastic-labs/honcho
 Project-URL: Repository, https://github.com/plastic-labs/honcho
@@ -13,9 +13,11 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
+Requires-Dist: certifi>=2026.10.19
 Requires-Dist: click>=8.0.0
 Requires-Dist: honcho-ai>=2.5.0
 Requires-Dist: httpx>=0.27.0
+Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: dev
@@ -50,6 +52,7 @@ uv tool install honcho-cli
 honcho init                 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
 honcho start --setup basic  # local stack: LLM provider key + Docker
 honcho doctor               # verify config + connectivity
+honcho install              # find your AI agents and add Honcho to them
 honcho                      # show banner + command list
 ```
 
@@ -92,6 +95,7 @@ honcho stop --wipe     # also delete volumes
 | `honcho stop` | Stop the local stack. `--wipe` also deletes volumes. |
 | `honcho status` | Show every local stack (or `--profile` for one). |
 | `honcho doctor` | Health check: config, connectivity, workspace, peer, queue |
+| `honcho install` | Find the AI agents on this machine, show which already have Honcho, and pick which to add it to. Claude Code, Hermes, OpenClaw and Pi get their Honcho plugin and Codex the Honcho MCP server, each through the agent's own commands and the API key in `~/.honcho/config.json`. Other agents link to their setup guide; `honcho install grok-bot` copies a prompt to paste into a Grok Bot. `honcho install all` or `honcho install <id>...` skips the picker; `--list` only reports. |
 
 ### Workspaces
 

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/README.md

@@ -25,6 +25,7 @@ uv tool install honcho-cli
 honcho init                 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
 honcho start --setup basic  # local stack: LLM provider key + Docker
 honcho doctor               # verify config + connectivity
+honcho install              # find your AI agents and add Honcho to them
 honcho                      # show banner + command list
 ```
 
@@ -67,6 +68,7 @@ honcho stop --wipe     # also delete volumes
 | `honcho stop` | Stop the local stack. `--wipe` also deletes volumes. |
 | `honcho status` | Show every local stack (or `--profile` for one). |
 | `honcho doctor` | Health check: config, connectivity, workspace, peer, queue |
+| `honcho install` | Find the AI agents on this machine, show which already have Honcho, and pick which to add it to. Claude Code, Hermes, OpenClaw and Pi get their Honcho plugin and Codex the Honcho MCP server, each through the agent's own commands and the API key in `~/.honcho/config.json`. Other agents link to their setup guide; `honcho install grok-bot` copies a prompt to paste into a Grok Bot. `honcho install all` or `honcho install <id>...` skips the picker; `--list` only reports. |
 
 ### Workspaces
 

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "honcho-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "A terminal for Honcho — memory that reasons."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,6 +22,9 @@ dependencies = [
     "honcho-ai>=2.5.0",
     "rich>=13.0.0",
     "httpx>=0.27.0",
+    "questionary>=2.1.0",
+    # First bundle without emSign ECC Root CA - G3 (eMudhra intermediate key compromise)
+    "certifi>=2026.10.19",
 ]
 
 [project.urls]

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/src/honcho_cli/__init__.py

@@ -1,3 +1,3 @@
 """Honcho CLI — a terminal for Honcho."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/src/honcho_cli/_help.py

@@ -70,6 +70,7 @@ def print_welcome(console: Console) -> None:
         ("honcho init",                  "configure API key and server URL"),
         ("honcho start [--setup basic]", "run a local Honcho stack (Docker)"),
         ("honcho doctor",                "verify connection and workspace health"),
+        ("honcho install",               "find your AI agents and add Honcho to them"),
     ]
     stack_rows = [
         ("honcho start / status / stop",          "lifecycle for the local Docker stack"),

honcho_cli-0.3.0/src/honcho_cli/agents.py

@@ -0,0 +1,401 @@
+"""Which AI agents are on this machine, and how ``honcho install`` adds Honcho to each.
+
+Mirrors the "General agents" and "Coding agents" sections of the docs
+integrations catalog (``docs/snippets/integrations-catalog.jsx``).
+
+Finding an agent works like vercel-labs/skills: a plain filesystem check, its
+binary on PATH or its config directory on disk, plus the variables an agent
+sets when it is the one running ``honcho install``. Nothing is parsed.
+``honcho install`` never edits an agent's config files either; it only runs
+the agent's own commands. Three kinds:
+
+- ``plugin``: the agent has an official Honcho plugin, installed with the
+  agent's own plugin commands.
+- ``mcp``: the hosted Honcho MCP server, registered with the agent's own
+  ``mcp add`` command, plus the honcho-memory skill.
+- ``suggest``: ``honcho install`` changes nothing and points at the setup guide.
+  Cloud agents (Grok Bot) get a setup prompt to paste instead.
+
+Whether Honcho is already set up comes from asking the agent itself (its
+``plugin list`` / ``mcp get`` / ``config get`` command), never from reading
+its files.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+DOCS = "https://honcho.dev/docs/v3/guides"
+CATALOG_URL = f"{DOCS}/overview"
+MCP_DOCS = f"{DOCS}/integrations/mcp"
+MCP_URL = "https://mcp.honcho.dev"
+
+GROK_BOT_PROMPT = (
+    "Set up Honcho memory using the plugin at "
+    "https://github.com/plastic-labs/honcho/tree/main/integrations/cursor: "
+    "connect its MCP server (https://mcp.honcho.dev, sign in with OAuth), "
+    "install its skills, then run honcho-setup."
+)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """What install commands need from ``~/.honcho/config.json``."""
+
+    api_key: str
+    base_url: str
+
+    @property
+    def hosted(self) -> bool:
+        return self.base_url.rstrip("/") == "https://api.honcho.dev"
+
+
+# --------------------------------------------------------------------------- #
+# locations
+
+
+def _home() -> Path:
+    return Path.home()
+
+
+def _env_path(var: str, default: Path) -> Path:
+    val = os.environ.get(var)
+    return Path(val).expanduser() if val else default
+
+
+def _exists(path: Path) -> bool:
+    """``Path.exists`` that treats an unreadable parent as missing (3.11/3.12 raise)."""
+    try:
+        return path.exists()
+    except OSError:
+        return False
+
+
+def _app_support() -> Path:
+    """Per-user application data dir: macOS Application Support, Windows APPDATA, Linux XDG."""
+    if sys.platform == "darwin":
+        return _home() / "Library" / "Application Support"
+    if sys.platform == "win32":
+        return _env_path("APPDATA", _home() / "AppData" / "Roaming")
+    return _env_path("XDG_CONFIG_HOME", _home() / ".config")
+
+
+def _xdg_config() -> Path:
+    return _env_path("XDG_CONFIG_HOME", _home() / ".config")
+
+
+def _vscode_user() -> Path:
+    return _app_support() / "Code" / "User"
+
+
+def _hermes_home() -> Path:
+    return _env_path("HERMES_HOME", _home() / ".hermes")
+
+
+def _zed_dir() -> Path:
+    return _app_support() / "Zed" if sys.platform == "win32" else _xdg_config() / "zed"
+
+
+def _goose_dir() -> Path:
+    if sys.platform == "win32":
+        return _app_support() / "Block" / "goose" / "config"
+    return _xdg_config() / "goose"
+
+
+def _dsh_present() -> bool:
+    """``dsh`` is also Debian's distributed shell; only count DeepSeek's npm one."""
+    exe = shutil.which("dsh")
+    if not exe:
+        return False
+    try:
+        return "deepseek" in os.path.realpath(exe).lower()
+    except OSError:
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# asking an agent whether Honcho is set up
+
+
+def _output(argv: list[str]) -> tuple[int, str] | None:
+    """Run one of the agent's own status commands. ``None`` when it couldn't run."""
+    exe = shutil.which(argv[0])
+    if not exe:
+        return None
+    try:
+        proc = subprocess.run(
+            [exe, *argv[1:]], capture_output=True, text=True, errors="replace", timeout=60, stdin=subprocess.DEVNULL
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return proc.returncode, proc.stdout
+
+
+def _json_list(out: tuple[int, str] | None, key: str | None = None) -> list[dict[str, object]] | None:
+    """The list of objects a ``--json`` status command printed, or None if it didn't."""
+    if out is None or out[0] != 0:
+        return None
+    try:
+        data = json.loads(out[1])
+    except ValueError:
+        return None
+    if key is not None:
+        data = data.get(key) if isinstance(data, dict) else None
+    return [d for d in data if isinstance(d, dict)] if isinstance(data, list) else None
+
+
+def _claude_code_has_honcho() -> bool | None:
+    out = _output(["claude", "plugin", "list", "--json"])
+    return None if out is None or out[0] != 0 else "honcho@honcho" in out[1]
+
+
+def _codex_has_honcho() -> bool | None:
+    out = _output(["codex", "mcp", "get", "honcho"])
+    return None if out is None else out[0] == 0
+
+
+def _hermes_has_honcho() -> bool | None:
+    out = _output(["hermes", "config", "get", "memory.provider"])
+    return None if out is None or out[0] != 0 else out[1].strip() == "honcho"
+
+
+def _hermes_has_plugin() -> bool:
+    plugins = _json_list(_output(["hermes", "plugins", "list", "--json", "--user"]))
+    return any(p.get("name") == "honcho" for p in plugins or [])
+
+
+def _openclaw_has_honcho() -> bool | None:
+    plugins = _json_list(_output(["openclaw", "plugins", "list", "--json"]), key="plugins")
+    return None if plugins is None else any(p.get("id") == "openclaw-honcho" for p in plugins)
+
+
+def _pi_has_honcho() -> bool | None:
+    out = _output(["pi", "list"])
+    return None if out is None or out[0] != 0 else "@honcho-ai/pi-honcho" in out[1]
+
+
+# --------------------------------------------------------------------------- #
+# install commands — each is the agent's own CLI
+
+
+class Quiet(list[str]):
+    """An install step that isn't the agent's own CLI; its output shows only if it fails."""
+
+
+def _claude_code_install(_: Credentials) -> list[list[str]]:
+    return [
+        ["claude", "plugin", "marketplace", "add", "plastic-labs/claude-honcho"],
+        ["claude", "plugin", "install", "honcho@honcho"],
+    ]
+
+
+def _codex_install(creds: Credentials) -> list[list[str]]:
+    # `codex mcp add --url` reads a bearer token only from an env var, so the
+    # key from the config goes in mcp-remote's header instead. This entry is the
+    # one copy of the key outside ~/.honcho/config.json.
+    return [
+        [
+            "codex", "mcp", "add", "honcho", "--",
+            "npx", "-y", "mcp-remote", MCP_URL,
+            "--header", f"Authorization:Bearer {creds.api_key}",
+            "--header", "X-Honcho-Plugin:codex",
+        ],
+        # the skill that tells Codex when to recall and record, installed by vercel-labs/skills
+        Quiet(["npx", "-y", "skills", "add", "plastic-labs/honcho", "--skill", "honcho-memory",
+               "--agent", "codex", "--global", "--yes"]),
+    ]
+
+
+def _hermes_install(_: Credentials) -> list[list[str]]:
+    # The plugin reads the key from ~/.honcho/config.json, so switching the
+    # provider on replaces Hermes' interactive `memory setup`.
+    enable = ["hermes", "config", "set", "memory.provider", "honcho"]
+    if _hermes_has_plugin():
+        return [enable]
+    return [["hermes", "plugins", "install", "honcho", "--enable", "--yes-deps"], enable]
+
+
+def _hermes_notes() -> list[str]:
+    # Hermes reads these before ~/.honcho/config.json, so a key in one of them wins.
+    files = dict.fromkeys([_hermes_home() / "honcho.json", _home() / ".hermes" / "honcho.json"])
+    return [f"Hermes reads {f} before ~/.honcho/config.json, so a key there wins." for f in files if _exists(f)]
+
+
+def _openclaw_install(_: Credentials) -> list[list[str]]:
+    # The plugin reads the key from ~/.honcho/config.json. From ClawHub rather
+    # than npm: OpenClaw cancels an npm-sourced install without a terminal, and
+    # without --accept-capabilities it stops to ask for consent either way.
+    # `plugins uninstall` leaves the entry behind as enabled: false, so a
+    # reinstall would stay disabled without the explicit enable. Message capture
+    # also needs conversation access, which the plugin's own warning says to
+    # turn on this way.
+    return [
+        ["openclaw", "plugins", "install", "clawhub:@honcho-ai/openclaw-honcho", "--accept-capabilities"],
+        ["openclaw", "plugins", "enable", "openclaw-honcho"],
+        ["openclaw", "config", "set", "plugins.entries.openclaw-honcho.hooks.allowConversationAccess", "true"],
+    ]
+
+
+# --------------------------------------------------------------------------- #
+# registry
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    name: str
+    kind: Literal["plugin", "mcp", "suggest"]
+    docs_url: str
+    bins: tuple[str, ...] = ()
+    paths: Callable[[], list[Path]] = field(default=lambda: [])
+    present: Callable[[], bool] | None = None  # overrides bins/paths when set
+    cloud: bool = False  # runs elsewhere: never found here, always offered
+    caller_env: tuple[str, ...] = ()  # set in the shell of this agent's tool calls
+    has_honcho: Callable[[], bool | None] = field(default=lambda: None)
+    install: Callable[[Credentials], list[list[str]]] | None = None
+    requires: tuple[str, ...] = ()
+    hosted_only: bool = False  # the hosted MCP server can't reach a self-hosted Honcho
+    activate: str | None = None  # extra step after install, beyond restarting the agent
+    notes: Callable[[], list[str]] = field(default=lambda: [])  # warnings to show once installed
+
+
+AGENTS: tuple[Agent, ...] = (
+    # ---- installed by `honcho install`
+    Agent(
+        id="claude-code", name="Claude Code", kind="plugin",
+        docs_url=f"{DOCS}/integrations/claude-code",
+        bins=("claude",), paths=lambda: [_env_path("CLAUDE_CONFIG_DIR", _home() / ".claude")],
+        caller_env=("CLAUDECODE", "CLAUDE_CODE"),
+        has_honcho=_claude_code_has_honcho, install=_claude_code_install,
+        requires=("claude", "node"),  # the plugin's hooks run on node
+    ),
+    Agent(
+        id="codex", name="Codex", kind="mcp", docs_url=f"{MCP_DOCS}#codex",
+        bins=("codex",), paths=lambda: [_env_path("CODEX_HOME", _home() / ".codex")],
+        caller_env=("CODEX_THREAD_ID", "CODEX_SANDBOX", "CODEX_CI"),
+        has_honcho=_codex_has_honcho, install=_codex_install,
+        requires=("codex", "npx"), hosted_only=True,
+    ),
+    Agent(
+        id="hermes", name="Hermes Agent", kind="plugin",
+        docs_url=f"{DOCS}/integrations/hermes",
+        bins=("hermes",), paths=lambda: [_hermes_home()],
+        has_honcho=_hermes_has_honcho, install=_hermes_install,
+        requires=("hermes",), notes=_hermes_notes,
+    ),
+    Agent(
+        id="openclaw", name="OpenClaw", kind="plugin",
+        docs_url=f"{DOCS}/integrations/openclaw",
+        bins=("openclaw",), paths=lambda: [_env_path("OPENCLAW_STATE_DIR", _home() / ".openclaw")],
+        has_honcho=_openclaw_has_honcho, install=_openclaw_install,
+        requires=("openclaw",), activate="openclaw gateway restart",
+    ),
+    Agent(
+        id="pi", name="Pi", kind="plugin", docs_url=f"{DOCS}/integrations/pi",
+        bins=("pi",), paths=lambda: [_home() / ".pi" / "agent"],
+        has_honcho=_pi_has_honcho, install=lambda _: [["pi", "install", "npm:@honcho-ai/pi-honcho"]],
+        requires=("pi",),
+    ),
+    # ---- set up from the guide
+    Agent(
+        id="grok-bot", name="Grok Bot", kind="suggest",
+        docs_url=f"{DOCS}/integrations/grok-bot", cloud=True,
+    ),
+    Agent(
+        id="opencode", name="OpenCode", kind="suggest", docs_url=f"{DOCS}/integrations/opencode",
+        bins=("opencode",), paths=lambda: [_env_path("OPENCODE_CONFIG_DIR", _xdg_config() / "opencode")],
+    ),
+    Agent(
+        id="kilo", name="Kilo Code", kind="suggest", docs_url=f"{DOCS}/integrations/kilo",
+        bins=("kilo",), paths=lambda: [_xdg_config() / "kilo"],
+    ),
+    Agent(
+        id="dsh", name="DeepSeek Harness", kind="suggest",
+        docs_url=f"{DOCS}/integrations/deepseek-harness", present=_dsh_present,
+    ),
+    Agent(
+        id="cursor", name="Cursor", kind="suggest", docs_url=f"{DOCS}/integrations/cursor",
+        bins=("cursor", "cursor-agent"), paths=lambda: [_home() / ".cursor"],
+    ),
+    Agent(
+        id="claude-desktop", name="Claude Desktop", kind="suggest", docs_url=f"{MCP_DOCS}#claude-desktop",
+        paths=lambda: [_app_support() / "Claude"] if sys.platform in ("darwin", "win32") else [],
+    ),
+    Agent(
+        id="windsurf", name="Windsurf", kind="suggest", docs_url=f"{MCP_DOCS}#windsurf",
+        bins=("windsurf",), paths=lambda: [_home() / ".codeium" / "windsurf"],
+    ),
+    Agent(
+        id="cline", name="Cline", kind="suggest", docs_url=f"{MCP_DOCS}#cline",
+        paths=lambda: [_vscode_user() / "globalStorage" / "saoudrizwan.claude-dev"],
+    ),
+    Agent(
+        id="vscode", name="VS Code", kind="suggest", docs_url=f"{MCP_DOCS}#vs-code-copilot-chat",
+        bins=("code",), paths=lambda: [_vscode_user()],
+    ),
+    Agent(
+        id="zed", name="Zed", kind="suggest", docs_url=f"{MCP_DOCS}#zed",
+        bins=("zed", "zeditor"), paths=lambda: [_zed_dir()],
+    ),
+    Agent(
+        id="goose", name="Goose", kind="suggest", docs_url=f"{MCP_DOCS}#goose",
+        # config dir only: "goose" is also the binary of a common Go migration tool
+        paths=lambda: [_goose_dir()],
+    ),
+)
+
+
+@dataclass
+class Detection:
+    agent: Agent
+    found: bool
+    installed: bool | None = None  # None = can't tell
+    blocked: str | None = None     # why the install can't run here
+
+
+def calling_agent() -> Agent | None:
+    """The agent whose tool call is running this command, from env vars it sets."""
+    named = os.environ.get("AI_AGENT", "").strip().lower()
+    for agent in AGENTS:
+        if agent.id == named or any(os.environ.get(v) for v in agent.caller_env):
+            return agent
+    return None
+
+
+def _found(agent: Agent) -> bool:
+    if agent.present is not None:
+        return agent.present()
+    return any(shutil.which(b) for b in agent.bins) or any(_exists(p) for p in agent.paths())
+
+
+def detect(agent: Agent, creds: Credentials | None = None) -> Detection:
+    if agent.cloud or not _found(agent):
+        return Detection(agent, found=False)
+    if agent.install is None:
+        return Detection(agent, found=True)
+    missing = [b for b in agent.requires if not shutil.which(b)]
+    if missing:
+        return Detection(agent, found=True, blocked=f"needs {', '.join(missing)} on PATH")
+    try:
+        installed = agent.has_honcho()
+    except Exception:
+        installed = None
+    blocked = None
+    if not installed and agent.hosted_only and creds is not None and not creds.hosted:
+        blocked = f"only works with api.honcho.dev; see {agent.docs_url}"
+    return Detection(agent, found=True, installed=installed, blocked=blocked)
+
+
+def detect_all(creds: Credentials | None = None) -> list[Detection]:
+    """Detect every agent. Status commands run in parallel; some take seconds."""
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        return list(pool.map(lambda a: detect(a, creds), AGENTS))

honcho_cli-0.3.0/src/honcho_cli/commands/install.py

@@ -0,0 +1,483 @@
+"""``honcho install`` — find the agents on this machine and add Honcho to them.
+
+Finding agents is a filesystem check (see ``honcho_cli.agents``). Adding Honcho
+runs only each agent's own commands: plugin installs for Claude Code, Hermes,
+OpenClaw and Pi, ``codex mcp add`` and the honcho-memory skill for Codex. All
+of them use the API key in ``~/.honcho/config.json``. Other agents are pointed
+at their setup guide, and Grok Bot gets a prompt to paste into a Bot.
+
+On a terminal with no arguments it shows a checkbox picker. Run from inside an
+agent's tool call (Claude Code, Codex), it adds Honcho to that agent and never
+prompts.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from honcho_cli.agents import (
+    AGENTS,
+    CATALOG_URL,
+    GROK_BOT_PROMPT,
+    Agent,
+    Credentials,
+    Detection,
+    Quiet,
+    calling_agent,
+    detect_all,
+)
+from honcho_cli.branding import BRAND, ICON_FAIL, ICON_OK, ICON_RUN
+from honcho_cli.config import CONFIG_FILE, DEFAULT_BASE_URL, CLIConfig
+from honcho_cli.output import print_error, print_result, set_json_mode, use_json
+
+_console = Console(stderr=True)
+
+Runner = Callable[[Sequence[str], bool], int]
+
+KEY_PLACEHOLDER = "<api-key>"
+
+
+def _run(argv: Sequence[str], quiet: bool) -> int:
+    """Run one install command with the terminal attached; return its exit code.
+
+    argv[0] is resolved through PATH first so Windows npm ``.cmd`` shims run
+    without a shell. In JSON mode the child's stdout goes to stderr, keeping
+    our stdout for the JSON summary. A quiet step's output is captured and
+    shown only if it fails.
+    """
+    exe = shutil.which(argv[0]) or argv[0]
+    try:
+        if quiet:
+            proc = subprocess.run(
+                [exe, *argv[1:]], check=False, capture_output=True, text=True, errors="replace",
+                stdin=subprocess.DEVNULL,
+            )
+            if proc.returncode != 0:
+                sys.stderr.write(proc.stdout + proc.stderr)
+            return proc.returncode
+        stdout = None
+        if use_json():
+            with contextlib.suppress(AttributeError, OSError, ValueError):
+                stdout = sys.stderr.fileno()
+        return subprocess.run([exe, *argv[1:]], check=False, stdout=stdout).returncode
+    except OSError:
+        return 127
+
+
+# Swapped out in tests so nothing is actually installed.
+runner: Runner = _run
+
+
+def _mask(text: str, key: str) -> str:
+    if not key or key == KEY_PLACEHOLDER:
+        return text
+    return text.replace(key, f"{key[:4]}…{key[-4:]}" if len(key) > 12 else "****")
+
+
+def _fmt(commands: list[list[str]], key: str) -> str:
+    return _mask(" && ".join(shlex.join(argv) for argv in commands), key)
+
+
+# --------------------------------------------------------------------------- #
+# the API key and user peer every install uses
+
+
+def _read_config() -> dict[str, Any] | None:
+    """The config file as a dict: empty when missing, None when it exists but can't be parsed."""
+    try:
+        data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _saved_field(key: str) -> str:
+    """A string field from the config file itself (not the env vars CLIConfig overlays)."""
+    value = (_read_config() or {}).get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _saved_key() -> str:
+    return _saved_field("apiKey")
+
+
+def _save_key(cfg: CLIConfig, key: str) -> None:
+    cfg.api_key = key
+    cfg.save()
+    _console.print(f"  {ICON_OK} [dim]Saved the API key to {CONFIG_FILE}[/dim]")
+
+
+def _ensure_api_key(interactive: bool) -> str | None:
+    """The key in ``~/.honcho/config.json``, asking for one (or saving HONCHO_API_KEY) if absent.
+
+    Every agent reads its key from that file or gets it copied from there, so
+    nothing is installed without one. A key only in HONCHO_API_KEY is saved to
+    the file, because the OpenClaw and Hermes gateways run as services and never
+    see the shell's environment. A browser (device) login stores an OAuth token
+    instead, which the plugins can't use.
+    """
+    env_key = os.environ.get("HONCHO_API_KEY", "").strip()
+    key = _saved_key()
+    if key:
+        if env_key and env_key != key:
+            _console.print(
+                f"  [yellow]![/yellow] HONCHO_API_KEY differs from the key in {CONFIG_FILE}. "
+                "Agents read the file, so that key is the one used."
+            )
+        return key
+    from honcho_cli.commands.setup import _test_connection
+
+    cfg = CLIConfig.load()
+    if env_key:
+        ok, detail = _test_connection(cfg.base_url, env_key)
+        if ok:
+            _save_key(cfg, env_key)
+            return env_key
+        _console.print(f"  {ICON_FAIL} HONCHO_API_KEY was rejected: {detail}")
+
+    if cfg.oauth and cfg.oauth.access_token:
+        why = "You're signed in with a browser login, but agents need an API key."
+    else:
+        why = f"Agents read it from {CONFIG_FILE}."
+    if not interactive:
+        _console.print(f"  {ICON_FAIL} No Honcho API key yet. {why} Run: honcho init --api-key <key>")
+        return None
+
+    hosted = cfg.base_url.rstrip("/") == DEFAULT_BASE_URL
+    where = "Create one at https://app.honcho.dev and paste it here" if hosted else f"Paste an API key for {cfg.base_url}"
+    _console.print(f"  [yellow]![/yellow] No Honcho API key yet. {why}")
+    _console.print(f"  [dim]{where}. Press Enter to cancel.[/dim]")
+    while True:
+        key = typer.prompt("  API key", default="", show_default=False, hide_input=True).strip()
+        if not key:
+            return None
+        ok, detail = _test_connection(cfg.base_url, key)
+        if ok:
+            _save_key(cfg, key)
+            return key
+        _console.print(f"  {ICON_FAIL} {detail}. Try again, or press Enter to cancel.")
+
+
+def _default_peer_name() -> str:
+    try:
+        return getpass.getuser() or "user"
+    except Exception:  # no username in the environment or the password database
+        return "user"
+
+
+def _ensure_peer_name(interactive: bool) -> None:
+    """A shared ``peerName`` in ``~/.honcho/config.json``, asking for one if absent.
+
+    Hermes saves nothing from CLI turns until it knows the user's peer, and the
+    other plugins fall back to the same field, so every agent names the user the
+    same way. Defaults to the OS username, as the Claude Code plugin does.
+    """
+    if _saved_field("peerName"):
+        return
+    data = _read_config()
+    if data is None:
+        _console.print(f"  [yellow]![/yellow] Couldn't read {CONFIG_FILE}, so no peerName was saved.")
+        return
+    default = _default_peer_name()
+    name = typer.prompt("  What should your agents call you?", default=default).strip() if interactive else ""
+    data["peerName"] = name or default
+    CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(data, indent=2) + "\n")
+    with contextlib.suppress(OSError):
+        os.chmod(CONFIG_FILE, 0o600)
+    _console.print(f"  {ICON_OK} [dim]Agents will call you {data['peerName']} (peerName in {CONFIG_FILE})[/dim]")
+
+
+# --------------------------------------------------------------------------- #
+# rendering
+
+
+def _preview(d: Detection, creds: Credentials) -> str:
+    assert d.agent.install is not None
+    return _fmt(d.agent.install(creds), creds.api_key)
+
+
+def _print_status(detections: list[Detection], creds: Credentials, caller: Agent | None) -> None:
+    installable = [d for d in detections if d.found and d.agent.install]
+    guides = [d for d in detections if d.found and not d.agent.install]
+    missing = [d.agent.name for d in detections if not d.found and not d.agent.cloud]
+    width = max((len(d.agent.name) for d in installable + guides), default=0) + 2
+
+    _console.print()
+    if caller:
+        _console.print(f"  [dim]Running inside {caller.name}: setting up {caller.name} only, no prompts.[/dim]\n")
+    if installable:
+        _console.print("  [bold]Agents found on this machine[/bold]\n")
+        for d in installable:
+            if d.installed:
+                icon, detail = ICON_OK, "[green]Honcho installed[/green]"
+            elif d.blocked:
+                icon, detail = "[yellow]![/yellow]", f"[yellow]{d.blocked}[/yellow]"
+            else:
+                note = "  [dim](couldn't check if already added)[/dim]" if d.installed is None else ""
+                icon, detail = f"[{BRAND}]●[/{BRAND}]", f"{_preview(d, creds)}{note}"
+            _console.print(f"  {icon} {d.agent.name:<{width}}{detail}", highlight=False)
+    else:
+        names = ", ".join(a.name for a in AGENTS if a.install)
+        _console.print(f"  [bold]None of these is on this machine: {names}[/bold]")
+    if guides:
+        _console.print("\n  [bold]Also found[/bold] [dim](set up from the guide)[/dim]\n")
+        for d in guides:
+            _console.print(f"  [dim]○[/dim] {d.agent.name:<{width}}[dim]{d.agent.docs_url}[/dim]", highlight=False)
+    _console.print("\n  [dim]Grok Bot: `honcho install grok-bot` copies a setup prompt to paste into any Bot.[/dim]")
+    if missing:
+        _console.print(f"  [dim]Not found: {', '.join(missing)}[/dim]")
+    _console.print(f"  [dim]Full list: {CATALOG_URL}[/dim]\n")
+
+
+def _as_json(detections: list[Detection], creds: Credentials) -> list[dict[str, Any]]:
+    return [
+        {
+            "id": d.agent.id,
+            "name": d.agent.name,
+            "kind": d.agent.kind,
+            "found": d.found,
+            "installed": d.installed,
+            "blocked": d.blocked,
+            "command": _preview(d, creds) if d.found and d.agent.install and not d.installed else None,
+            "docs_url": d.agent.docs_url,
+        }
+        for d in detections
+    ]
+
+
+# --------------------------------------------------------------------------- #
+# picker + installs
+
+
+def _pick(candidates: list[Detection]) -> list[Detection] | None:
+    """Checkbox picker. Returns the ticked rows, or None if the user cancelled."""
+    import questionary
+
+    style = questionary.Style([
+        ("qmark", f"fg:{BRAND} bold"),
+        ("pointer", f"fg:{BRAND} bold"),
+        ("highlighted", f"fg:{BRAND} bold"),
+        ("selected", f"fg:{BRAND}"),
+        ("instruction", "fg:#808080"),
+        ("disabled", "fg:#808080 italic"),
+    ])
+    choices = [
+        questionary.Choice(
+            title=d.agent.name if d.agent.install else f"{d.agent.name}  (copies a setup prompt)",
+            value=d.agent.id,
+            checked=bool(d.agent.install) and not d.blocked,
+            disabled=d.blocked or None,
+        )
+        for d in candidates
+    ]
+    picked = questionary.checkbox(
+        "Add Honcho to which agents?",
+        choices=choices,
+        instruction="(space to toggle, a for all, enter to confirm)",
+        style=style,
+    ).ask()
+    if picked is None:
+        return None
+    by_id = {d.agent.id: d for d in candidates}
+    return [by_id[i] for i in picked]
+
+
+def _copy(text: str) -> bool:
+    for argv in (["pbcopy"], ["wl-copy"], ["xclip", "-selection", "clipboard"], ["clip"]):
+        exe = shutil.which(argv[0])
+        if not exe:
+            continue
+        try:
+            subprocess.run([exe, *argv[1:]], input=text, text=True, check=True, timeout=5)
+            return True
+        except (OSError, subprocess.SubprocessError):
+            continue
+    return False
+
+
+def _show_guide(agent: Agent) -> None:
+    if agent.id != "grok-bot":
+        _console.print(f"  {ICON_RUN} {agent.name}: follow {agent.docs_url}")
+        return
+    copied = " (copied to your clipboard)" if _copy(GROK_BOT_PROMPT) else ""
+    _console.print(f"\n  {ICON_RUN} [bold]Grok Bot[/bold]: paste this into any Bot{copied}:\n")
+    _console.print(f"  {GROK_BOT_PROMPT}\n", highlight=False, soft_wrap=True)
+    _console.print(f"  [dim]The Bot signs you in to Honcho itself. Guide: {agent.docs_url}[/dim]")
+
+
+def _install_one(agent: Agent, creds: Credentials) -> bool:
+    assert agent.install is not None
+    for argv in agent.install(creds):
+        shown = _fmt([argv], creds.api_key)
+        _console.print(f"\n  {ICON_RUN} [bold]{agent.name}[/bold]  [dim]{shown}[/dim]", highlight=False)
+        code = runner(argv, isinstance(argv, Quiet))
+        if code != 0:
+            _console.print(f"  {ICON_FAIL} {agent.name}: exited {code}. Retry with: {shown}", highlight=False)
+            return False
+    if agent.has_honcho() is False:
+        _console.print(f"  {ICON_FAIL} {agent.name}: the commands ran, but {agent.name} doesn't report Honcho yet.")
+        return False
+    _console.print(f"  {ICON_OK} {agent.name}: Honcho added")
+    for note in agent.notes():
+        _console.print(f"  [yellow]![/yellow] {note}", highlight=False)
+    return True
+
+
+def _run_installs(chosen: list[Detection], interactive: bool, results: dict[str, str]) -> int:
+    """Install or show each row, recording the outcome in results."""
+    if not chosen:
+        _console.print("  Nothing to install.")
+        return 0
+    creds: Credentials | None = None
+    if any(d.agent.install for d in chosen):
+        key = _ensure_api_key(interactive)
+        if key is None:
+            for d in chosen:
+                if d.agent.install:
+                    results[d.agent.id] = "no_api_key"
+            _console.print("  Nothing installed: every agent here needs the API key.")
+            return 1
+        _ensure_peer_name(interactive)
+        creds = Credentials(api_key=key, base_url=CLIConfig.load().base_url)
+
+    failed: list[str] = []
+    done: list[Agent] = []
+    for d in chosen:
+        if not d.agent.install:
+            _show_guide(d.agent)
+            results[d.agent.id] = "shown"
+            continue
+        assert creds is not None
+        ok = _install_one(d.agent, creds)
+        results[d.agent.id] = "installed" if ok else "failed"
+        if ok:
+            done.append(d.agent)
+        else:
+            failed.append(d.agent.name)
+    _console.print()
+    if done:
+        _console.print(f"  Restart {', '.join(a.name for a in done)} to load Honcho.")
+    for agent in done:
+        if agent.activate:
+            _console.print(f"  {agent.name}: run [bold]{agent.activate}[/bold] to activate.")
+    if failed:
+        _console.print(f"  [red]{len(failed)} failed:[/red] {', '.join(failed)}")
+        return 1
+    return 0
+
+
+def _resolve_targets(
+    targets: list[str], detections: list[Detection], results: dict[str, str]
+) -> tuple[list[Detection], bool]:
+    """Turn ids (or ``all``) into rows to install. Returns (rows, any_problem)."""
+    if "all" in targets:
+        chosen = []
+        for d in detections:
+            if not (d.found and d.agent.install) or d.installed:
+                continue
+            if d.blocked:
+                results[d.agent.id] = "blocked"
+                _console.print(f"  [dim]Skipping {d.agent.name}: {d.blocked}[/dim]")
+            else:
+                chosen.append(d)
+        return chosen, False
+
+    by_id = {d.agent.id: d for d in detections}
+    chosen: list[Detection] = []
+    problem = False
+    for t in dict.fromkeys(targets):
+        d = by_id[t]
+        if not d.agent.install:
+            chosen.append(d)
+        elif not d.found:
+            results[t] = "not_found"
+            problem = True
+            _console.print(f"  {ICON_FAIL} {d.agent.name} isn't on this machine.")
+        elif d.installed:
+            results[t] = "already_installed"
+            _console.print(f"  {ICON_OK} {d.agent.name} already has Honcho.")
+        elif d.blocked:
+            results[t] = "blocked"
+            problem = True
+            _console.print(f"  {ICON_FAIL} {d.agent.name}: {d.blocked}.")
+        else:
+            chosen.append(d)
+    return chosen, problem
+
+
+# --------------------------------------------------------------------------- #
+# command
+
+
+def install(
+    targets: list[str] | None = typer.Argument(
+        None,
+        help=f"Agents to set up without the picker, or 'all' for every one found. Ids: {', '.join(a.id for a in AGENTS)}",
+        show_default=False,
+    ),
+    list_only: bool = typer.Option(False, "--list", help="Only show what was found; install nothing"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Find the AI agents on this machine and add Honcho to them.
+
+    Claude Code, Hermes, OpenClaw and Pi get their Honcho plugin, and Codex the
+    Honcho MCP server and skill, each through the agent's own commands and the
+    API key in ~/.honcho/config.json. Other agents link to their setup guide.
+    """
+    if json_output:
+        set_json_mode(True)
+
+    creds = Credentials(api_key=_saved_key() or KEY_PLACEHOLDER, base_url=CLIConfig.load().base_url)
+    detections = detect_all(creds)
+    caller = None if targets or list_only else calling_agent()
+    if caller:
+        targets = [caller.id]
+
+    if use_json() and (not targets or list_only):
+        print_result(_as_json(detections, creds))
+        return
+
+    interactive = sys.stdin.isatty() and sys.stdout.isatty() and not use_json() and caller is None
+    if not use_json():
+        _print_status(detections, creds, caller)
+    if list_only:
+        return
+
+    results: dict[str, str] = {}
+    if targets:
+        known = {a.id for a in AGENTS}
+        unknown = [t for t in targets if t != "all" and t not in known]
+        if unknown:
+            print_error("UNKNOWN_AGENT", f"Unknown agent: {', '.join(unknown)}", {"known": sorted(known)})
+            raise typer.Exit(2)
+        chosen, problem = _resolve_targets(targets, detections, results)
+        code = _run_installs(chosen, interactive, results)
+        if use_json():
+            print_result([{"id": k, "status": v} for k, v in results.items()])
+        raise typer.Exit(1 if problem or code else 0)
+
+    candidates = [d for d in detections if d.found and d.agent.install and not d.installed]
+    candidates += [d for d in detections if d.agent.cloud]
+    if not interactive:
+        _console.print("  No terminal to ask on. Run `honcho install all`, or `honcho install <id>`.\n")
+        raise typer.Exit(1)
+    chosen = _pick(candidates)
+    if chosen is None:
+        _console.print("  Cancelled.")
+        raise typer.Exit(1)
+    raise typer.Exit(_run_installs(chosen, interactive, results))

{honcho_cli-0.2.1 → honcho_cli-0.3.0}/src/honcho_cli/main.py

@@ -65,11 +65,13 @@ def main(
 
 
 # Register top-level commands
+from honcho_cli.commands.install import install
 from honcho_cli.commands.setup import doctor, init
 from honcho_cli.commands.stack import start, status, stop
 
 app.command()(init)
 app.command()(doctor)
+app.command()(install)
 app.command()(start)
 app.command()(stop)
 app.command()(status)

honcho_cli-0.3.0/tests/test_install.py

@@ -0,0 +1,98 @@
+"""`honcho install`: agent detection, and which install commands run."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+from honcho_cli.agents import AGENTS
+from honcho_cli.main import app
+from typer.testing import CliRunner
+
+CATALOG = Path(__file__).resolve().parents[2] / "docs" / "snippets" / "integrations-catalog.jsx"
+KEY = "hch-test-0123456789abcdef"
+
+# Fake agent CLIs. Claude Code already lists the Honcho plugin; Codex reports
+# the MCP server only once something has registered it.
+STUBS = {
+    "claude": 'case "$*" in "plugin list --json") echo \'[{"id":"honcho@honcho"}]\';; esac',
+    "codex": '[ "$*" = "mcp get honcho" ] && { [ -f "$HOME/codex-has-honcho" ] || exit 1; }; exit 0',
+    "node": "exit 0",
+    "npx": "exit 0",
+}
+
+
+@pytest.fixture
+def machine(tmp_path, monkeypatch):
+    """A fake home with Claude Code (Honcho installed), Codex (not yet) and a Cursor config dir."""
+    home = tmp_path / "home"
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    for name, body in STUBS.items():
+        exe = bin_dir / name
+        exe.write_text(f"#!/bin/sh\n{body}\n")
+        exe.chmod(0o755)
+    (home / ".cursor").mkdir(parents=True)
+    config = home / ".honcho" / "config.json"
+    config.parent.mkdir()
+    config.write_text(json.dumps({"apiKey": KEY}))
+
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("PATH", str(bin_dir))
+    monkeypatch.setattr("honcho_cli.config.CONFIG_FILE", config)
+    monkeypatch.setattr("honcho_cli.commands.install.CONFIG_FILE", config)
+    for var in ("HONCHO_API_KEY", "HONCHO_BASE_URL", "XDG_CONFIG_HOME", "CODEX_HOME", "CLAUDE_CONFIG_DIR",
+                "OPENCODE_CONFIG_DIR", "HERMES_HOME", "OPENCLAW_STATE_DIR", "APPDATA", "AI_AGENT",
+                *(v for a in AGENTS for v in a.caller_env)):
+        monkeypatch.delenv(var, raising=False)
+    return home
+
+
+def test_detects_agents_and_installs_only_what_is_missing(machine, monkeypatch):
+    runner = CliRunner()
+
+    rows = {r["id"]: r for r in json.loads(runner.invoke(app, ["install", "--json"]).output)}
+    assert rows["claude-code"]["found"] and rows["claude-code"]["installed"] is True
+    assert rows["codex"]["found"] and rows["codex"]["installed"] is False
+    assert rows["codex"]["command"].startswith("codex mcp add honcho -- npx -y mcp-remote https://mcp.honcho.dev")
+    assert KEY not in rows["codex"]["command"]  # shown masked
+    assert rows["cursor"]["found"] and rows["cursor"]["kind"] == "suggest"
+    assert not rows["hermes"]["found"] and not rows["openclaw"]["found"]
+
+    ran: list[tuple[list[str], bool]] = []
+
+    def fake_run(argv, quiet):
+        ran.append((list(argv), quiet))
+        if argv[:3] == ["codex", "mcp", "add"]:
+            (machine / "codex-has-honcho").touch()
+        return 0
+
+    monkeypatch.setattr("honcho_cli.commands.install.runner", fake_run)
+    result = runner.invoke(app, ["install", "all"])
+
+    # Claude Code already has Honcho and Cursor is set up from its guide, so only Codex runs:
+    # its own `mcp add` on the terminal, then the skill install with its output hidden.
+    assert result.exit_code == 0, result.output
+    assert [(argv[:3], quiet) for argv, quiet in ran] == [
+        (["codex", "mcp", "add"], False),
+        (["npx", "-y", "skills"], True),
+    ]
+    assert f"Authorization:Bearer {KEY}" in ran[0][0]
+    # A shared user peer is saved next to the key, keeping what was already there.
+    saved = json.loads((machine / ".honcho" / "config.json").read_text())
+    assert saved["apiKey"] == KEY and saved["peerName"]
+
+
+@pytest.mark.skipif(not CATALOG.exists(), reason="docs catalog not in this checkout")
+def test_every_catalog_agent_is_detected():
+    """Adding an agent to the docs catalog should prompt adding it here."""
+    sections = CATALOG.read_text().split('title: "')[1:]
+    names = {
+        name
+        for section in sections
+        if section.startswith(("General agents", "Coding agents"))
+        for name in re.findall(r'name: "([^"]+)"', section)
+    }
+    assert names <= {a.name for a in AGENTS}