From 5e4336fa8462a6a5f412e31254483bf2fde1a8b2 Mon Sep 17 00:00:00 2001
From: Jason2866 <24528715+Jason2866@users.noreply.github.com>
Date: Tue, 14 Apr 2026 16:24:57 +0200
Subject: [PATCH 1/3] Add clangd-esp tool configuration to platform.json

---
 platform.json | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/platform.json b/platform.json
index e615c96ac..ab514f19e 100644
--- a/platform.json
+++ b/platform.json
@@ -135,6 +135,13 @@
       "package-version": "2.20.1",
       "version": "https://github.com/pioarduino/registry/releases/download/0.0.1/cppcheck-v2.20.1.zip"
     },
+    "tool-clangd-esp": {
+      "type": "tool",
+      "optional": true,
+      "owner": "pioarduino",
+      "package-version": "21.1.3+20260304",
+      "version": "https://github.com/pioarduino/registry/releases/download/0.0.1/clangd-esp-21.1.3_20260304.zip"
+    },
     "tool-clangtidy": {
       "type": "tool",
       "optional": true,

From 64555298b2acaec5e229f00dfc5c464d57bcbf5d Mon Sep 17 00:00:00 2001
From: Jason2866 <24528715+Jason2866@users.noreply.github.com>
Date: Tue, 14 Apr 2026 16:33:59 +0200
Subject: [PATCH 2/3] feat: auto-install tool-clangd-esp when IDE uses clangd
 IntelliSense (#475)

The pioarduino IDE extension now exports PLATFORMIO_IDE_INTELLISENSE_ENGINE
as an environment variable. When the value is 'clangd', the platform
automatically installs tool-clangd-esp during configure_default_packages().

Espressif's clangd has native Xtensa and ESP RISC-V ISA extension support
(xespv, xesploop, xespdsp, etc.) that the upstream clangd lacks, which
eliminates unknown-flag errors and improves IntelliSense for ESP32 targets.

Amp-Thread-ID: https://ampcode.com/threads/T-019d8c25-963a-728c-8166-76efd9747d60

Co-authored-by: Amp <amp@ampcode.com>
---
 platform.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/platform.py b/platform.py
index 6b63614e1..b915297d0 100644
--- a/platform.py
+++ b/platform.py
@@ -797,6 +797,19 @@ def _configure_check_tools(self, variables: Dict) -> None:
             if any(tool in package for tool in check_tools):
                 self.install_tool(package)
 
+    def _configure_clangd_tool(self) -> None:
+        """Install Espressif's clangd when the IDE has clangd IntelliSense enabled.
+
+        The pioarduino IDE extension exports PLATFORMIO_IDE_INTELLISENSE_ENGINE
+        so the platform can automatically install the matching tool package.
+        Espressif's clangd has native Xtensa and ESP RISC-V support that the
+        upstream clangd lacks.
+        """
+        engine = os.environ.get("PLATFORMIO_IDE_INTELLISENSE_ENGINE", "")
+        if engine == "clangd" and "tool-clangd-esp" in self.packages:
+            logger.info("clangd IntelliSense engine detected, installing tool-clangd-esp")
+            self.install_tool("tool-clangd-esp")
+
     def _handle_dfuutil_tool(self, variables: Dict) -> None:
         """Install dfuutil tool for Arduino Nano ESP32 board."""
         board_config = self.board_config(variables.get("board"))
@@ -851,6 +864,7 @@ def configure_default_packages(self, variables: Dict, targets: List[str]) -> Any
 
             self._configure_rom_elfs_for_exception_decoder(variables)
             self._configure_check_tools(variables)
+            self._configure_clangd_tool()
             self._handle_dfuutil_tool(variables)
 
             logger.info("Package configuration completed successfully")

From 3d77db6ff52215c7e4ff266ec615352c72b84747 Mon Sep 17 00:00:00 2001
From: Jason2866 <24528715+Jason2866@users.noreply.github.com>
Date: Tue, 14 Apr 2026 17:35:20 +0200
Subject: [PATCH 3/3] Strip and lowercase IntelliSense engine variable

---
 platform.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/platform.py b/platform.py
index b915297d0..05b78d02d 100644
--- a/platform.py
+++ b/platform.py
@@ -805,7 +805,7 @@ def _configure_clangd_tool(self) -> None:
         Espressif's clangd has native Xtensa and ESP RISC-V support that the
         upstream clangd lacks.
         """
-        engine = os.environ.get("PLATFORMIO_IDE_INTELLISENSE_ENGINE", "")
+        engine = os.environ.get("PLATFORMIO_IDE_INTELLISENSE_ENGINE", "").strip().lower()
         if engine == "clangd" and "tool-clangd-esp" in self.packages:
             logger.info("clangd IntelliSense engine detected, installing tool-clangd-esp")
             self.install_tool("tool-clangd-esp")