Tyto

Talk to your notes and they change. Say "rename heading Budget to Costs" or "add apples, bananas and pears under Shopping", and the edit lands in the note you are looking at.

Other voice plugins transcribe what you say into the note. Tyto takes speech that mixes content with formatting and placement, and sorts out which is which. There is no fixed command phrasing to learn, and no chat window to copy an answer out of.

Under the hood it is a model harness: a model with tools to read the vault, run Obsidian commands and write to a note. It runs once per utterance.

Table of Contents

1. Why Tyto
2. What It Can Do
3. It Can Get It Wrong
4. What It Does Not Do
5. What Leaves Your Vault
6. Getting Started
7. Commands and Search
8. Skills and Folder Instructions
9. On Mobile
10. Troubleshooting
11. Contributing and Releasing

Why Tyto

Dictation leaves you the structure to add afterwards: you get the words down, then go back to put them under the right heading. Tyto does that part in the one utterance. It takes the words you want written down, reads what you said about where they go, and makes the change under the heading and in the list you meant.

That matters most when your hands are busy. The panel is a sidebar drawer, one tap from the mobile toolbar, and adding to a shopping list while walking is the case it is designed around. Typing works too, and is the easier way to try it.

Nothing about it is heavyweight. Four runtime dependencies, no database, no embedding index, and vault search that reads your notes directly.

What it cannot promise is being right. A model decides what you meant, so read It Can Get It Wrong before pointing it at notes you care about.

What It Can Do

Out of the box, a turn reads and edits the note in front of you. Anything that reaches past that note waits on a setting: see Commands and Search.

• Edit the note you are on: replace text, insert at a heading or a line, or write the whole note. One utterance can touch several notes.
• Answer a question from the vault, with search on. "What did I write about the roofing quote recently" returns a summary in the panel naming the notes it read, and writes nothing.
• Reach a note you did not open, by an allowed Obsidian command, a path, a glob, or a date phrase. "Saturday last week" resolves to a real date before a filename is guessed.
• Ask you which note, where several match. The pick is also permission to write to it.
• Suggest tags the vault already uses, read from Obsidian's tag index rather than invented, so a suggestion matches what the rest of the vault is filed under.
• Follow the vault's own instructions, from skills and AGENTS.md files. See Skills and Folder Instructions.
• Keep the session across a reload, so a phone evicting Obsidian does not lose the thread. Reset clears it.
• Show its working. The panel lists every step a turn took and what it spent against its budget, and the session transcript setting adds a button that copies the lot as Markdown.

It Can Get It Wrong

A model decides what your instruction meant, and a model is not deterministic. The same words can produce a different edit on a different day. Tyto is built so that a wrong edit is easy to spot, and usually easy to reverse. It cannot stop one happening.

What can go wrong

• The transcriber mishears a name, and the search that follows looks for a word you never said.
• The model picks the wrong heading, the wrong list, or the wrong note, especially where several plausibly match.
• The model answers a question from the notes it happened to read rather than the best ones.
• A long instruction spends its step budget part-done, having made some of its edits and not the rest.

Not every edit is undoable

Tyto writes two ways, and only one of them can be undone.

• Through the editor, where Ctrl+Z and Cmd+Z step back through a turn one edit at a time. This needs the note open in a tab that is still showing it and whose text matches the file on disk.
• Straight to the file, used whenever the editor route is not available. Obsidian's undo history never sees the change, so Ctrl+Z will not take it back.

A direct write is what happens when the note has no tab open, when the tab moved to another note mid-turn, or when a tab is still loading and holds text the file does not. Editing a note the model found by search is the common case: it was not open, so it was written directly.

Tyto tells you when this happened. The step that made the edit reads "Undo not available" in the panel and names the note underneath, because that edit is the one you may have to reverse by hand. Reverse it by editing the note yourself, or from your vault's backup or version control.

What limits the damage

• Tyto writes nothing outside the note it is on unless a command, a search or your own pick sends it elsewhere.
• An answer drawn from search is shown in the panel and never written into a note. An instruction that asks for both an answer and an edit still edits.
• The panel lists each step as it runs. The turn is labelled with the note it is on, and a step shows its own path whenever it edited a different note or wrote directly, so a wrong target is visible rather than silent.

What to do about it

• Read the panel after a turn rather than trusting it. The note names are there for exactly this.
• Undo immediately if an edit is wrong. The further you get from the turn, the more history you step back through.
• Treat an answer as a pointer to the notes it cites, not as the last word.
• Keep the vault in version control or on Obsidian Sync, as you would for any plugin that writes.

What It Does Not Do

• Mistral only, using your own API key. There is no other provider and no local model.
• Manually tested against mistral-medium-latest, the default. The model is a free text field, so another Mistral model will run untested, and a smaller one is likelier to mistake the instruction.
• One turn has a step budget, twenty by default. A long instruction that runs out reports what it did rather than continuing.
• One recording per request, up to Mistral's limits on its latest transcription model, currently 60 minutes or 500 MB. A longer one is rejected rather than split, and the panel offers a retry rather than losing the audio. Normal dictation is nowhere near either, since five minutes is about 1 MB.

What Leaves Your Vault

Tyto sends note content to one remote provider: Mistral, at api.mistral.ai. Nothing is sent anywhere else, and there is no telemetry and no analytics.

What is sent, and when

Two things go to Mistral, and only during a turn you start by recording or typing. Nothing is sent in the background, and nothing while the panel sits idle.

• Your spoken audio, so it can be transcribed.
• The instruction, the text of the note the session is on, any skill the turn matched, any AGENTS.md or CLAUDE.md in that note's folder chain, and search excerpts when vault search is on.

Tyto is an instruction parser, and the parsing is the model's. Turning free speech into a structural edit is what the model does, and no local model does it.

Your key, and what the plugin can reach

A Mistral API key is required, and without one Tyto does nothing. The key is stored in the plugin's folder inside your vault, and is sent only to Mistral.

Before you change any setting, a turn can read and edit the note the session is on, and run one Obsidian command: daily-notes, which creates or reveals your daily note. Vault search is off, and no other command is allowed until you add it. See Commands and Search.

The session transcript is off by default, because it holds your note text and any vault instructions the turn read, verbatim. Turning it on adds a Copy button to the Tyto panel header, for debugging what went wrong. Your API key is never in it. See Reporting a turn that went wrong before posting one.

Getting Started

Tyto needs a Mistral API key. Create one at console.mistral.ai, then open Settings, Tyto, and paste it into Mistral API key. Nothing works without it.

Then try a turn. Use a scratch note for these six, not one you care about: the point is to watch what an edit looks like before you trust it with anything.

1. Open the note and click the mic ribbon icon, or run "Tyto: Start session". The session panel opens in the right sidebar.
2. Type an instruction first, to prove the loop without the mic: "add a heading called Test at the start of the file", then Send.
3. Click Mic, say "rename heading Test to Done", click Stop. The transcript appears, then the edit lands.
4. Try dictation: "make a list of apples, bananas and pears under a heading called Shopping".
5. Try a follow-up: "actually make that heading level two".
6. Press Ctrl+Z / Cmd+Z in the note: the last edit undoes through the native history.

If a step fails, the panel shows an error entry naming the failing step: transcription, chat, or apply.

Those six use the note in front of you. To let Tyto find a note or answer a question from the vault, see Commands and Search.

Commands and Search

Two settings widen what a turn can reach beyond the note in front of you. With both off, Tyto reads and edits only the note the session is on.

The commands you allow

Say "open my daily note and add a paragraph under Meetings", and the note opens, the session moves to it, and the edit lands there.

Tyto runs only the commands you allow. Settings holds one command id or namespace pattern per line, and a collapsed count showing what those entries currently resolve to. The list ships holding daily-notes, which is why that example works out of the box: opening the daily note creates or reveals one note and destroys nothing, which makes it safe to allow unasked. Clear the line to allow nothing.

Write daily-notes for a single command, and open-or-create-file-command:* for every command in a namespace. A pattern's plugin id must be literal, and only a trailing wildcard is allowed. Obsidian's core commands are not namespaced, so daily-notes:* matches none of them.

Vault search

The second toggle, off by default. It is what lets Tyto find a note you did not name exactly, and answer a question from your notes rather than editing one.

Skills and Folder Instructions

Two ways to tell Tyto how this vault writes, so an instruction does not have to repeat the house style every time.

Skills are markdown files in the skills folder set in settings, each with a name and a description in its frontmatter. The description is what the model matches an utterance against, and a matched skill is read before the edit lands.

AGENTS.md and CLAUDE.md files are picked up from the folder chain above the note being written. Unlike a skill, these apply to every write under that folder rather than being matched per utterance.

Neither can widen what the plugin does. A skill naming a tool outside Tyto's own set finds nothing to call.

On Mobile

The session panel opens as a drawer from the right sidebar. To reach it in one tap, add the command to the mobile toolbar: Settings, Mobile, Manage toolbar options, then add "Tyto: Start session". The allowed-command list is a plain text box and the resolved list stays collapsed, so neither fills a phone screen.

What stops a recording

Leaving Obsidian does, because a backgrounded recording captures silence. What was said up to that point is transcribed and acted on rather than discarded, so a locked screen costs the rest of the sentence instead of the whole dictation. Closing the panel does the same.

Collapsing the sidebar does not. The recording keeps running, and nothing is sent until you stop it.

Skills need a normal folder

Obsidian Sync copies no dot-folder to a phone, so a skills path starting with a dot gives an empty catalogue on mobile.

Troubleshooting

• Mic errors: macOS needs microphone permission for Obsidian under System Settings, Privacy and Security.
• 401 errors: check the API key in settings.
• "Undo not available" on an edit: it could not go through the editor, so it was written to the file directly. It landed, but Ctrl+Z will not take it back. See Not every edit is undoable.
• "is not a markdown note": the session is on a canvas, a PDF or a Bases file, which have no editor to write through. Press Reset and start on a note.
• A turn that stops short: it spent its step budget. Raise the budget in settings, or split the instruction in two.
• No skills on mobile: check the skills path in settings is a normal folder, not a dot-folder.

Reporting a turn that went wrong

Turn on the session transcript in settings, reproduce the problem, and copy the session from the panel header. The transcript holds the tool calls and what each returned, which is what makes a bad turn diagnosable after the fact.

Read it before you post it. A transcript is a verbatim copy of your notes: names, dates, reference numbers, whatever the note held. Replace anything you would not publish, keeping the shape of the text, since a name changed to another name still shows a misheard match. Then raise it at github.com/iparips/obsidian-tyto/issues.

Contributing and Releasing

Building from source, running the suite and installing a development build are in docs/CONTRIBUTING.md. Cutting a release is in docs/RELEASE.md.

Every feature here was specified before it was built, and the specs are in docs/spec: 1-upcoming is designed but unbuilt, 2-active is in flight, and 3-archived is what shipped. They are the place to look for why something behaves the way it does.