Plugins

A plugin is an extension that adds a new feature to Zettly. Plugins can add a small tool (a focus timer), a file browser, a connector to an external service, or on-device AI models. Plugins are how Zettly grows without growing the core app.

The plugin system is designed around three ideas: easy to install, easy to control, easy to trust. Install from a marketplace with one click. Configure each plugin independently. Verify the integrity of every plugin before it runs.

This page covers what plugins are, how to install and configure them, featured marketplace plugins, and the security model.

What a plugin is

A plugin is a packaged extension that lives alongside the core app. It can:

• Add a new tool or surface. A timer widget. A new view on a board. A keyboard shortcut for a specific action.
• Connect to an external service. A web search bridge. A calendar provider. A project tracker.
• Add on-device AI. Local chat, embedding, and image models via the Local AI Models plugin. See Memory & RAG.
• Add a UI panel. A new sidebar tab. A dashboard card. A status bar widget.

What a plugin does not do:

• Plugins can’t modify the core app. Plugins run in a sandboxed environment with a clear API. They can’t reach into the app’s internals or replace core behavior.
• Plugins can’t read notes without permission. The first time a plugin wants to read your vault, it asks. You can grant or deny the permission.
• Plugins can’t make network requests without declaration. Any external service a plugin talks to is declared in its manifest and shown to you at install time.

The model is “ask first, act later.” A plugin that wants to do something new has to declare it, and you have to approve it.

Not everything is a plugin. Suggest note improvements (AI tag/link/summary suggestions) and other background automation are built into the core app as Flows. Enable them in the Flows rail — see Memory & RAG.

The marketplace

Plugins are distributed through an external official store at store.zettly.studio. Plugin bundles download at install time and are not bundled with the core app.

A few things about the marketplace:

• Verified before activation. Every official plugin release includes a SHA-256 checksum. The app verifies the hash before running plugin code.
• One-click install. Click install in Settings → Plugins → Marketplace. The app downloads from the store, verifies, and activates.
• Versioned releases. Each plugin has semver releases on the store CDN.
• Easy to remove. Uninstall removes plugin code from your vault and revokes permissions.

The store carries three official Zettly plugins today.

Browse the public gallery: zettly.studio/plugins (marketing site).

Featured marketplace plugins

Three plugins are good starting points — install them from the marketplace like any other extension.

Pomodoro timer

A focus timer with configurable work and break intervals. Install from the marketplace. The Pomodoro plugin adds a small timer widget that runs in the sidebar, with:

• Configurable work intervals. Default is 25 minutes.
• Configurable break intervals. Default is 5 minutes for short breaks, 15 for long ones.
• A cycle counter. Tracks how many Pomodoros you’ve completed in a session.
• Optional integration with tasks. The plugin can suggest pulling a task from the Tasks hub to focus on, and (optionally) mark the task as in-progress while the timer is running.

The Pomodoro is a small, focused plugin. It’s a good example of a plugin that adds a tool without trying to do too much.

Local AI Models

The on-device AI plugin. Install it from the marketplace (id zettly-local-models) — it is not bundled with the core app or the desktop installer. When installed, Local AI Models lets you run GGUF chat models, ONNX embedding models, and local image generation entirely on your machine. Nothing leaves your computer.

The plugin adds its own Local models settings section with a hardware-fit wizard: it scans your machine, recommends a model that fits, and downloads it from Hugging Face when you install. Use it for private AI assistant chat and for local embeddings in Memory & RAG. Without this plugin installed, only cloud AI providers and cloud embeddings are available.

Local AI Models is the largest plugin in the marketplace today. It’s also the one to install first if you want the assistant to run without sending your vault to a cloud provider.

File Manager

A trusted main-thread plugin for vault file operations. Install from the marketplace (id zettly-file-manager). It adds a Files tab with drag-and-drop between the Explorer sidebar, boards, decks, and chat attachments.

File Manager needs broader filesystem permissions than most plugins (vault-readwrite). Review the permission list at install time.

Per-plugin settings

Each plugin has its own settings panel. You can configure:

• On/off. A master switch for the plugin. Off means the plugin is installed but not running.
• Permissions. The data the plugin can access. A plugin that wants to read your notes asks; you can grant or revoke at any time.
• Plugin-specific options. The Pomodoro’s work interval. Local AI Models’ active chat and embedding models. Each plugin has its own options.
• Storage. Some plugins store data in your vault. The settings panel shows what data the plugin has stored and lets you clear it.

Settings are per-vault. A plugin can be configured differently in your work vault and your personal vault.

Permissions

The permission system is the part of the plugin model that matters most for trust. Plugins ask before they act, and you can revoke any permission at any time.

The standard permission categories:

• Read notes. The plugin can read the content of notes in the active vault.
• Write notes. The plugin can create or modify notes. (Most plugins don’t ask for this — they propose changes through the preview flow instead.)
• Read tasks. The plugin can read the Tasks hub.
• Write tasks. The plugin can create or modify tasks.
• Read calendar. The plugin can read the Calendar surface.
• Read boards. The plugin can read board layouts and widgets.
• Write boards. The plugin can create or modify boards.
• Read decks. The plugin can read slide decks.
• Write decks. The plugin can create or modify decks.
• Read & write files. The plugin can access files in the vault beyond notes.
• Network access. The plugin can make HTTP requests. The destinations are declared in the manifest.
• Show notifications. The plugin can surface system or in-app notifications.
• MCP connector access. The plugin can talk to an external MCP connector (mcp:<connector-id>).

Each plugin manifest also declares a filesystem scope: none, vault-readonly, or vault-readwrite. This is separate from the per-resource permissions above and controls how broadly the plugin can touch vault files.

When a plugin is installed, you see the list of permissions it asks for. You can grant all, grant selectively, or deny installation. After install, you can revoke any permission from the plugin’s settings. Revoking a permission that a plugin needs to function will pause the plugin and tell you why.

Per-plugin toggles

Beyond the on/off master switch, many plugins have per-feature toggles. A few examples:

• The Pomodoro has toggles for task integration, sound effects, and break-reminder behavior.
• Local AI Models has toggles for the active chat model, embedding model, runtime mode (auto or CPU-only), and GPU acceleration.
• A web search bridge has a toggle for whether it should be used by default or only when explicitly asked.

The principle is the same: each plugin gives you as much control as makes sense, with sensible defaults.

Security: how plugins are verified

Trust in a plugin system comes from verification. Zettly’s plugin system is designed to be auditable.

Every plugin in the marketplace:

• Ships as a versioned release. A plugin is a specific version, with a clear changelog and a date.
• Has a SHA-256 checksum. The package’s checksum is published with the release. When you install, the app verifies the checksum matches before activating.
• Was manually reviewed. A human reviewed the plugin’s manifest, its permissions, and its behavior. The review is the gate.
• Has a declared permission list. The manifest declares every permission the plugin needs. The list you see at install time is the list the plugin will use — no more.
• Runs in a sandboxed environment. The plugin can’t reach into the app’s internals or the file system at large.

The combination of checksum verification, manual review, and sandboxing is what makes the marketplace safe to install from. You don’t have to take a plugin’s word for what it does; the manifest is the contract.

A few practical notes:

• Self-hosted plugins are possible. If you want to install a plugin that isn’t in the marketplace (a plugin you wrote, or one from a trusted source), the app supports loading it from a local file. The same checksum and manifest model applies.
• Plugin updates are signed. When a plugin updates, the new version is verified against its checksum. If the checksum doesn’t match, the update is rejected.
• Plugins can be uninstalled cleanly. Uninstalling removes the plugin’s code, revokes its permissions, and (optionally) deletes its stored data.

A note on alpha status

The plugin system is functional but new. The marketplace is small, and the most useful plugins today (Pomodoro, Local AI Models, File Manager) are downloadable from the marketplace. As the alpha progresses, the marketplace will grow.

If you have an idea for a plugin, or you want to write one, see the developer documentation (which lives elsewhere; this is the user-facing docs page). For users, the plugin system today is: a small but solid marketplace, three well-tested featured plugins, and a security model that makes trying new plugins low-risk.

Tips and conventions

A few things that aren’t obvious until you’ve installed a few plugins:

• Start with featured plugins. Pomodoro, Local AI Models, and File Manager are good test cases for the plugin model. Install them from the marketplace, configure them, see how the permission flow feels.
• Read the permission list. When you install a plugin, the permission list is the contract. If a plugin asks for permissions that don’t match what it does, don’t install it.
• Revoke unused permissions. If a plugin has access to something it doesn’t need, revoke it. The plugin will tell you if it can’t function without the permission.
• Update plugins on a schedule. Plugin updates are versioned and checksummed. Updating is safe; not updating means missing security fixes.
• Uninstall cleanly. When you don’t need a plugin anymore, uninstall it. The permission and data cleanup is automatic.

See AI assistant for the plugin-adjacent features of the AI system, and Memory & RAG for built-in Suggest note improvements and Chat Inbox review.