AI assistant

The AI assistant is a chat surface that knows your vault. It can answer questions about your notes, summarize a long document, find a passage you half-remember, draft a deck from a board, schedule a week’s worth of tasks, or propose edits to a note — and every answer cites the notes it came from, and every edit comes with a preview you approve before anything saves.

The design philosophy is propose, don’t impose. The assistant is a collaborator, not an autopilot. It suggests; you decide. Everything it does is reversible in one click.

This page covers what the assistant is, how it works, how to set it up, and the agent and skill system that lets you customize it.

What the assistant can do

A short list of the things people use the assistant for:

• Answer questions about your vault. “What did I decide about the launch pricing?” The assistant searches the notes, finds the relevant passages, and answers with citations — links to the notes and the specific sections they came from.
• Summarize a long note. “Summarize my reading of the shoreline essay.” The assistant reads the note, produces a tight summary, and points to the source.
• Find things you half-remember. “Where’s the note about the client call last month?” The assistant searches semantically, not just by keyword, so it can find the note even if you don’t remember the exact words.
• Draft a deck from a board. “Make a 10-slide deck from this board.” See the agent section below.
• Schedule tasks. “Schedule the launch tasks for next week.” The assistant proposes a schedule, you review and accept. See Calendar for details.
• Propose edits to a note. “Tighten the opening paragraph of the shoreline essay.” The assistant shows a preview of the proposed edit, side-by-side with the current text. You accept or reject.
• Create a new note from a prompt. “Start a note on what we learned from the launch retrospective.” The assistant drafts the note and proposes a title. You accept and edit.
• Find connections. “What notes are related to the design system work?” The assistant walks the wikilink graph and the tag structure, and proposes links you might add.

A few things the assistant explicitly does not do:

• It doesn’t edit your vault without preview. Every change comes with a preview. Nothing is merged until you accept.
• It doesn’t talk to the open web by default. Answers cite your notes, not Wikipedia or Reddit. The assistant is grounded in your vault.
• It doesn’t share your data with anyone unless you ask it to. The provider you choose sees only the content you actively put in front of the assistant. See the privacy section below.

How it works

The assistant is a chat panel that lives in the sidebar. You type a question or a request, and it responds in a conversation. Behind the scenes:

1. Your message goes to the assistant. The assistant uses a mix of your active note, the linked context you provide, and the search results from the RAG system to find relevant material.
2. The assistant drafts a response. The response can include text, citations, and proposed actions (edit a note, create a task, build a deck, etc.).
3. The response shows in the chat. Citations are clickable — they jump to the note they came from. Proposed actions come with a preview.
4. You accept, reject, or refine. Every action has a preview. Accepting applies the change; rejecting discards it. Refining lets you ask for a different version.
5. The conversation is preserved. The chat is a real thing in your vault. You can scroll back, copy out useful answers, and reference past conversations.

The assistant is grounded in your vault. The default behavior is to answer with citations to your notes, not the open web. This is a deliberate design choice — the assistant is meant to be a thinking partner for your work, not a generic chatbot.

Provider settings: bring your own

The assistant works with a range of AI providers. You bring your own API key, install the Local AI Models plugin, or point Zettly at a server you run yourself. Nothing is sent to a provider you haven’t configured.

The supported providers include:

• OpenAI (GPT-4, GPT-4o, and other models). You provide an OpenAI API key.
• Anthropic (Claude). You provide an Anthropic API key.
• Google Gemini. You provide a Google AI API key.
• Local AI Models — on-device GGUF models via the zettly-local-models plugin. Install it from the Plugins marketplace; it is not bundled with the app. Runs entirely on your machine; nothing leaves. Model download and the hardware-fit wizard live in the plugin’s Local models settings section.
• Ollama / LM Studio / llama.cpp server — point Zettly at any OpenAI-compatible HTTP server you run yourself. Still local, but you manage the server and models outside Zettly.

A few practical notes:

• Provider choice is per-vault. You can have one vault using a local model and another using a cloud provider. The choice is in the vault settings.
• API keys are stored locally. The keys are kept in your vault, encrypted at rest. They never leave your machine except to authenticate with the provider.
• The model can be switched per task. Some tasks (summarization) work well with fast, cheap models. Others (deep research) benefit from a more capable model. You can configure the default per task type, or override per conversation.
• Local models are slower but private. On-device models require the Local AI Models plugin. A local model on a laptop will be slower than a cloud model, but the plugin’s wizard picks a model that fits your hardware. The tradeoff is privacy and cost. For a vault of personal notes, a local model is often the right choice.

Agent delegation: specialists for big jobs

The main assistant can delegate to specialist agents. Each agent is a tuned version of the main model, configured with a specific role and tool set.

The current specialists:

• Deck builder. Creates slide outlines from boards or notes. Asks for the goal, the audience, and the desired length, then proposes a slide sequence. Each slide is a draft — widgets placed, titles written, supporting shapes added. You review the deck in the deck editor.
• Board architect. Composes board layouts. Given a goal (“a launch board for the Q2 release”), the agent proposes a layout — a project note, a task list, a calendar week, a graph view, all positioned and connected. You review the proposed board and accept.
• Research. Gathers and summarizes with citations. Given a question, the agent searches the vault, pulls in the relevant passages, and produces a summary with footnotes. Useful for “what do I know about X?” questions.

Task triage and calendar sweeps stay on the main assistant via skills (task-triage, calendar-sweep). You can still create extra specialists from the agent wizard if you want named people for those jobs.

You don’t need to know the agents exist to use them. The main assistant routes to the right specialist based on what you ask for. But you can also invoke a specialist directly from the assistant’s menu.

Skills: teach the agent new tricks

A skill is a natural-language instruction bundle that tells the agent how to handle a specific task. Skills are how you customize the assistant without writing code.

A skill is a Markdown file in your vault’s skills folder. It has a name, a description, and instructions. When the assistant thinks a skill is relevant, it reads the instructions and follows them.

A few examples of useful skills:

• A weekly review skill. Instructions for the agent to walk through the week’s notes, summarize the highlights, and propose tasks for the coming week.
• A meeting-notes skill. Instructions for the agent to extract action items from a meeting note and file them in the Tasks hub.
• A writing-feedback skill. Instructions for the agent to act as a writing coach, with a specific style of feedback.

Skills are written in plain English. You don’t need a developer to create one. The assistant reads them like instructions and applies them when relevant.

MCP bridges: connect to external tools

MCP (Model Context Protocol) bridges are how the assistant connects to external tools — your calendar provider, a project tracker, a search service, anything that speaks MCP. The bridge runs locally, and the assistant can call the tools it exposes.

A few practical uses:

• A calendar bridge. Read events from an external calendar, write events back. (Some users prefer this to the standard Calendar import; the bridge keeps the source of truth in the external system.)
• A web search bridge. When the assistant’s default is to cite only your notes, a web search bridge lets you opt in to web results for specific queries.
• A task tracker bridge. Sync tasks with an external system like Linear, Jira, or GitHub Issues.

Bridges are configured in the assistant’s settings. Each bridge asks for permission to access the data it needs, and you can revoke that permission at any time. See Plugins for the broader plugin system, which includes bridges.

A note on alpha status

The AI assistant is the part of Zettly that’s most actively evolving. The core experience — chat, citations, previews, undo — works. The specialist agents are functional but rough. The MCP bridge system is new and not every provider has been tested. Expect some bumps.

If you find a case where the assistant does something surprising, file a bug. The team is paying close attention to the AI experience, and the alpha feedback is what shapes the next iteration.

Tips and conventions

A few things that aren’t obvious until you’ve used the assistant for a while:

• Cite the assistant’s citations. When the assistant says “in the meeting note from April 15,” open the note and verify. The assistant is usually right, but you’re the one who needs to trust the answer.
• Previews are not suggestions. The preview is what will be written. Read it like a real change. If the preview isn’t what you want, reject it and ask for a different version.
• Use specialists for big jobs. A 30-slide deck or a full week of scheduling is a specialist job. Ask the assistant to “use the deck builder agent” or just describe what you want — the assistant will route.
• Skills are the way to customize. If you find yourself writing the same instruction twice, turn it into a skill.

See Memory & RAG for how the assistant grounds its answers, and Plugins for the broader extension system.