How to Perform Data Analysis with PI Desktop: The Complete Plugin Development Guide

You perform data analysis with PI Desktop by importing datasets into the Rust-based host core and processing them through isolated JavaScript plugins that execute in the agent runtime, returning structured results to the Electron renderer for visualization.

PI Desktop is a modular, Electron-based desktop application designed for extensible data analysis. According to the vastsa/PI-Desktop source code, the platform uses a three-tier architecture—host process, agent runtime, and renderer process—to safely execute user-defined analysis logic while maintaining UI responsiveness. This guide explains how to leverage these components to build, execute, and visualize custom data workflows.

Understanding the PI Desktop Architecture

Before writing analysis code, you must understand how the platform handles data and execution isolation. The architecture separates concerns across three distinct layers to prevent heavy computation from crashing the UI.

The Host Process (Rust Core)

The host process provides secure storage and low-level data operations. Written in Rust and located in crates/host-core, this layer handles file parsing for CSV, JSON, Excel, and plain-text formats. When you import a dataset, the host process stores parsed tables in ~/.pi-desktop/workspace and manages persistence via crates/host-core/src/storage.rs. This ensures that data ingestion occurs outside the JavaScript event loop, preventing blocking operations from freezing the interface.

The Agent Runtime (JavaScript Isolation)

User-defined analysis logic runs inside the agent runtime, located at packages/agent-runtime/src/runtime.ts. This isolated environment executes plugin code separately from the host process, ensuring that infinite loops or memory leaks in your analysis script cannot crash the application. The runtime exposes APIs like readTable and writeTable that communicate with the host core through secure message passing.

The Renderer Process (Electron UI)

The renderer process presents the interface using Electron. Components such as apps/desktop/src/components/DataTable.tsx and apps/desktop/src/components/ChartView.tsx display tabular data and visualizations. When a plugin returns results, the renderer converts structured data into interactive tables or markdown reports without re-executing the analysis logic.

Step-by-Step Guide to Performing Data Analysis

To execute a complete data analysis workflow, follow these four steps as implemented in the PI Desktop source code.

Step 1: Import Your Dataset

Begin by importing data through the file dialog. PI Desktop supports CSV, JSON, Excel, and plain-text files. The import routine in crates/host-core parses the file and registers it as a named table in your workspace under ~/.pi-desktop/workspace. Once imported, the table becomes accessible to plugins via the readTable API.

Step 2: Create a Data Analysis Plugin

Analysis code must be packaged as a PI plugin. Create a directory containing two required files:

• manifest.json: Declares capabilities such as "data-transform" or "visualisation"
• main.js: The JavaScript entry point containing your analysis logic

The official guide for building plugins is documented in docs/plugin-development.md. Place your plugin directory in the workspace or load it dynamically through the UI. The plugin system allows you to distribute reusable analysis workflows across different datasets.

Step 3: Execute the Plugin via the Tools Pane

Once installed, your plugin appears in the Tools pane of the UI. When you launch a tool, the interface calls functions defined in apps/desktop/src/components/ToolLauncher.tsx, which invokes launchTool() with your plugin ID and configuration parameters (such as target table names or statistical functions). The agent runtime loads your plugin's main.js and executes the run(context) function, passing an API context that includes methods for reading and writing tables.

Step 4: Visualize Results in the UI

After execution, the plugin returns structured data—typically arrays, aggregates, or markdown strings. The renderer process processes these results through DataTable.tsx for tabular display or ChartView.tsx for graphical visualization. Results can also be persisted as new tables in the workspace for downstream analysis.

Complete Plugin Development Example

The following example demonstrates a plugin that computes summary statistics for a CSV file. This code lives in apps/desktop/resources/skills/example-data-analysis.js and shows the standard pattern for data analysis with PI Desktop.

// apps/desktop/resources/skills/example-data-analysis.js
import { readTable, writeTable } from '@pi/agent-runtime';

export async function run(context) {
  // Load the user-uploaded CSV as a table named "my_data"
  const table = await readTable('my_data');

  // Compute basic statistics for each numeric column
  const stats = {};
  for (const col of table.columns) {
    if (table.isNumeric(col)) {
      const values = table.columnValues(col);
      const sum = values.reduce((a, b) => a + b, 0);
      const mean = sum / values.length;
      const min = Math.min(...values);
      const max = Math.max(...values);
      stats[col] = { mean, min, max };
    }
  }

  // Write the results back as a new table "my_data_stats"
  await writeTable('my_data_stats', stats);

  // Return a markdown summary that the UI will render
  return {
    markdown: Object.entries(stats)
      .map(([c, s]) => `**${c}** – mean: ${s.mean.toFixed(2)}, min: ${s.min}, max: ${s.max}`)
      .join('\n')
  };
}

To invoke this plugin from the application interface, use the launchTool function as implemented in the launcher component:

// apps/desktop/src/components/ToolLauncher.tsx
import { launchTool } from '@pi/ui';

function runAnalysis() {
  launchTool('example-data-analysis', { tableName: 'my_data' });
}

The run(context) function receives a context object containing the parameters passed from launchTool, allowing dynamic configuration of column selections, filtering criteria, or algorithmic parameters without modifying the plugin code.

Data Storage and Session Replay

All data analysis actions are logged through the message bus, creating a complete audit trail of your workflow. These logs store the sequence of plugin executions, parameter configurations, and data transformations in the workspace folder.

You can replay entire analysis sessions using the Session Replay tool, which re-executes the logged sequence of operations against the original or updated datasets. This feature, backed by the message bus implementation in the host core, ensures reproducibility and allows you to export complete analysis pipelines as shareable scripts.

Summary

• PI Desktop uses a three-process architecture (Rust host, isolated agent runtime, Electron renderer) to safely perform data analysis with PI Desktop without compromising UI stability.
• Data import is handled by crates/host-core/src/storage.rs, supporting CSV, JSON, and Excel formats stored in ~/.pi-desktop/workspace.
• Analysis logic is implemented as JavaScript plugins using readTable and writeTable APIs from @pi/agent-runtime, executed inside packages/agent-runtime/src/runtime.ts.
• Visualization components DataTable.tsx and ChartView.tsx render plugin outputs as interactive tables and charts.
• Session logging via the message bus enables full workflow replay and reproducibility.

Frequently Asked Questions

What file formats does PI Desktop support for data import?

PI Desktop natively supports CSV, JSON, Excel, and plain-text file formats. The import logic resides in the Rust-based host core at crates/host-core, which parses these formats and converts them into internal table representations stored in the workspace directory.

How does PI Desktop isolate plugin execution from the main application?

Plugin code runs inside the agent runtime located at packages/agent-runtime/src/runtime.ts, which operates in an isolated process separate from the Electron renderer and Rust host. This architecture prevents errors or infinite loops in analysis scripts from crashing the UI or corrupting the workspace data.

Where are analysis datasets stored in PI Desktop?

Imported datasets and generated results are stored in the user's workspace at ~/.pi-desktop/workspace. The host core manages persistence through crates/host-core/src/storage.rs, ensuring that tables remain available across application restarts and can be referenced by name in subsequent plugin executions.

How can I replay a previous analysis session?

PI Desktop logs every analysis action through its internal message bus, storing the complete sequence of operations, parameters, and data references in the workspace folder. You can replay these sessions using the built-in Session Replay tool, which re-executes the logged workflow against your data, ensuring reproducibility and auditability.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}