Plugins & extensions

Furoshiki separates three ideas: the Brain (scheduler + managed services), runtime plugins (PLUGIN.md under $FUROSHIKI_DATA/plugins/), and the extensions hub (delegations, repairs, skill proposals in extension_work_items). This page orients humans; LLMs authoring plugins should follow docs/PLUGIN-SPEC.md as the contract.

Canonical spec — docs/PLUGIN-SPEC.md (v1.1+): hook arguments, env vars, CLI, permissions, and caller map. Delegation and packaged install rules: docs/DELEGATION-AND-SKILLS.md. Unified queue: docs/EXTENSIONS-UNIFIED-PIPELINE.md.

Brain — scheduler, not OS crontab

scripts/brain.py runs scripts/scheduler.py against $FUROSHIKI_DATA/memory/schedules.json. Periodic jobs (soul engine, post-conversation, reflection loops, etc.) are rows in that file. The legacy cron/crontab in the repo is reference-only; Furoshiki does not require installing it for Brain-driven work.

Runtime plugins (PLUGIN.md)

Each plugin is a directory with a YAML manifest and Python entrypoints. Core discovers plugins via scripts/plugin_loader.py. Hooks run as subprocesses with a stable contract — they do not import Telegram or daemon modules directly.

HookPurpose
cron (Brain) Scheduled work. furoshiki plugins reload merges tasks (id prefix plugin__) into schedules.json; Brain runs run_plugin_scheduled.py → your script. Uses UTC five-field cron.
pre_conversation Inject JSON context into session assembly (refresh_session_context.py).
post_conversation After a session, optional side effects (run_post_conversation.py).
pre_reflection / post_reflection Before/after reflection LLM runs (target: deep, inner_monologue, morning, afternoon, all).
callable Named tools for the model (get_callable_manifest / OpenRouter tools / skill_orchestrator).
post_inbound_signals After inbound conversation_mode classification — optional mode tweak + prompt addendum; merged with operator JSON and strict chat_recall clamp (plugin_loader.run_post_inbound_signals).

Scheduled plugin flow

flowchart LR
  subgraph data [Instance data]
    PM[plugins/name/PLUGIN.md]
    SJ[memory/schedules.json]
  end
  subgraph brain [Brain]
    SCH[scheduler.py tick]
    RPS[run_plugin_scheduled.py]
  end
  PM -->|furoshiki plugins reload| SJ
  SCH -->|fires due task| RPS
  RPS -->|subprocess + env| ENT[Plugin entry script]

Extensions hub (operator queue)

extension_work_items is the single SQLite view for delegation jobs, repair jobs, and skill/self-modification proposals. It powers the dashboard Extensions page and furoshiki extensions …. Installing a plugin from a proposal is related but not the same table: apply moves files into plugins/; the queue tracks work items and phases. 

flowchart TD
  subgraph tracks [Work tracks]
    DJ[delegation_jobs]
    RJ[repair_jobs]
    SM[self_modification / skill proposals]
  end
  EWI[extension_work_items]
  DJ --> EWI
  RJ --> EWI
  SM --> EWI
  EWI --> DASH[Dashboard Extensions]
  EWI --> CLI[furoshiki extensions]

CLI (essentials)

See also