Plugin SDK

Créer pour OpenClone

N'importe quel langage, n'importe quelle source. Un seul endpoint. Votre plugin écrit dans le vault automatiquement. Déduplication, assainissement et isolation tenant inclus.

1 endpoint · 15 source types · 500 events/batch · Any language

Registre de plugins

Plugins officiels et communautaires. Installez, forkez, ou utilisez comme point de départ.

● Stable

Mac System Audio

macOS

System audio capture via ScreenCaptureKit + Whisper STT. Captures all app audio including meetings.

audio_system openclone-mac-audio
● Stable

Mac Screen OCR

macOS

Screenshots active window every 30s + Apple Vision OCR. Captures everything you read and write.

screen_ocr openclone-mac-screen
Beta

Browser Extension

Chrome/Firefox

Captures browsing history, reading time, and article content. Manifest V3.

web_browsing openclone-browser
● Stable

Microphone

macOS / iOS

Ambient microphone capture via AVFoundation + Whisper STT. Voice notes and conversations.

audio_mic openclone-mac-mic
● Stable

Voice Journal

iOS / macOS

Voice notes from the mobile or desktop app. Transcribed and stored in Journal/.

journal
Planned

Windows Audio

Windows

WASAPI Loopback capture — all app audio.

Planned

Windows Screen

Windows

DXGI capture + WinRT OCR.

Planned

Linux Audio

Linux

PulseAudio/PipeWire monitor source.

Planned

Linux Screen

Linux

X11/Wayland screenshot + Tesseract OCR.

Planned

Health

iOS/Android

HealthKit + Health Connect. Steps, sleep, HR, HRV.

Planned

Calendar

All

EventKit + Google Calendar API.

Planned

Obsidian

All

Filesystem watcher on your Obsidian vault.

Planned

Spotify / Last.fm

All

Last.fm scrobbling — works with any music player.

View all on GitHub → · Want to build one? Read on ↓

Référence API — POST /api/v1/ingest

L'unique endpoint que votre plugin appelle. Envoyez des lots d'événements, recevez le nombre de stockés et ignorés.

Request body

POST /api/v1/ingest Content-Type: application/json
{
  "source_type": "audio_system",
  "platform": "macos",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "plugin_id": "openclone-mac-audio",
  "plugin_version": "1.0.0",
  "timestamp": 1708258800.0,
  "events": [
    {
      "timestamp": 1708258800.0,
      "data": {
        "text": "We discussed the product roadmap for Q2.",
        "duration": 60,
        "app_name": "Google Meet",
        "confidence": 0.95
      },
      "raw_ref": "chunk-2026-02-18-14h30-001"
    }
  ]
}

Response (200)

{
  "stored": 3,
  "skipped": 1,
  "file": "Audio/2026-02-26.md"
}

Error codes

401 Invalid or missing X-API-Key
422 Validation error (field details in body)
429 Rate limit exceeded — retry with backoff
500 Storage error — vault write failed

Field reference

Field Type Required Constraints
source_type string yes One of 15 defined types (see below)
platform string yes macos · windows · linux · ios · android · web
device_id string yes UUID v4 — stable across sessions
plugin_id string yes Kebab-case, max 64 chars, alphanumeric + hyphens
plugin_version string yes Semver (1.0.0)
timestamp float yes Unix epoch — not before 2020-01-01, not > +24h
events array yes 1–500 events per request
events[].timestamp float yes Per-event timestamp (same constraints)
events[].data object yes Source-type-specific fields (see Source Types)
events[].raw_ref string no Your unique ID for deduplication — recommended
Auth: Include X-API-Key: your-api-key in every request. Get your key from backend/.env → API_KEY.

Manifeste du plugin — plugin.json

Déclarez les métadonnées de votre plugin. Utilisé pour l'affichage du registre et les contrôles de permission.

plugin.json
{
  "id": "my-audio-plugin",
  "name": "My Audio Capture",
  "version": "1.0.0",
  "platform": ["macos"],
  "source_types": ["audio_system"],
  "sensitivity": "MEDIUM",
  "requires_permissions": ["screen_recording"],
  "config_schema": {
    "chunk_duration": { "type": "integer", "default": 60 },
    "blocklist": { "type": "array", "default": ["Spotify", "Music"] }
  }
}

Field reference

Field Notes
id Unique kebab-case identifier
name Display name in registry
version Semver string
platform macos · windows · linux · ios · android · web
source_types Which source_types this plugin writes
sensitivity LOW · MEDIUM · HIGH · CRITICAL
requires_permissions Platform permissions needed (optional)
config_schema User-configurable settings with defaults (optional)
Place plugin.json at the root of your plugin directory. The backend reads it at startup and registers your plugin in the registry endpoint (GET /api/v1/plugins).

Types de sources

Chaque source_type correspond à un dossier vault et un niveau de sensibilité. Utilisez le plus proche de vos données.

source_type Vault folder Sensitivity Typical data fields
audio_system Audio/ MEDIUM text, duration, app_name, confidence
audio_mic Audio/ HIGH text, duration, confidence
screen_ocr Screen/ MEDIUM text, app_name, window_title, url
journal Journal/ LOW text, duration
web_browsing Web/ MEDIUM url, title, domain, reading_time
music Music/ LOW track, artist, album, duration
health Health/ HIGH steps, heart_rate, sleep_hours
calendar Calendar/ LOW title, start, end, attendees, location
notes Notes/ LOW title, text, tags
gps Location/ MEDIUM lat, lon, accuracy, place_name
photos Photos/ MEDIUM filename, location, timestamp
email Email/ CRITICAL subject, from, to, date (no body)
messaging Messages/ CRITICAL platform, from, preview (local only)
activity Activity/ LOW app_name, duration, category
braindump Braindump/ LOW text
Note on HIGH/CRITICAL types: Always inform users before activating plugins with HIGH or CRITICAL sensitivity. These types capture personal data that users may not want recorded automatically. The backend enforces no technical restriction, but your plugin should default to openclone.enabled: false.

Exemples de code

Exemples prêts à l'emploi pour les langages courants. Remplacez l'URL, la clé et les champs de données.

curl — quickest way to test
curl -X POST http://localhost:8000/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "source_type": "braindump", "platform": "macos",
    "device_id": "test-001", "plugin_id": "my-plugin",
    "plugin_version": "1.0.0", "timestamp": 1708258800.0,
    "events": [{"timestamp":1708258800.0,"data":{"text":"Hello!"},"raw_ref":"e1"}]
  }'

# Response: {"stored":1,"skipped":0,"file":"Braindump/2026-02-26.md"}

Sujets avancés

Déduplication

Chaque événement est dédupliqué côté serveur. Définissez raw_ref sur un ID unique stable par événement. Le backend hache source_type + plugin_id + raw_ref et ignore silencieusement les doublons.

// In your event:
"raw_ref": "chunk-abc123"
// Backend hashes:
source_type + plugin_id + raw_ref
// Duplicate → skipped

Limites de débit

60 requêtes/minute par clé API. 500 événements par lot. 1 Mo max. Timestamps après 2020-01-01, pas plus de 24h dans le futur. Renvoie 429 si la limite est dépassée. Backoff exponentiel recommandé.

60 req / min / key
500 events / batch
1 MB max payload
429 → retry with backoff

Traitement par lots

Bufferisez les événements localement et envoyez-les en lots. Jusqu'à 500 événements par requête. Tous les événements d'un lot vont dans le même fichier .md quotidien. Lots partiels supportés.

// Recommended pattern:
buffer = []
buffer.append(event)
// Every 60s or 100 events:
ingest(buffer[:500])
buffer.clear()
Timestamp rules: Events must have timestamps between 2020-01-01 and now + 24h. Out-of-range timestamps are rejected with a 422. Always use the event's actual capture time, not the send time.

5 minutes to your first memory entry

1

Create plugin.json

Declare your plugin ID, platform, and source type.

"source_type": "braindump"
2

POST your first event

Use the curl example above — one command, 30 seconds.

{"stored": 1}
3

Verify in vault

Open the vault folder. Your .md file is ready.

Braindump/2026-02-26.md

Publier votre plugin

Ouvrez une PR sur le repo PixxzR/openclone pour ajouter votre plugin au registre officiel. Incluez plugin.json, un README et un script d'installation.

PR checklist

  • plugin.json with all required fields
  • README.md with install instructions
  • install.sh (macOS) or setup instructions
  • No hardcoded API keys or personal data
  • Defaults to openclone.enabled: false
  • Source type matches one of the 15 defined types