ext-develop

Extension Development

Build an OpenClacky extension end to end — scaffold, edit, verify, hot-reload, and (only when asked) publish. Prefer editing real files and verifying over describing.

The extension model (ground truth)

An extension is one directory with a single ext.yml manifest declaring contributes:. Nothing is nested — units reference each other by id. It survives gem update and never requires editing gem source.

Three layers, override precedence local > installed > builtin:

• builtin — bundled in the gem (default_extensions/)
• installed — ~/.clacky/ext/installed/<id>/ (from ext install)
• local — ~/.clacky/ext/local/<id>/ (where users develop; ext new lands here)

Eight contributes: types (use one, several, or all):

• panels — WebUI panels (a view.js, no build step, no React, no iframe)
• api — one backend file api/handler.rb, mounted at /api/ext/<id>/
• skills — a SKILL.md under skills/<id>/ (prompt-only capability)
• agents — a system_prompt.md; can reference panels: [id] and skills: [id]; hidden: true hides from the new-session picker
• channels — an IM adapter
• patches — monkey-patch a real class (advanced, supply-chain risk)
• hooks — lifecycle hooks like before_tool_use (advanced)
• tools — a custom agent tool (a Clacky::Tools::Base subclass in tools/<id>.rb)

Hot reload is per-request: after editing view.js, handler.rb, or a SKILL.md, the user just reloads the WebUI page — no server restart. Editing ext.yml also applies on the next load.

Hard rules — never break these

• ❌ Never edit the gem source. Do NOT bundle show openclacky and change files in there. Everything lives in ~/.clacky/ext/local/<id>/ and survives gem update.
• ❌ Never restart the server to apply a change. Hot reload is per-request — the user just reloads the WebUI page. If you're telling them to restart, you're wrong.
• ❌ Never declare success on "it should work." A task is done only when clacky ext verify is clean AND the user reloaded and saw it work. Run verify — don't imagine its output.
• ❌ Never add patches: or hooks: unless the user explicitly asks. They run arbitrary Ruby and carry supply-chain risk. Default to panels/api/skills/agents.
• ❌ Never publish on your own initiative. Publishing is opt-in — see Publish.
• ❌ Never write window.Sessions / "Sessions" in window in view.js. Host services are const bindings, not window properties — such checks return undefined/false even when loaded. Always use Clacky.Sessions.* etc.
• ✅ Always work in the local layer (~/.clacky/ext/local/<id>/). ext new lands there; that's the only layer you edit.