README file from
GithubYoofloe
Research, write and organize your Obsidian Markdown with your own OpenAI API key. Visit www.yoofloe.com for Yoofloe apps and support. Use one workspace from the sparkle ribbon, note header, note menu, or Yoofloe: Open command. Yoofloe Calendar and ChronoHUD are optional. Open Yoofloe on its own whenever you need it, including without an open note.
Requires Obsidian 1.11.5+. The same implementation runs on desktop and mobile. The 0.7.0 release was verified in Windows Obsidian and on a physical Android phone; iOS and physical tablet verification are not included in that evidence.
Start
- Install Yoofloe, plugin ID
yoofloe, and open its sparkle workspace. - Open settings, choose a model, enter your own OpenAI key, and choose Save once. The same button stores model/thinking settings and the new key together. An empty key field keeps the existing key. The UI confirms local storage; it does not make a paid key-validation call.
- Describe the task. Attach the current note or use + to add images, documents and audio. Expanded is the default; choose Provided only when factual evidence must stay within supplied material.
- Check Allowed actions, Notes AI can read, Write target, the working/output folder, model, thinking depth and maximum requests. Preview data previews the initial input locally.
- Send starts the task and authorizes its permitted reads and changes. The same fixed-size button becomes Stop during work. A task can make several paid API requests. Choose 1 request, Custom…, or No limit. No limit is the new default; explicitly saved limits remain available as Custom. No-limit mode continues until completion, Stop or a technical stopping condition; API charges can accumulate. It does not remove provider context/rate/credit limits. There are no automatic retries.
At a finite boundary the task pauses. Increase the total limit or choose no count limit, then Continue using the same model, original scopes, tool results and cumulative usage. Completed writes are not replayed. Finish here ends continuation without sending another request. Continuation is available while the current vault session stays open; closing/restarting the app keeps saved answers and completed changes but does not automatically resume requests. If an OpenAI host lookup failure pauses the task, restore the connection and choose Continue in that vault session. On Android, long OpenAI replies use an HTTP stream. The plugin waits for the final response before executing any returned note edits.
Opening the first note connects it to a conversation that has no note, even when an earlier answer or unsent draft is present. Once a note is connected, browsing another note offers Use opened note above the conversation; it never silently switches the active task. The header paperclip opens Choose note, including Chat without a note. Choosing a different note keeps the conversation, draft and permission settings. Running or paused tasks keep their original note.
The conversation stays above the settings, and each area scrolls independently. Drag the divider up or down to resize the two areas. You can also focus it with Tab and use the arrow keys. The split is remembered on this device; double-click the divider or press Enter to reset it. Choose Expand settings to give the settings the full available panel height, then Back to chat to return to the same conversation and draft. Stop stays available while a task runs with settings expanded. Model and permission cards sit below it; Calendar, activity, privacy and recovery remain compact. Conversation search is local: it searches saved requests, answers and attachment names, highlights matches, and pages through older archived conversations without an AI request. Previews remain bounded for mobile performance. Follow-ups in the same conversation retain recent user directions when you connect another document or change models. For example, after asking for Polish readings in parentheses, choose another note and ask to do the same there. The current note and Access settings govern the new task. Recent directions use a bounded local context budget.
Open the conversation’s Conversation actions menu to Copy conversation or Select messages. Choose individual requests and responses, then Copy selected. The copy button on a response copies its Markdown. Drag across conversation text and right-click Copy for a partial selection. Touch devices support text selection and the message selection controls. Full and selected message copies load their saved original text, including older messages. The conversation shows user requests, assistant answers, actual confirmed operations, sources and returned files.
The task reads relevant excerpts as needed within your chosen data scope; it does not upload the whole vault upfront. The model control shows the full GPT version/name and the exact selected API model ID. Images use GPT-Image-2.6 Flare. Image planning uses Low for Fast/Light or Model default, Medium for Balanced, and High for deeper settings. This separate image setting keeps Fast text responses compatible with image generation; image rendering can still incur tool charges. Choose Working / output folder to browse a collapsible folder tree like the file explorer, including the vault root. Search reaches every existing subfolder; larger search results have an explicit Show more control. This picker uses local folder names only. It cannot choose an external computer/device folder, and cancelling keeps your previous choice. Folder scope includes subfolders while exclusions continue to apply. Selecting an output folder does not expand Current note scope. All actions offers every supported action while retaining the separate data and change scopes you choose. Preview data is inside the data/permissions section and makes no API request. It previews initial input, rather than predicting every later tool read.
Yoofloe has no server or cloud database. Yoofloe does not receive your notes, prompts or answers.
When you choose Send, task data goes directly to OpenAI using your API key; API charges apply.
Conversations are stored on this device by default. In Conversations, open a conversation's menu and choose
Sync with this vault to make its completed messages available on other connected devices. Include the
Yoofloe AI/Shared conversations folder in your Obsidian Sync settings. Anyone with access to the local vault files can read
the shared records. Confirm that the remote vault uses end-to-end encryption. Open the conversation from
From this vault on the other device. If edits diverge, choose which version to continue. Stop syncing saves a
device copy of received versions and removes the shared files. Drafts, attachments and approval state stay on their device.
Choose Delete in a conversation's menu to remove that conversation and its draft from this device. For a shared
conversation, the vault copy stays available on other devices. Saved notes and API keys are kept.
See privacy and local data controls for OpenAI retention, local removal and scope details.
Note titles and vault-relative paths returned by search can also go to OpenAI. Select a passage while the Yoofloe pane is
open to add a reference chip above the composer. Opening Yoofloe from a selected passage works too. Click the chip to preview it or create local image pages. Use its x button to remove
the reference and its selected images from the next message. Use Restore reference to bring them back.
References guide the task. Access continues to control which notes the task can read and edit, including other passages
or notes. Open editor text, including unsaved changes, is used. Changed references require a fresh selection.
Long passages have versioned continuation cursors and reading coverage. Queue stores each message's reference and
attachments. A steer containing new reference material or attachments joins the next safe model request.
The input-size indicator is a local estimate for the next message. After sending, large requests, files and compacted context are counted through the OpenAI input-token endpoint before generation. Known models reserve room for output and reasoning. A failed size check keeps the draft and completed work. The activity details separately report cumulative model usage. Image previews use the selected Markdown only, with embedded files shown as text.
Sources and attachments
Expanded uses permitted notes, supplied attachments, general knowledge and live web research as needed. Current-news/search requests perform a real search, and saved research notes include clickable sources. Provided only omits web search and excludes prior expanded-mode answers from new-task context. It still supports writing, translation, calculation and analysis of supplied facts. It uses OpenAI and is not offline AI. Switching source modes never expands note read/write permissions.
Use + to select up to 10 files, 45 MiB combined. Images can be up to 20 MiB each, and audio recordings can be up to 25 MB each. Files are copied to encrypted device storage;
selection makes no provider request. Send authorizes sharing the selected files with OpenAI.
Supported inputs include PNG/JPEG/WebP, PDF, Office documents/spreadsheets, text/code and recorded audio
(MP3, M4A, MP4, WAV, MPEG/MPGA and WebM). Unsupported or oversized files show an error before upload.
Audio uses gpt-transcribe; each new transcription counts toward the API request limit and has an audio charge.
Completed transcripts are cached and reused on continuation. Removing a chip excludes that file from the next
request; it does not erase the original file. Completed attachments remain visible in the conversation; Attach again explicitly selects them for a follow-up.
The composer clears its attachment selection when that task finishes. A paused task keeps its original attachments.
Office inputs expose extracted text, not embedded images; use PDF to preserve document charts/images. Spreadsheet previews may cover only the first 1,000 rows per sheet. The uploaded file is also available to the analysis container so the model can perform full-file calculations rather than claiming complete coverage from a preview.
Uploaded file objects are requested with a one-hour expiry and deleted after the task finishes or stops when possible. Pausing retains them for continuation within that expiry. This is separate from OpenAI abuse-monitoring retention. Generated images, charts and documents are cached locally with type/size/hash checks. Save attachment or the permitted file tool copies a verified result into the chosen output folder without overwriting existing files. Per-file generated downloads are streamed with a 12 MiB cap, including when OpenAI reports an unknown file size. File transfer and cleanup calls do not consume the model/transcription request count. Recovery keeps newer human edits.
Model response/transcription requests and built-in search/analysis/image calls have separate counters and optional limits, both defaulting to No limit. Hosted tools and transcription can add charges beyond text tokens; a request count is not a price cap. Read OpenAI pricing before choosing a large task.
What it can do
- Ask only: explain, summarize, translate and search permitted notes without modifying files.
- Write and edit: create documents, rewrite or append text, update requested properties, link notes and rename the current document within its folder. Document title changes use the Markdown filename/tab title; body headings are separate. Moving between folders requires an organizing mode.
- Organize notes: also create folders, rename/move notes and propose Trash operations. Moving notes does not silently rewrite backlinks; link updates are separate, version-checked edits within your scope.
- Write ordinary Markdown: headings, lists, tasks, tables, internal links, blockquotes, LaTeX math, Mermaid flowcharts, sequences, mindmaps, timelines, pie charts and numerical charts. Charts must use supplied or verified retrieved data; the model is instructed not to invent measurements.
The model requests typed tools; local code checks permissions, paths, note versions and recovery before performing them. Expanded mode adds OpenAI-hosted web search, Python analysis and image generation when needed. The analysis container has network disabled. No code is executed on the user's computer or phone. Hidden/configuration files are blocked. Calendar proposals go through a separate review in the Android app. Active HTML, remote embeds, executable plugin blocks and unsafe Mermaid features are made inert. Verified generated local image attachments can be embedded in notes. Other installed plugins can still interpret ordinary Markdown; review generated content in the context of your vault.
Scope and cost
Read scope and Write target are independent. Read scope offers Current note, Note folder (including subfolders), or Vault. For writing, Current note permits changes only to the attached note; it cannot create notes, folders or automatically save generated files, even with All actions. A title change stays in that note's folder. Without an attached note, no note is writable. Choose New documents explicitly to create Markdown notes in the output folder without changing existing notes. The same task can read, revise and rename only the notes it created. A later task needs an appropriate write target to edit those now-existing notes. Note folder and Vault allow changes within those selected scopes. New files still use the output folder. In Note folder mode the picker also sets the access boundary for existing notes and subfolders; changing it changes that boundary. Current note never gains creation permission from a folder selection. Broader writes do not bypass a narrower read scope. The manual Save attachment button saves only the selected verified file and does not expand AI permissions. Existing notes, keys and saved scopes are preserved on upgrade; a saved Current note scope now follows this strict behavior. An empty folder means the vault root. Exclude private folders with one vault-relative path per line. Configuration, hidden folders, AI backups/history and detected credential strings are blocked. Credential detection is a precaution, not a complete secret scanner.
Search considers at most 2000 permitted metadata entries and reads bounded pages of up to 32 candidates; the agent can request another page. Note excerpts are at most 32 KiB per read; outlines and line ranges support long notes. Partial coverage is returned explicitly. Input and device-size safeguards still apply.
Model choices include an economical default and a Custom model ID field with examples. Thinking depth offers supported effort values for known models; unknown custom models use the model default. Higher effort may cost more. Effort does not expand file permissions or control response length. No plugin output-token cap is sent. OpenAI's own limits still apply.
Recovery and continued work
Hiding the workspace keeps the task running and retains its answer. Stop prevents future requests and file actions; it cannot recall an in-flight request or its charges. Its returned text is retained. Drafts, the latest result, and bounded previous answers are saved locally in the plugin's configuration folder. A new task keeps up to two bounded prior turns as context. Opening another note does not silently retarget a task.
Before content changes, exact originals are verified in Yoofloe AI/Backups/ and a recovery record is written
in .obsidian/plugins/yoofloe/tasks/ (or the vault's custom configuration directory).
Revert changes from this task only restores files whose current content still matches the recorded version.
Newer user edits, occupied filenames, modified backups and uncertain operations are kept.
Empty folders are retained. Review the changed-file list and use original backups for manual recovery if needed.
Trash always requires a separate user choice after reviewing the concrete notes.
Backups, drafts and results can contain private data and consume local/sync storage. No automatic backup deletion is performed. After checking your work, you can remove unneeded backups and recovery records yourself. They are excluded from AI tools.
Old Writer and Capture panels are consolidated into this one workspace after their saved layout state is backed up locally. Existing Markdown, plugin settings and secret IDs are preserved. No Yoofloe account, hosted database or migration sign-in is required. Historical cloud and MCP-wrapper releases through 0.3.31 remain historical; this release does not reactivate or ship them.
Optional Android app context
Open Workspace settings → App context in Obsidian on the Android phone or tablet that runs the selected app. Use the same Android profile and a vault in shared device storage. The plugin shows the next step as you start a lookup, approve it in the app, and return to review excerpts. Check reply is available while a request is pending. Local lookups make no AI call. Choose the excerpts to include before sending a message to OpenAI. Calendar changes take effect after you review and apply a proposal in the Calendar app.
Yoofloe Calendar
With Yoofloe Calendar 1.8.14 or later, choose Check Calendar connection. If prompted, choose this vault’s Yoofloe Calendar Inbox, then tap Share capabilities. Return to Obsidian, choose workspaces, record types and dates, and tap Find records in Calendar. Review the search in Calendar and return to Obsidian for the excerpts. Quick Calendar lookup supports Calendar 1.8.5 or later.
Archive, Trash, financial records and attachment metadata have separate controls. Draft workspace changes prepares supported Schedule, Study, Project and Notes changes. Review and apply proposals in Calendar. Use Revert in Calendar for a confirmed batch or Check status in Calendar to recover a missed reply. Full-record Markdown snapshot import remains available in Settings.
ChronoHUD
With ChronoHUD 1.3.0 or later, choose date cards, timeline text, Mandalart goals or Eisenhower tasks. Tap Open ChronoHUD to approve and choose this vault’s ChronoHUD Inbox in ChronoHUD. Review the excerpts and tap Approve and return to Obsidian. ChronoHUD is a read-only source. It calculates date metrics locally and keeps each excerpt’s original H reference.
Data, rights and privacy
This is online AI. Permitted note text, prompts, selected app excerpts and relevant tool results go directly to OpenAI, using your key. Yoofloe does not relay them through a server or collect plugin telemetry. API billing is separate from ChatGPT subscriptions. Local key storage does not make the model local.
Requests use store: false; that is not a zero-retention guarantee. Read Privacy and data flow,
OpenAI data controls and
OpenAI pricing before sending sensitive material.
Use only material you may disclose and edit. AI output can be inaccurate; review facts, citations, rights and changes before relying on or publishing it.
This product does not claim that using BYOK or these controls automatically makes a workflow legally compliant.
Build and verify
npm ci, npm run check, npm run lint, npm test, npm run build.
Local lint now checks both manifests and the published package metadata with zero warnings allowed. The build validates CSS and rejects !important. Settings use the searchable 1.13+ definitions and keep the same rows as a 1.11.5–1.12 fallback.
The default root build uses calendar-companion/src/main.ts and publishes only main.js, manifest.json, styles.css.
No additional runtime dependencies, embedding service, planner model or Yoofloe backend is required.
Tests with synthetic providers do not prove live API/device behavior; release notes distinguish those results.
Issues: GitHub issue tracker. Do not post keys, personal note content or private Calendar records in public issues.