#!/usr/bin/env -S uv run --quiet # /// script # requires-python = ">=3.10" # dependencies = [] # /// # Copyright (c) 2026 Advanced Micro Devices, Inc. All rights reserved. # # See LICENSE for license information. """One-shot setup for the `local-ai-use` skill. Performs the setup steps from SKILL.md: 1. Ensures modern Lemonade is installed and its background service (the `lemond` daemon) is reachable. The port is the one `lemonade status` reports, unless --host / --port or LEMONADE_HOST / LEMONADE_PORT say otherwise; http://localhost:13305 is only the fallback. If no modern `lemonade` CLI is found, the latest version is installed on the user's behalf. The daemon auto-starts on install and is managed by the OS service manager, so this script never runs a `serve` command; it waits for the service to come up and, if it does not, prints the OS-specific start command and exits non-zero. 2. Writes the routing rule from `templates/local-ai-rule.md` into /AGENTS.md, between stable BEGIN/END markers so re-runs replace the block in place rather than appending. Modern Lemonade unified everything under a single `lemonade` CLI (subcommands `status`, `pull`, `run`, ...) driving an always-on `lemond` service. That is the only CLI this skill supports. An older build left on PATH lacks those subcommands, so the check below probes *capability* (does `lemonade status` work?) rather than trusting the binary name, and reports a stale CLI clearly instead of driving it into a 90-second dead end. Setup never downloads models: the default image/TTS/STT models are pulled on first use, by the installed AGENTS.md rule (see its failure handling). This keeps setup fast and offline-friendly. The script is idempotent: a second run on a fully configured workspace only re-runs the healthcheck. It exits non-zero on any unrecoverable failure. Pass --no-install to refuse the automatic install (it then just reports the missing CLI and exits non-zero, the old behaviour). Constants are documented inline; nothing is magical. """ from __future__ import annotations import argparse import json import os import platform import re import shutil import subprocess import tempfile import time import urllib.error import urllib.request from pathlib import Path # Defaults match the system-wide Lemonade Server install. Both the CLI # (LEMONADE_HOST / LEMONADE_PORT) and the OpenAI-compatible HTTP endpoints # bind to these by default -- but only by default, so the port is a fallback # for when `lemonade status` cannot tell us the real one (see resolve_port). DEFAULT_HOST = "127.0.0.1" DEFAULT_PORT = 13305 # `lemonade status --json` reports `{"port": 13305}`; the human-readable form # says "Server is running on port 13305". Anchoring on "running on" keeps this # off the other ports the same output lists (e.g. "WebSocket Port 9001"). STATUS_PORT_RE = re.compile(r"running on port (\d+)", re.IGNORECASE) # Picked because each default fits in under ~5 GB and runs on commodity CPU # hardware, so the savings vs. cloud calls are real on a typical developer # laptop. See SKILL.md for upgrade paths. DEFAULT_IMAGE_MODEL = "SD-Turbo" DEFAULT_TTS_MODEL = "kokoro-v1" DEFAULT_STT_MODEL = "Whisper-Tiny" # Stable markers around the rule block in AGENTS.md. The script rewrites the # region between these markers in place; do not change the marker strings or # every existing AGENTS.md will get a duplicate block on the next run. BEGIN_MARKER = "" END_MARKER = "" SKILL_DIR = Path(__file__).resolve().parent.parent RULE_TEMPLATE = SKILL_DIR / "templates" / "local-ai-rule.md" # Windows: winget is the current recommended install and keeps Lemonade # upgradable in place, so we try it first. WINDOWS_WINGET_ID = "AMD.LemonadeServer" # Fallback when winget is unavailable: the *full* Windows installer, Lemonade # plus the desktop app and the always-on `lemond` service. # `releases/latest/download/` always resolves to the newest published # asset of that exact name, so we never have to pin a version. WINDOWS_MSI_URL = ( "https://github.com/lemonade-sdk/lemonade/releases/latest/download/lemonade.msi" ) # Default per-user install location used by lemonade.msi. The CLI is added to # the *user* PATH in the registry, which the current process will not see, so # we also probe this tree directly after installing. WINDOWS_INSTALL_DIR = Path( os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local")) ) / "lemonade_server" # macOS: the Homebrew cask is the current recommended install. It also avoids # the unauthenticated GitHub API call the .pkg fallback needs, which is rate # limited per source IP. MACOS_BREW_CASK = "lemonade-server" # GitHub release metadata, used to resolve the versioned macOS .pkg asset # (its filename embeds the version, so there is no stable latest/download URL). GITHUB_LATEST_RELEASE_API = ( "https://api.github.com/repos/lemonade-sdk/lemonade/releases/latest" ) # Ubuntu/Debian install: the stable PPA. The apt package is named # `lemonade-server` (the CLI you then run is `lemonade`); installing it pulls # in the `lemond` service, which the OS auto-starts. Run as a single shell # pipeline so one sudo prompt covers the whole thing. LINUX_APT_INSTALL = ( "sudo add-apt-repository -y ppa:lemonade-team/stable && " "sudo apt-get update && " "sudo apt-get install -y lemonade-server" ) # Modern Lemonade exposes exactly one CLI, `lemonade`, driving the always-on # `lemond` service. There is no second binary to fall back to, so instead of # trying other names we verify this one is the modern build (see find_cli). CLI_NAME = "lemonade" # Docs URL to point users at when they must install/upgrade Lemonade by hand. INSTALL_DOCS_URL = "https://lemonade-server.ai/docs/guide/install/" def _default_workspace() -> Path: """Workspace root for AGENTS.md. Defaults to cwd, but if launched from inside an agent's skill folder (the universal `<.dot-config>/skills//` layout used by Claude, Cursor, Codex, Gemini, etc.), climb out to the real workspace root so AGENTS.md is never buried inside the skill folder. """ cwd = Path.cwd().resolve() for parent in cwd.parents: if parent.name == "skills" and parent.parent.name.startswith("."): return parent.parent.parent return cwd def _print(msg: str) -> None: """Single-line, prefix-tagged status print so the agent's output stays parseable.""" print(f"[local-ai-use] {msg}", flush=True) def _http_get(url: str, timeout_s: float) -> tuple[int, bytes]: req = urllib.request.Request(url) with urllib.request.urlopen(req, timeout=timeout_s) as r: # noqa: S310 return r.status, r.read() def _candidate_clis() -> list[str]: """Every `lemonade` executable we can find, PATH first. On Windows the MSI updates the *user* PATH in the registry, which the current process will not have inherited, so we also probe the default per-user install tree for the executable. """ candidates: list[str] = [] found = shutil.which(CLI_NAME) if found: candidates.append(found) if platform.system() == "Windows" and WINDOWS_INSTALL_DIR.exists(): for exe in WINDOWS_INSTALL_DIR.rglob(f"{CLI_NAME}.exe"): exe_str = str(exe) if exe_str not in candidates: candidates.append(exe_str) return candidates def _run_status(cli: str, *, as_json: bool = False) -> str | None: """Combined output of ` status`, or None if it did not run. `status` is read-only and cheap, which is why it doubles as the modern-CLI probe and the port lookup. """ cmd = [cli, "status"] + (["--json"] if as_json else []) try: result = subprocess.run(cmd, capture_output=True, text=True, timeout=20) except (OSError, subprocess.SubprocessError): return None return f"{result.stdout}\n{result.stderr}" def is_modern_cli(cli: str) -> bool: """True if `cli` is the modern Lemonade CLI (drives the `lemond` service). Capability probe, not a name check: the modern `lemonade` CLI exposes a `status` subcommand that reports on the service. An older `lemonade` on PATH does not recognise the subcommand and errors with an argparse "invalid choice" instead. Running `lemonade status` is cheap, does not mutate anything, and tells us both that the CLI is modern AND whether the service is already up, so we reuse it as the single discriminator. A modern CLI prints "Server is running..." or "Server is not running" (exiting 0 or 1 accordingly). We key off that phrasing rather than the exit code alone. """ blob = (_run_status(cli) or "").lower() # Modern `lemonade status` always reports on the server, whether or not it # is running. An old/incompatible CLI never prints this phrasing (it errors # with "invalid choice: 'status'"), so the presence of the phrase is a # positive, unambiguous signal that this is the modern CLI. return "server is running" in blob or "server is not running" in blob def discover_port(cli: str) -> int | None: """The port the service actually bound, or None if it is not running. The port is a config value (`lemonade config set port`) that an existing config, another install channel, or a port conflict all move, so treating DEFAULT_PORT as the definition of "reachable" hides a healthy server. The CLI resolves this from the service's UDP beacon for us; do not scan for beacons here, because those also arrive from servers on other machines. """ blob = _run_status(cli, as_json=True) if blob: try: port = json.loads(blob.strip()).get("port") except (AttributeError, ValueError): port = None if isinstance(port, int): return port blob = _run_status(cli) # older builds may not support --json match = STATUS_PORT_RE.search(blob) if blob else None return int(match.group(1)) if match else None def resolve_port(cli: str | None, host_arg: str | None, port_arg: int | None) -> int: """Port to health-check: what was asked for, else what `status` reports. An explicit host is taken at face value: the CLI here knows nothing about another machine's config, so a remote host keeps the default port. """ if port_arg is not None: return port_arg if cli is not None and host_arg is None: return discover_port(cli) or DEFAULT_PORT return DEFAULT_PORT def find_cli() -> tuple[str | None, str | None]: """Locate a Lemonade CLI and classify it. Returns ``(modern_cli, stale_cli)``: - ``(path, None)`` a modern, capable `lemonade` CLI was found -> use it. - ``(None, path)`` a `lemonade` executable exists but is an older build -> the caller should guide the user to upgrade. - ``(None, None)`` no `lemonade` executable found at all -> install it. """ stale: str | None = None for cli in _candidate_clis(): if is_modern_cli(cli): return cli, None stale = stale or cli return None, stale def install_lemonade() -> None: """Install the latest version of Lemonade for the current OS. Raises RuntimeError on any unrecoverable failure so the caller can report a clean message and fall back to the manual install link. """ system = platform.system() if system == "Windows": _install_windows() elif system == "Linux": _install_linux() elif system == "Darwin": _install_macos() else: raise RuntimeError( f"No automatic installer for this OS ({system}). " f"Install manually: {INSTALL_DOCS_URL}" ) def _download(url: str, dest: Path) -> None: _print(f"downloading {url}") try: urllib.request.urlretrieve(url, dest) # noqa: S310 except (urllib.error.URLError, OSError) as exc: raise RuntimeError(f"download failed ({url}): {exc}") from exc def _run(cmd: list[str] | str, *, shell: bool = False) -> None: """Run an install command, surfacing a clean error on failure.""" printable = cmd if isinstance(cmd, str) else " ".join(cmd) _print(f"running: {printable}") result = subprocess.run(cmd, shell=shell) # noqa: S602,S603 if result.returncode != 0: raise RuntimeError(f"command failed (exit {result.returncode}): {printable}") def _install_windows() -> None: """Install with winget, falling back to the signed full MSI.""" if shutil.which("winget") is not None: try: _run( [ "winget", "install", "-e", "--id", WINDOWS_WINGET_ID, "--accept-package-agreements", "--accept-source-agreements", "--disable-interactivity", ] ) _print("Lemonade installed.") return except RuntimeError as exc: _print(f"winget install did not complete ({exc}); trying the MSI.") msi = Path(tempfile.gettempdir()) / "lemonade.msi" _download(WINDOWS_MSI_URL, msi) # /qn = silent, per-user (no elevation needed). The MSI registers the CLI # and Start Menu shortcut and pulls the full app payload. _run(["msiexec", "/i", str(msi), "/qn"]) _print("Lemonade installed.") def _install_linux() -> None: """Install from the stable PPA on apt distros.""" if shutil.which("apt-get") is None: raise RuntimeError( "Automatic install only supports apt-based distros (Ubuntu/Debian). " f"Install manually: {INSTALL_DOCS_URL}" ) if os.geteuid() != 0 and shutil.which("sudo") is None: # type: ignore[attr-defined] raise RuntimeError( "Need root (or sudo) to install system packages. " f"Install manually: {INSTALL_DOCS_URL}" ) _run(LINUX_APT_INSTALL, shell=True) _print("Lemonade installed.") def _install_macos() -> None: """Install the Homebrew cask, falling back to the signed .pkg.""" if shutil.which("brew") is not None: try: _run(["brew", "install", "--cask", MACOS_BREW_CASK]) _print("Lemonade installed.") return except RuntimeError as exc: _print(f"Homebrew install did not complete ({exc}); trying the .pkg.") pkg_url = _resolve_macos_pkg_url() pkg = Path(tempfile.gettempdir()) / "Lemonade.pkg" _download(pkg_url, pkg) _run(["sudo", "installer", "-pkg", str(pkg), "-target", "/"]) _print("Lemonade installed.") def _resolve_macos_pkg_url() -> str: """Resolve the versioned macOS .pkg download URL from the latest release.""" req = urllib.request.Request( GITHUB_LATEST_RELEASE_API, headers={"Accept": "application/vnd.github+json"} ) try: with urllib.request.urlopen(req, timeout=15.0) as r: # noqa: S310 data = json.loads(r.read()) except (urllib.error.URLError, OSError, ValueError) as exc: raise RuntimeError(f"could not query latest release: {exc}") from exc for asset in data.get("assets", []): name = asset.get("name", "") if name.endswith("-Darwin.pkg"): return asset["browser_download_url"] raise RuntimeError( "No macOS .pkg asset found in the latest release. " f"Install manually: {INSTALL_DOCS_URL}" ) def service_start_hint() -> str: """OS-specific command to (re)start the `lemond` service by hand. Modern Lemonade has no `lemonade serve`; the `lemond` daemon is managed by the OS service manager and auto-starts on install. If it is somehow down, the user starts it via their service manager, not via the CLI. """ system = platform.system() if system == "Linux": # v11 ships a system service; older 10.x used a --user unit. Offer both. return ( "sudo systemctl start lemond " "(or, for a per-user install: systemctl --user start lemond)" ) if system == "Darwin": # macOS return "sudo launchctl load /Library/LaunchDaemons/com.lemonade.server.plist" if system == "Windows": return ( "start the Lemonade tray app from the Start menu, or run " "`Start-Service lemond` (or `net start lemond`) in an elevated shell" ) return f"start the Lemonade service for your OS; see {INSTALL_DOCS_URL}" def uninstall_hint() -> str: """OS-specific ways to remove an old Lemonade that shadows the modern CLI.""" system = platform.system() if system == "Linux": return "`sudo apt remove lemonade-server`, or the package manager it came from" if system == "Darwin": # macOS return ( f"`brew uninstall --cask {MACOS_BREW_CASK}`, or delete the installed " "`Lemonade.app` and its .pkg receipt" ) if system == "Windows": return ( f"`winget uninstall -e --id {WINDOWS_WINGET_ID}`, or uninstall " "Lemonade Server from Settings > Apps > Installed apps" ) return f"remove it with your platform's package manager; see {INSTALL_DOCS_URL}" def wait_for_server( host: str, port: int, *, cli: str | None = None, timeout_s: float = 90.0 ) -> tuple[bool, int]: """Poll /api/v1/health until it answers 200 or we hit the timeout. Returns ``(reachable, port)``: when `cli` is given the port is re-checked each pass, since a service that is still starting has none to report yet. """ deadline = time.monotonic() + timeout_s while time.monotonic() < deadline: if check_server_reachable(host, port): return True, port if cli is not None: port = discover_port(cli) or port time.sleep(2.0) return False, port def check_server_reachable(host: str, port: int) -> bool: """Return True if /api/v1/health responds 200 within 3 seconds.""" url = f"http://{host}:{port}/api/v1/health" try: status, _ = _http_get(url, timeout_s=3.0) return status == 200 except (urllib.error.URLError, OSError): return False def render_rule_block( *, host: str, port: int, image_model: str, tts_model: str, stt_model: str, ) -> str: """Read the rule template and fill in endpoint/model choices. The template already includes BEGIN/END markers and matches the constants at the top of this file. We re-validate that here so a future template edit cannot silently drift away from the markers the writer relies on. """ if not RULE_TEMPLATE.exists(): raise FileNotFoundError( f"Rule template missing: {RULE_TEMPLATE}. " "Did the skill folder get partially copied?" ) text = RULE_TEMPLATE.read_text(encoding="utf-8") if BEGIN_MARKER not in text or END_MARKER not in text: raise ValueError( "Rule template is missing the BEGIN/END markers; refuse to write " "AGENTS.md because re-runs would append duplicate blocks." ) endpoint_host = "localhost" if host in {"127.0.0.1", "::1"} else host base_root = f"http://{endpoint_host}:{port}" replacements = { "{{LEMONADE_BASE_ROOT}}": base_root, "{{LEMONADE_BASE_URL}}": f"{base_root}/api/v1", "{{IMAGE_MODEL}}": image_model, "{{TTS_MODEL}}": tts_model, "{{STT_MODEL}}": stt_model, } for placeholder, value in replacements.items(): text = text.replace(placeholder, value) unresolved = sorted(set(re.findall(r"\{\{[A-Z_]+\}\}", text))) if unresolved: raise ValueError( "Rule template still has unresolved placeholders: " + ", ".join(unresolved) ) return text.strip() + "\n" def upsert_agents_md( workspace: Path, *, host: str, port: int, image_model: str, tts_model: str, stt_model: str, ) -> Path: """Write or replace the rule block inside /AGENTS.md.""" target = workspace / "AGENTS.md" block = render_rule_block( host=host, port=port, image_model=image_model, tts_model=tts_model, stt_model=stt_model, ) if not target.exists(): workspace.mkdir(parents=True, exist_ok=True) target.write_text( "# Agent instructions\n\n" "Project-scoped rules picked up automatically by Cursor, Claude Code,\n" "Codex, Gemini CLI, and other AGENTS.md-aware coding agents.\n\n" f"{block}", encoding="utf-8", ) _print(f"created {target}") return target existing = target.read_text(encoding="utf-8") if BEGIN_MARKER in existing and END_MARKER in existing: before, _, rest = existing.partition(BEGIN_MARKER) _, _, after = rest.partition(END_MARKER) # Strip trailing newline noise around the spliced region so we don't # accumulate blank lines on every re-run. new = before.rstrip() + "\n\n" + block + after.lstrip() if new == existing: _print(f"AGENTS.md rule already up to date at {target}") return target target.write_text(new, encoding="utf-8") _print(f"updated rule block in {target}") return target # No existing block: append with a separating blank line. if not existing.endswith("\n"): existing += "\n" target.write_text(existing + "\n" + block, encoding="utf-8") _print(f"appended rule block to {target}") return target def _env_port() -> int | None: """LEMONADE_PORT as an int, ignoring an unusable value.""" raw = os.environ.get("LEMONADE_PORT") if not raw: return None try: return int(raw) except ValueError: # The CLI reads this variable too and refuses to start on a value it # cannot parse, which would then look like a stale CLI. os.environ.pop("LEMONADE_PORT") _print(f"ignoring LEMONADE_PORT={raw!r}: not a port number.") return None def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--workspace", type=Path, default=_default_workspace(), help="Workspace root where AGENTS.md should be written (default: workspace root, auto-detected).", ) parser.add_argument( "--host", default=os.environ.get("LEMONADE_HOST"), help="Lemonade Server host (default: $LEMONADE_HOST, else 127.0.0.1).", ) parser.add_argument( "--port", type=int, default=_env_port(), help=f"Lemonade Server port (default: $LEMONADE_PORT, else the port `{CLI_NAME} status` reports, else {DEFAULT_PORT}).", ) parser.add_argument( "--image-model", default=DEFAULT_IMAGE_MODEL, help=f"Image generation model written into AGENTS.md, pulled on first use (default: {DEFAULT_IMAGE_MODEL}).", ) parser.add_argument( "--tts-model", default=DEFAULT_TTS_MODEL, help=f"Text-to-speech model written into AGENTS.md, pulled on first use (default: {DEFAULT_TTS_MODEL}).", ) parser.add_argument( "--stt-model", default=DEFAULT_STT_MODEL, help=f"Speech-to-text model written into AGENTS.md, pulled on first use (default: {DEFAULT_STT_MODEL}).", ) parser.add_argument( "--no-install", action="store_true", help="Do not auto-install Lemonade; just report and exit non-zero if the CLI or service is missing.", ) args = parser.parse_args(argv) cli, stale = find_cli() # An old `lemonade` on PATH shadows the modern CLI. We never drive or # auto-remove it -- we guide the user, because a shadowing binary will keep # hiding a freshly installed modern CLI until it is removed. if cli is None and stale is not None: _print(f"FAIL: found an old Lemonade CLI at {stale}.") _print( "It is missing the modern `lemonade status` command, so it predates " "the unified CLI (v10.1.0) and cannot be used by this skill." ) _print(f"Uninstall it first so it stops shadowing the modern CLI: {uninstall_hint()}.") _print( "Then re-run this skill to install the latest Lemonade for you, or " f"install it yourself: {INSTALL_DOCS_URL}" ) return 2 if cli is None: if args.no_install: _print("FAIL: the `lemonade` CLI is not on PATH (--no-install set).") _print(f"Install Lemonade manually: {INSTALL_DOCS_URL}") return 2 _print("`lemonade` CLI not found; installing the latest version of Lemonade.") try: install_lemonade() except RuntimeError as exc: _print(f"FAIL: automatic install did not complete: {exc}") return 2 cli, stale = find_cli() if cli is None: _print("FAIL: install finished but a modern `lemonade` CLI is still not found.") _print( "Open a new shell so PATH refreshes and re-run, or install " f"manually: {INSTALL_DOCS_URL}" ) return 2 _print(f"using Lemonade CLI: {cli}") # Ask the service where it bound rather than assuming the default port: a # "not running" verdict from the wrong port would be baked into the rule. host = args.host or DEFAULT_HOST port = resolve_port(cli, args.host, args.port) rediscover_with = cli if args.host is None and args.port is None else None # Modern Lemonade auto-starts the `lemond` service on install; there is no # `lemonade serve`. If it is not up yet (e.g. still starting right after a # fresh install), poll briefly, then guide the user to start the OS # service rather than trying to spawn it ourselves. if not check_server_reachable(host, port): if args.no_install: _print( f"FAIL: Lemonade Server is not responding at " f"http://{host}:{port}/api/v1/health (--no-install set)." ) _print(f"Start the service: {service_start_hint()}") return 3 _print("Lemonade service not reachable yet; waiting for it to come up.") reachable, port = wait_for_server(host, port, cli=rediscover_with) if not reachable: _print( f"FAIL: the Lemonade service did not become reachable at " f"http://{host}:{port}/api/v1/health." ) _print(f"Start it manually, then re-run: {service_start_hint()}") _print(f"If it is not installed, see {INSTALL_DOCS_URL}") return 3 _print(f"server reachable at http://{host}:{port}") upsert_agents_md( args.workspace.resolve(), host=host, port=port, image_model=args.image_model, tts_model=args.tts_model, stt_model=args.stt_model, ) _print("done. Future image, TTS, and STT requests now route to local Lemonade.") return 0 if __name__ == "__main__": raise SystemExit(main())