Merge pull request #3523 from pareenaverma/content_review

Tech review of the Performix MCP server insights LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_index.md

@@ -1,31 +1,27 @@
 ---
-title: Use Arm Performix Agentic Dynamic Insights from VS Code with Codex
+title: Generate Arm Performix AI Insights in VS Code with Codex
 
 draft: true
 cascade:
     draft: true
 
-description: This Learning Path shows how to configure the Arm Performix MCP server with the Codex extension in Visual Studio Code, then generate AI Insights for an existing Arm Performix profiling run.
+description: Configure the Arm Performix MCP server for Codex in Visual Studio Code and use profile evidence to generate and validate AI Insights.
 
 minutes_to_complete: 20
 
 who_is_this_for: This Learning Path is for software developers and performance engineers who want to optimize applications on Arm-based servers using Arm Performix.
 
 learning_objectives:
-    - Configure the Arm Performix MCP server in the Codex extension for VS Code. 
-    - Check that the assistant can see Arm Performix recipes and runs. 
-    - Ask the assistant to list available Arm Performix runs. 
-    - Generate AI Insights for a supported code hotspots run. 
-    - Use the result to decide where to inspect or optimize next. 
+    - Configure the Arm Performix MCP server for the Codex extension in VS Code.
+    - Verify that Codex can access Arm Performix recipes, targets, and runs.
+    - Create or select a supported Code Hotspots run.
+    - Generate an AI Insight and validate its recommendations against profile evidence.
 
 prerequisites:
-    - Arm Performix version 2026.2.5 or later installed. Refer to the [Install Guide](https://learn.arm.com/install-guides/performix/) for instructions. 
-    - Visual Studio Code installed with the Codex extension. 
-    - Permission to use your organization-approved AI assistant with profile data, symbols, source excerpts, disassembly excerpts, and performance metrics.
-    - For remote Linux targets, configure key-based SSH access before using the Arm Performix MCP server. 
-    - If you connect to your target as a non-root user, some recipes or target configurations might require passwordless sudo. 
-    - Make sure your SSH known_hosts file contains the target host key. 
-    - If your target configuration uses jump nodes, make sure known_hosts also contains the host key for each jump node. 
+    - Arm Performix version 2026.2.5 or later installed. See the [Arm Performix install guide](/install-guides/performix/) for installation and target setup instructions.
+    - Visual Studio Code with the Codex extension installed.
+    - Access to Codex through ChatGPT sign-in, or an organization-approved OpenAI API key provided through the `OPENAI_API_KEY` environment variable.
+    - Permission from your organization to share profile data, symbols, source excerpts, disassembly excerpts, and performance metrics with Codex.
 
 author: 
     - Julie Gaskin
@@ -39,30 +35,28 @@ operatingsystems:
     - Linux
 tools_software_languages:
     - Arm Performix
-    - C++
-    - GCC
+    - Codex
+    - Model Context Protocol
+    - Visual Studio Code
 
 further_reading:
     - resource:
-        title: Install guide
+        title: Arm Performix install guide
         link: https://learn.arm.com/install-guides/performix
         type: documentation
     - resource:
-        title: User guide
+        title: Arm Performix User Guide
         link: https://developer.arm.com/documentation/110163/latest/
         type: documentation
     - resource:
-        title: Code hotspots learning path
+        title: Find Code Hotspots with Arm Performix
         link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix
-        type: learning path
+        type: documentation
     - resource:
-        title: CPU microarchitecture learning path
+        title: Tune application performance with Arm Performix CPU Microarchitecture
         link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-microarchitecture
-        type: learning path
-    - resource:
-        title: Migrating applications to Arm servers
-        link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/migration/
-        type: learning path
+        type: documentation
+
 
 ### FIXED, DO NOT MODIFY
 # ================================================================================

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md

@@ -3,98 +3,127 @@ title: Configure the Arm Performix MCP server in Codex
 
 weight: 3
 
+description: Add the local Arm Performix MCP server to Codex and verify that the extension can access Performix tools and profiling runs.
+
 layout: learningpathall
 ---
-There are 3 ways to configure the MCP server:
+## Choose a configuration method
 
-- Through VS Code's GUI
-- Through the Codex CLI
-- By editing the Codex configuration file: `~/.codex/config.toml`.
+Codex CLI and the Codex extension share MCP configuration on the same host. Choose one of these methods:
 
-## Configure the MCP server through VS Code
+- Use the Codex extension settings.
+- Run `codex mcp add` in a terminal.
+- Edit `~/.codex/config.toml`.
 
-Use the following procedure in Visual Studio Code:
+You only need to complete one method. The MCP server is a local standard input/output (STDIO) process started by the `apx` executable.
 
-1. Open Visual Studio Code and open the Codex sidebar.
-2. Open Codex settings.
-3. In the Codex Settings tab, select MCP servers.
-4. Click + Add server.
-5. In the Name field, enter a name such as arm-performix.
-6. In the Command to launch field, enter the path to the Arm Performix `apx` executable.
-    Default paths include:
+{{% notice Note %}}
+Configure the server on the host where Codex runs. In a local VS Code session, this is your development computer. In a remote development session, confirm which host runs the Codex extension and which Arm Performix data directory it uses.
+{{% /notice %}}
 
-    ```
+## Configure the server in the Codex extension
+
+To add the server in Visual Studio Code:
+
+1. Open the Codex sidebar and select the gear icon.
+2. Select **MCP servers**, then select **Add server**.
+3. Enter `arm-performix` for the server name.
+4. Select **STDIO** as the transport.
+5. Enter the full path to the Arm Performix `apx` executable in the command field.
+
+    On macOS:
+
+    ```text
     /Applications/Arm Performix.app/Contents/assets/apx/apx
+    ```
+
+    On Linux:
 
+    ```text
     /opt/Arm Performix/assets/apx/apx
     ```
 
-    On Windows, the default installation directory depends on whether Arm Performix was installed for one user or all users:
+    On Windows with an all-users installation:
 
+    ```text
+    C:\Program Files\Arm Performix\assets\apx\apx.exe
     ```
-    C:\Users\<username>\AppData\Local\Programs\Arm Performix 
 
-    C:\Program Files\Arm Performix
+    On Windows with a single-user installation:
+
+    ```text
+    C:\Users\<username>\AppData\Local\Programs\Arm Performix\assets\apx\apx.exe
     ```
 
-7. In the Arguments field, add:
+6. Add one argument:
 
-    ```
+    ```text
     mcp
     start
     ```
 
-8. Click **Save** and restart the Codex extension.
+7. Select **Save**, then select **Restart extension**.
 
-## Configure the MCP server using Codex CLI
+## Configure the MCP server with Codex CLI
 
-Alternatively, you can use Codex's CLI to add an MCP server. Replace `<path-to-apx>` with the path to the `apx` executable on your system. If the path contains spaces, put the path in double quotation marks.
+If the `codex` command is available in your terminal, add the same STDIO server from the command line. Replace `<path-to-apx>` with the full executable path for your host:
 
-```
+```bash
 codex mcp add arm-performix -- "<path-to-apx>" mcp start
 ```
 
 For example, on macOS:
 
-```
+```bash
 codex mcp add arm-performix -- "/Applications/Arm Performix.app/Contents/assets/apx/apx" mcp start
 ```
 
-## Configure the MCP server in the Codex configuration file
-
-You can also configure the MCP server by editing the Codex configuration file directly.
+Restart the Codex extension after the command completes.
 
-1. Open this file in a text editor: `~/.codex/config.toml`
+## Configure the server in `config.toml`
 
-2. Add a server entry:
+For direct configuration, open `~/.codex/config.toml` and add:
 
-    ```
-    [mcp_servers.arm-performix]
+```toml
+[mcp_servers.arm-performix]
+command = "/Applications/Arm Performix.app/Contents/assets/apx/apx"
+args = ["mcp", "start"]
+```
 
-    command = "/Applications/Arm Performix.app/Contents/assets/apx/apx"
+Replace `command` with the full path to `apx` on your host. Save the file and restart the Codex extension.
 
-    args = ["mcp", "start"]
-    ```
+On Windows, use a TOML literal string so backslashes in the path aren't treated as escape characters:
 
-3. Replace the command value with the path to the apx executable on your system.
-4. Save the file and restart the Codex extension.
+```toml
+[mcp_servers.arm-performix]
+command = 'C:\Program Files\Arm Performix\assets\apx\apx.exe'
+args = ["mcp", "start"]
+```
 
 ## Check that the MCP server is connected
 
-Before generating insights, ask Codex to confirm that it can see Arm Performix data:
+If the `codex` command is available, confirm that Codex loaded the configuration:
 
-```
-List the available Arm Performix recipes and profiling runs. If no code hotspots runs are available, tell me that the MCP server is connected but there are no supported runs to analyze.
+```bash
+codex mcp list
 ```
 
-If the assistant lists Arm Performix recipes or runs, the MCP server is connected.
+Find `arm-performix` in the server list and check that its command and `mcp` argument are correct. If you don't use Codex CLI, open **MCP servers** from the Codex gear menu to review the same status.
 
-To narrow the result, include a workload name, recipe, or time period:
+Configuration alone doesn't prove that the tools can read Performix data. In a new Codex chat, enter:
 
+```text
+Use the Arm Performix MCP server to list the available recipes and profiling runs. For each run, include its run ID, recipe, target, workload, and creation time when those fields are available.
 ```
-Show me a list of Arm Performix runs for which AI insights are available.
+
+If Codex returns Performix recipes or runs, the end-to-end connection works. An empty run list isn't a connection failure if recipes or targets are returned.
+
+Next, ask Codex to identify runs that support the insight workflow:
+
+```text
+List the Arm Performix Code Hotspots runs that can be used to generate an AI Insight. Include the run ID and enough workload and target details for me to choose the correct run.
 ```
 
-Review the returned runs and identify the run you want to analyze. Note the run name or run ID.
+Record the run ID you want to analyze. A run name can be changed and might not be unique, so use the run ID in later prompts.
 
-If no supported Code Hotspots runs are available, you can create one from VS Code by asking the assistant to use the Arm Performix MCP server.
+You have now configured and tested the MCP connection. If no supported run is available, create a Code Hotspots run in the next section.

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md

@@ -3,43 +3,75 @@ title: Create a Code Hotspots run
 
 weight: 4
 
+description: Create a representative Arm Performix Code Hotspots run through Codex or the Performix CLI and record its run ID.
+
 layout: learningpathall
 ---
-If no supported Code Hotspots runs are available, you can create one from VS Code by asking the assistant to use the Arm Performix MCP server.
+## Prepare a representative workload
 
-First, ask the assistant to list the configured targets:
+You can skip this section if you already selected a supported Code Hotspots run.
 
-```
-List the available Arm Performix targets
-```
+For a new run, choose a workload that represents the behavior you want to optimize. Specify the executable with an absolute path because Performix doesn't support relative workload paths. Build it with debug symbols when possible so Performix can attribute samples to functions and source lines. Aim for at least 20 seconds of representative activity; a very short run might not collect enough samples for useful analysis.
+
+Before profiling, make sure you know:
 
-Choose the target that should run your workload, then ask the assistant to run Code Hotspots and generate insights from the result:
+- The Performix target name.
+- The executable path and arguments on the target.
+- The workload's working directory and required environment variables.
+- Whether running the workload has side effects.
 
+## Create a run with Codex
+
+First, ask Codex to list the configured targets:
+
+```text
+Use the Arm Performix MCP server to list the configured targets. Include each target's name and connection status when available.
 ```
-Run the Code Hotspots recipe on the target named "<target name>" with this workload: "<command>". 
-When the run completes, generate AI insights for that run. Suggest where I should start investigating next. 
+
+Choose the correct target, then ask Codex to run Code Hotspots. Keep collection and analysis as separate requests so you can confirm the target and workload before remote execution:
+
+```text
+Use Arm Performix to run the Code Hotspots recipe on target "<target-name>" with workload "<command>". Before starting, repeat the target and workload and ask me to confirm them. When the run completes, return its run ID and collection status.
 ```
 
 Replace:
 
-- `<target name>` with the Performix target name returned by the assistant.
+- `<target-name>` with the Performix target name returned by Codex.
+- `<command>` with the command that starts your workload on the target.
 
-- `<command>` with the command that starts your workload on the target. 
+For example:
 
-For example: 
+```text
+Use Arm Performix to run the Code Hotspots recipe on target "graviton-dev" with workload "/opt/myapp/bin/my_app --input /data/input.dat". Before starting, repeat the target and workload and ask me to confirm them. When the run completes, return its run ID and collection status.
+```
+
+After you confirm, Codex uses the MCP server to start the recipe. Review any permission request before allowing the assistant to run a command on the target.
+
+## Create a run with the Performix CLI
+
+If you prefer to control collection from a terminal, first check that the recipe dependencies and workload are ready:
 
+```bash
+apx recipe ready code_hotspots \
+    --target my-target \
+    --workload "/opt/myapp/bin/my_app --input /data/input.dat"
 ```
-Run the Code Hotspots recipe on the target named "graviton-dev" with this workload: "/opt/myapp/bin/my_app --input /data/input.dat". 
+
+If Performix reports missing or outdated target tools, deploy them as part of the run:
+
+```bash
+apx recipe run code_hotspots \
+    --target my-target \
+    --workload "/opt/myapp/bin/my_app --input /data/input.dat" \
+    --timeout 30 
 ```
 
-The assistant uses the Arm Performix MCP server to prepare the target, run the Code Hotspots recipe.
+The `--timeout 30` option limits profiling to 30 seconds; it doesn't make a short workload run longer. Use a duration that captures representative behavior. Add `--working-dir`, `--env`, or `--source` when your workload needs a specific working directory, environment variables, or host-based source mapping. For an already-running process, replace `--workload` with `--pid <process-id>`.
 
-If you prefer to run the profile manually, use the Performix CLI:
+When collection finishes, list the saved runs:
 
-```
-apx recipe ready code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat" 
- 
-apx recipe run code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat" --timeout 30
+```bash
+apx run list
 ```
 
-Use `--timeout` for unattended profiling so the run ends automatically. If you are profiling an already-running process, use `--pid` instead of `--workload`.
+Confirm that the new run completed successfully and record its run ID. You now have the stable identifier Codex needs to analyze the intended profile.