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

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. The Rust Host Core persists conversations and permissions, and handles boot-time cleanup via boot_maintenance in 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.

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 in your plugin directory:

{
  "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. The skill body is fetched only when the model calls the built-in Skill tool, keeping the system prompt lightweight.

The 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:

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:

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 in your plugin's subagents/ folder:

{
  "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, 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 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 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) 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.

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