Yoofloe

Yoofloe turns your Yoofloe data into grounded AI documents inside Obsidian.

Public install guides, release links, and cross-product setup notes also live in the Yoofloe docs hub:

• https://www.yoofloe.com/docs/external-tools

Beta install

Before Community Plugin submission, install the beta from this public repository instead of the Community Plugin store.

BRAT path:

1. Install the BRAT plugin in Obsidian.
2. Open BRAT -> Add a beta plugin.
3. Paste https://github.com/yoofloe/yoofloe-obsidian.
4. Install the latest beta release from that repository.

Manual path:

1. Download the latest release assets from https://github.com/yoofloe/yoofloe-obsidian/releases.
2. Copy main.js, manifest.json, and styles.css into .obsidian/plugins/yoofloe/.
3. Enable Yoofloe in Obsidian Community Plugins.

Community Plugin submission notes

For Obsidian Community Plugin review, the submission target is the yoofloe plugin itself:

• main.js
• manifest.json
• styles.css

The packaged yoofloe-obsidian-mcp-wrapper.zip release asset is a companion download for external MCP clients. It is not the Community Plugin payload.

Reviewer-facing disclosures:

• desktop-only plugin
• requires a Yoofloe pat_yfl_... token
• requires Yoofloe Pro / External AI Access
• calls Yoofloe API and Google Gemini endpoints
• writes Markdown files locally into the vault
• uses direct-provider Gemini calls with the user's own Google credentials

Quick start

1. Install the plugin from BRAT or copy the latest release files into .obsidian/plugins/yoofloe/.
2. Open Settings -> Yoofloe.
3. Save your pat_yfl_... token and click Verify token.
4. Choose a Gemini setup and save each required field in Settings -> Yoofloe.
5. Run AI Insight Brief.

Recommended first AI choice:

• Gemini (Google AI) for most users
• Gemini (Vertex AI) only if you specifically want your own Vertex setup

Choose your AI setup

Gemini (Google AI)

• Best default for most users
• Uses Google OAuth in your browser
• Requires:
  • a Desktop App OAuth client ID from your own Google Cloud project
  • a Google Cloud Project ID
  • a Gemini model such as gemini-2.5-flash-lite

Gemini (Vertex AI)

• Advanced Google Cloud option
• Uses Google OAuth in your browser
• Requires:
  • a Desktop App OAuth client ID from your own Google Cloud project
  • a Google Cloud Project ID
  • a Vertex model such as gemini-2.5-flash-lite
• Optional:
  • Vertex location, default us-central1

Common errors

• Yoofloe API token is missing
  • Save your pat_yfl_... token in Settings -> Yoofloe
• Connect your Google account
  • Click Connect Google in Settings -> Yoofloe
• Add your Google Cloud Project ID
  • Use your Project ID, not the numeric project number
• Reconnect Google
  • Your Google session expired or was revoked; connect again from Settings

Modes

• Plugin Mode: generate grounded AI documents inside Obsidian with Gemini.
• Agent Direct Mode: let Codex, Claude Code, Antigravity, or another filesystem-capable agent fetch Yoofloe context and write AI documents directly into your vault.
• MCP Wrapper Mode: run the standalone stdio MCP server from this repo so external coding agents can fetch Yoofloe AI context and write notes only into your configured vault folder.

Agent Direct Mode does not call the plugin runtime directly. It uses the same Yoofloe PAT and API contract, then writes files into your vault so Obsidian picks them up automatically.

External AI Access

Yoofloe treats external AI surfaces as one Pro feature:

• Yoofloe Obsidian Plugin
• Yoofloe Obsidian MCP wrapper
• Yoofloe CLI
• Yoofloe CLI MCP

Auth stays product-specific:

• Obsidian Plugin and Obsidian MCP wrapper use a pat_yfl_... token
• Yoofloe CLI and Yoofloe CLI MCP use Yoofloe app login

Role split:

• Plugin Gemini mode is user-direct. Obsidian calls Google Gemini or Vertex with your own Google credentials and project.
• MCP Wrapper and Agent Direct are agent-direct. Your connected external agent brings its own model/provider path.
• Yoofloe provides auth, entitlement, grounded context, and bounded local writes. Yoofloe does not provide the model on these external surfaces.
• Business playbook context may include planning, success, setback, and learning categories. Treat planning as an idea/plan lane with a hypothesis, success signals, first steps, and risks, rather than a completed outcome.

Read the public notice:

• https://www.yoofloe.com/external-ai-access

Operator validation for cross-product entitlement changes should follow the shared runbook in the Yoofloe app repo:

• docs/ai/external-access-smoke-test.md

See docs/agent-direct.md for the direct agent workflow, curl examples, and recommended file conventions. See docs/mcp-wrapper.md for the MCP wrapper setup, supported tools, packaged zip install path, and Windows/PowerShell examples.

Security & Privacy

• Vault content is not uploaded to Yoofloe.
• All network traffic uses Obsidian requestUrl.
• The plugin pulls read-only Yoofloe data and writes Markdown files locally in your vault.
• A Yoofloe Personal Access Token is required.
• The plugin is desktop-only.
• Yoofloe requires Obsidian 1.11.5+ and stores your PAT, Google OAuth client secret, and Google OAuth refresh token in Obsidian secure storage instead of data.json.
• Google access tokens are kept in memory only and refreshed from secure storage when needed.
• Google OAuth credentials are used only for Gemini requests. They are not sent to Yoofloe backend.
• External providers may process content under their own terms and privacy practices when you choose to use them.
• PATs and .mcp.json entries do not contain Yoofloe raw encryption keys and cannot decrypt v2 zero-knowledge content by themselves.
• External MCP users can call yoofloe_mcp_session_status before fetching data to inspect the personal-only scope and local-key readiness contract.

Data Flow

1. Obsidian sends a read-only request to Yoofloe Edge Functions.
2. Yoofloe returns a deterministic bundle for the selected domains and range.
3. The plugin optionally fetches a deterministic gardener brief to compress signals.
4. AI document commands build prompts locally from the bundle and gardener brief, call your selected Gemini setup with requestUrl, then save the result into your vault.

Domains Contacted

• https://hhiyerojemcujzcmlzao.supabase.co/functions/v1/obsidian-data-api
• https://hhiyerojemcujzcmlzao.supabase.co/functions/v1/obsidian-gardener-api
• https://accounts.google.com during Google OAuth connection
• https://oauth2.googleapis.com for Google OAuth token exchange and refresh
• https://generativelanguage.googleapis.com when you use Gemini (Google AI)
• https://*.aiplatform.googleapis.com when you use Gemini (Vertex AI)

Token Storage

• Tokens are generated in Yoofloe web app Settings.
• Tokens use the pat_yfl_ prefix.
• Tokens expire after 90 days unless regenerated sooner.

Pro Requirement

Yoofloe External AI Access requires an active Pro-eligible Yoofloe account.

Wrapper download

The standalone Yoofloe Obsidian MCP Wrapper is published as a packaged release asset:

• https://github.com/yoofloe/yoofloe-obsidian/releases/latest/download/yoofloe-obsidian-mcp-wrapper.zip

That zip contains:

• mcp-server.js
• README-mcp-wrapper.txt

AI Providers

Plugin AI providers currently support:

• Gemini (Google AI)
• Gemini (Vertex AI)

Google providers share one Google OAuth desktop connection and your own Google Cloud project:

• Gemini (Google AI) calls Gemini Developer API with OAuth
• Gemini (Vertex AI) calls Vertex AI Standard with OAuth
• Both require:
  • a Desktop App OAuth client ID from your own Google Cloud project
  • a Google Cloud Project ID
• Gemini (Vertex AI) also supports a custom location, default us-central1

Google OAuth scopes:

• https://www.googleapis.com/auth/cloud-platform
• https://www.googleapis.com/auth/generative-language.retriever

Yoofloe uses these scopes only for Gemini and Vertex generation requests. The plugin does not use them for unrelated Google Cloud APIs.

These providers are used only by the plugin AI commands:

• AI Insight Brief
• AI Decision Memo
• AI Action Plan
• AI Deep Dive

The MCP wrapper does not call AI providers. Agent Direct Mode also does not reuse plugin secrets.

AI Document Commands

• AI Insight Brief
• AI Decision Memo
• AI Action Plan
• AI Deep Dive

All four commands pull the full Yoofloe domain bundle by default. AI Deep Dive additionally asks for a focus instruction before generation.

Agent Direct In The Plugin

Settings now includes a Use With AI Agents section with:

• Copy Codex Prompt
• Copy Claude Code Prompt
• Copy MCP Config
• Open Agent Direct Guide
• Write Agent Setup Note

The command palette also includes Write Agent Setup Note for generating a shareable setup note inside your configured Yoofloe folder.

Agent MCP Workflow

If you want Codex or another coding agent to create a grounded Yoofloe AI document without using plugin Gemini setup:

1. Run the MCP wrapper from this repo.
2. Optionally call yoofloe_agent_direct_guide to fetch the current workflow contract and examples.
3. Call yoofloe_ai_document_context to fetch the canonical bundle, optional gardener brief, and the document-specific prompt scaffold.
4. Let the agent use its own model path to draft the final Markdown.
5. Call yoofloe_write_ai_document to save the final Markdown into your vault under Yoofloe/.

Low-level tools such as yoofloe_data_bundle and yoofloe_write_note remain available for advanced flows, but the AI-document workflow above is the recommended path.