Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

temps-plugin

Build external plugins for the Temps deployment platform. Use when the user wants to create, modify, or debug a Temps plugin binary — a standalone Rust process that communicates with Temps over a Unix domain socket. Also use when the user mentions "temps plugin", "external plugin", "plugin binary", "plugin for temps", "plugin UI", or asks about plugin architecture, plugin events, plugin manifest, or plugin SDK. Covers the full lifecycle: project scaffolding, manifest, router, events, SQLite persistence, embedded React UI, build.rs, testing, and deployment into the plugins directory.

gotempsh · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add gotempsh/temps --skill temps-plugin

About this skill


name: temps-plugin description: > Build external plugins for the Temps deployment platform. Use when the user wants to create, modify, or debug a Temps plugin binary — a standalone Rust process that communicates with Temps over a Unix domain socket. Also use when the user mentions "temps plugin", "external plugin", "plugin binary", "plugin for temps", "plugin UI", or asks about plugin architecture, plugin events, plugin manifest, or plugin SDK. Covers the full lifecycle: project scaffolding, manifest, router, events, SQLite persistence, embedded React UI, build.rs, testing, and deployment into the plugins directory.

Temps Plugin Development

Build external plugins as standalone Rust binaries that Temps discovers, spawns, and proxies to.

Architecture Overview

Temps (main process)
  ├── Scans ~/.temps/plugins/ for binaries
  ├── Spawns each binary with --socket-path, --auth-secret, --data-dir
  ├── Reads JSON manifest from stdout (handshake phase 1)
  ├── Reads ready signal from stdout (handshake phase 2)
  ├── Opens WebSocket to plugin's /_temps/channel (bidirectional data access)
  ├── Proxies /api/x/{plugin_name}/* → Unix socket
  ├── Serves plugin UI at /api/x/{plugin_name}/ui/*
  └── Delivers platform events over the WebSocket channel

Plugins are self-contained binaries. They own their own HTTP routes (axum Router), optional React UI (embedded via include_dir), and SQLite database (via sea-orm in their data_dir).

Critical Rules

NEVER

  • Register a /health route — the SDK runtime already provides one. Axum panics on Router::merge with duplicate routes.
  • Use rt.block_on() directly inside router() — it deadlocks. Use tokio::task::block_in_place(|| Handle::current().block_on(...)) instead.
  • Use #[tokio::main] — the SDK creates its own runtime via run_plugin().
  • Access the Temps database directly — use ctx.temps() for platform data queries over the WebSocket channel.
  • Use sea-orm with the main Temps database — plugins get their own SQLite in data_dir.
  • Return anyhow::Result — use typed error enums with thiserror.
  • Use .unwrap() or .expect() in production paths.

ALWAYS

  • Use temps_plugin_sdk::main!(YourPlugin) as the entry point.
  • Implement ExternalPlugin trait with manifest() and router() at minimum.
  • Use block_in_place for any async initialization inside router().
  • Embed the UI with include_dir!("$CARGO_MANIFEST_DIR/web/dist") and serve via own routes.
  • Keep tests in the same file as the code they test (#[cfg(test)] mod tests).
  • Run cargo check -p your-plugin after every modification.
  • Run cargo test -p your-plugin to verify tests pass.

Project Structure

examples/your-plugin/
├── Cargo.toml
├── build.rs              # Builds web UI (bun + vite), creates fallback in debug
├── src/
│   ├── main.rs           # Plugin struct, manifest, router, on_event, UI handlers, entry point
│   ├── db.rs             # SQLite persistence (sea-orm entities + raw DDL migrations)
│   ├── types.rs          # Shared types (Settings, API DTOs) — all serde(rename_all = "camelCase")
│   └── ...               # Additional modules as needed
└── web/                  # React UI (Vite + TypeScript)
    ├── package.json
    ├── vite.config.ts    # base: "/api/x/{plugin_name}/ui/"
    ├── tsconfig.json
    ├── index.html
    └── src/
        ├── main.tsx
        ├── App.tsx
        ├── api.ts        # API_BASE = "/api/x/{plugin_name}"
        ├── types.ts
        ├── router.ts     # Hash-based routing with useSyncExternalStore
        ├── styles.css
        └── components/

Step-by-Step: Creating a New Plugin

1. Cargo.toml

[package]
name = "temps-your-plugin"
version = "0.1.0"
edition = "2021"
publish = false

[[bin]]
name = "temps-your-plugin"
path = "src/main.rs"

[dependencies]
temps-plugin-sdk = { path = "../../crates/temps-plugin-sdk" }
axum = { version = "0.8" }
sea-orm = { workspace = true }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
chrono = { version = "0.4", features = ["serde"] }
thiserror = { workspace = true }
include_dir = "0.7"
mime_guess = "2.0"
# Add reqwest, scraper, url, uuid etc. as needed

[dev-dependencies]
tempfile = "3"

Add the crate to the workspace Cargo.toml members list:

members = [
    # ...existing...
    "examples/your-plugin",
]

2. build.rs

Copy from the reference implementation. Key behavior:

  • Debug mode (default): Skips web build, creates fallback web/dist/index.html so include_dir! doesn't fail.
  • Release mode (or FORCE_WEB_BUILD=1): Runs bun install + bun run build.
use std::env;
use std::path::Path;
use std::process::Command;

fn main() {
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
    let web_dir = Path::new(&manifest_dir).join("web");
    let dist_dir = web_dir.join("dist");

    println!("cargo:rerun-if-changed=web/src");
    println!("cargo:rerun-if-changed=web/index.html");
    println!("cargo:rerun-if-changed=web/vite.config.ts");
    println!("cargo:rerun-if-changed=web/package.json");
    println!("cargo:rerun-if-env-changed=FORCE_WEB_BUILD");

    let profile = env::var("PROFILE").unwrap_or_default();
    if profile == "debug" && env::var("FORCE_WEB_BUILD").is_err() {
        println!("cargo:warning=Skipping plugin web build in debug mode (use FORCE_WEB_BUILD=1 to build)");
        let _ = std::fs::create_dir_all(&dist_dir);
        let fallback = dist_dir.join("index.html");
        if !fallback.exists() {
            let _ = std::fs::write(&fallback, r#"<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>Plugin (dev)</title></head>
<body style="font-family:system-ui;padding:2rem;color:#a1a1aa;background:#09090b;text-align:center">
<h2>Plugin UI not built</h2>
<p>Run <code style="color:#3b82f6">cd examples/your-plugin/web && bun install && bun run build</code></p>
<p>
Read the complete source ↗