# How to Set Up PI Desktop Predictive Maintenance: Skills, MCP, and Subagents Guide

> Learn how to set up PI Desktop predictive maintenance using Skills MCP and Subagents. Monitor your codebase detect anomalies and prevent failures with local data.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**PI Desktop predictive maintenance workflows combine Skills, MCP servers, and Subagents to continuously monitor your codebase, detect anomalies in real-time, and suggest corrective actions before failures occur—all while keeping data local.**

PI Desktop is a local-first desktop workspace designed for AI coding agents to operate on your codebase, tools, and services without sending data to external servers. By leveraging the **Skill** system, **Model Context Protocol (MCP)** infrastructure, and **Subagent** runtime, you can build a PI Desktop predictive maintenance pipeline that analyzes logs, infers degradation patterns, and generates remediation plans without compromising security.

## Architecture Overview

The predictive maintenance loop operates across four distinct layers implemented in the `vastsa/PI-Desktop` repository. Understanding this separation is critical for debugging and extending your maintenance workflows.

The **UI Layer** (React Renderer) provides the **Composer** interface and **Review** panel where you trigger commands and approve changes. The **Electron Main** process orchestrates IPC between the UI, Rust host, and AI sidecar, configured in [`apps/desktop/electron.vite.config.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron.vite.config.ts). The **Rust Host Core** persists conversations and permissions, and handles boot-time cleanup via `boot_maintenance` in [`crates/host-core/src/db.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/db.rs) (lines 47-80). Finally, the **pi Agent Sidecar** streams prompts to your configured model, loads **Skills** on demand, and manages **Subagent** lifecycles, as documented in [`docs/spec/02-architecture/01-architecture.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/02-architecture/01-architecture.md).

All data remains on your machine; model requests route directly to your configured provider (OpenAI, Anthropic, or local), satisfying the local-first guarantee described in the README.

## Step 1: Configure the AI Model

Before implementing predictive logic, configure the underlying model that will analyze your logs and infer maintenance needs.

Open **Settings → Model Configuration** and add your provider credentials. Set the **temperature**, **context window**, and API keys for your chosen endpoint (OpenAI, Anthropic, or a local gateway). This model acts as the "brain" of your PI Desktop predictive maintenance system, interpreting log patterns and generating remediation strategies.

## Step 2: Create the Predictive Maintenance Skill

**Skills** in PI Desktop are cataloged tools that the AI can invoke on demand. Create a skill file named [`predictive-maintenance.skill.json`](https://github.com/vastsa/PI-Desktop/blob/main/predictive-maintenance.skill.json) in your plugin directory:

```json
{
  "id": "predictive-maintenance",
  "name": "Predictive Maintenance",
  "description": "Analyse recent logs and suggest preventative fixes.",
  "type": "skill",
  "runtime": "node",
  "entry": "run.js"
}

```

Register this skill via `contributes.skills` in your plugin manifest, as specified in [`docs/spec/07-plugins/01-plugin-system.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/01-plugin-system.md). The skill body is fetched only when the model calls the built-in `Skill` tool, keeping the system prompt lightweight.

The [`run.js`](https://github.com/vastsa/PI-Desktop/blob/main/run.js) entry point implements the analysis logic. This script executes in an isolated Node.js runtime and can fetch logs from your MCP server:

```javascript
const { fetch } = require('node-fetch');

module.exports = async (args) => {
  const resp = await fetch('http://localhost:3000/logs/getRecent?count=100');
  const logs = await resp.text();

  // Flag ERROR entries older than 24 hours
  const errors = logs
    .split('\n')
    .filter(line => /ERROR/.test(line) && new Date(line.slice(0,19)) < Date.now() - 86400000);

  if (errors.length === 0) return "No critical errors detected – system is healthy.";

  return `Found ${errors.length} stale error entries. Suggested actions:\n` +
         errors.map(e => `• Investigate: ${e}`).join('\n');
};

```

This implementation queries your MCP endpoint, applies a heuristic filter for stale errors, and returns a structured remediation plan.

## Step 3: Expose Logs Through an MCP Server

The **Model Context Protocol (MCP)** allows the agent to query external data sources without leaving the desktop environment. Implement a lightweight MCP server to expose your application logs:

```javascript
const express = require('express');
const fs = require('fs');
const app = express();

app.get('/logs/getRecent', (req, res) => {
  const count = parseInt(req.query.count) || 50;
  const logs = fs.readFileSync('/var/log/myapp.log', 'utf8')
                .split('\n')
                .slice(-count)
                .join('\n');
  res.send(logs);
});

app.listen(3000, () => console.log('MCP server listening on 3000'));

```

Register this server in **Settings → MCP → Add Server** with the local URL (e.g., `http://localhost:3000`). The Electron main process will forward calls from the agent sidecar to this endpoint, enabling real-time log analysis for your PI Desktop predictive maintenance workflow.

## Step 4: Configure a Background Subagent

**Subagents** run isolated, long-running loops that keep the main UI responsive. Define a subagent to periodically invoke your predictive maintenance skill without manual intervention.

Create [`maintenance-subagent.json`](https://github.com/vastsa/PI-Desktop/blob/main/maintenance-subagent.json) in your plugin's `subagents/` folder:

```json
{
  "id": "maintenance-monitor",
  "schedule": "*/5 * * * *",
  "task": {
    "type": "invokeSkill",
    "skillId": "predictive-maintenance",
    "args": {}
  }
}

```

The `schedule` field uses cron syntax to run every 5 minutes. When triggered, the subagent invokes the skill, and results appear as new turns in the **Composer**. The Rust host core manages subagent lifecycles and database cleanup through the `boot_maintenance` function in [`crates/host-core/src/db.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/db.rs), ensuring failed runs don't corrupt state.

## Triggering and Reviewing Maintenance Actions

To manually trigger the workflow, open the **Composer** and type `/predictive-maintenance`. Alternatively, click the **Predictive Maintenance** button on a custom panel if configured.

The model receives the latest logs via the MCP server, executes the skill logic, and returns a remediation plan. This plan appears in the **Review** panel, where you can inspect diffs, run generated tests, and approve or reject each suggested change. Only vetted modifications reach your codebase, preserving auditability and safety.

## Summary

- **PI Desktop predictive maintenance** combines three core primitives: **Skills** for analysis logic, **MCP servers** for data access, and **Subagents** for scheduling.
- The architecture separates concerns across React (UI), Electron (IPC), Rust (persistence), and the Agent sidecar (AI execution), ensuring responsive monitoring.
- Skills are registered via `contributes.skills` in the plugin manifest and loaded on-demand via the built-in `Skill` tool.
- The Rust host's `boot_maintenance` function in [`crates/host-core/src/db.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/db.rs) handles cleanup and database preparation for subagent tasks.
- All data remains local; model requests route directly to your configured provider without intermediate servers.

## Frequently Asked Questions

### How does PI Desktop keep predictive maintenance data secure?

All log analysis and model inference occur locally on your machine. PI Desktop operates on a local-first architecture where the Rust host core stores conversations and permissions locally, and model requests are sent directly to your configured provider (OpenAI, Anthropic, or local gateway) without passing through third-party servers. Your logs never leave the machine unless you explicitly configure external MCP servers.

### Can I use a local model instead of OpenAI or Anthropic for predictive maintenance?

Yes. PI Desktop supports any provider that offers an OpenAI-compatible API endpoint. In **Settings → Model Configuration**, add your local gateway URL (such as Ollama or LM Studio) and adjust the context window settings accordingly. The predictive maintenance skill will route all inference requests to this local endpoint.

### What happens if a Subagent fails during a maintenance check?

The Rust host core includes a `boot_maintenance` routine in [`crates/host-core/src/db.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/db.rs) that runs at startup to clean up unfinished or crashed subagent runs. This ensures that failed monitoring tasks don't leave the database in an inconsistent state. Failed subagents log errors to the host console, visible in the **Developer Tools** panel, and can be restarted manually from the Subagent management interface.

### How do I adjust the frequency of predictive maintenance checks?

Modify the `schedule` field in your subagent configuration file (e.g., [`maintenance-subagent.json`](https://github.com/vastsa/PI-Desktop/blob/main/maintenance-subagent.json)) using standard cron syntax. For example, change `*/5 * * * *` to `0 */1 * * *` to run hourly instead of every five minutes. The schedule is parsed by the host core and triggers skill invocations accordingly without requiring app restarts.