Obsidian Plugin Setup & Configuration

The NutEgg Obsidian plugin hosts the local sync server, manages AI communication, matches incoming content to your knowledge trees, and maintains your vault files.

Installation

Option 1: Obsidian Community Plugins (Recommended)

NutEgg is officially listed in the Obsidian Community Plugins directory:

In Obsidian, open Settings → Community plugins.
Ensure Restricted mode is turned off, then click Browse.
Search for NutEgg (or visit NutEgg on Obsidian Community Plugins).
Click Install, then click Enable.

Option 2: Manual Installation

Download main.js, manifest.json, and styles.css from the NutEgg Obsidian Plugin Releases.
In your Obsidian vault, open .obsidian/plugins/ (show hidden folders in your OS if needed).

Create a new directory named nutegg and place the three files inside:

your-vault/.obsidian/plugins/nutegg/
├── main.js
├── manifest.json
└── styles.css

In Obsidian, open Settings → Community plugins, click Reload, and toggle NutEgg on.

Option 3: Using BRAT

Install the BRAT community plugin in Obsidian.
Go to Settings → BRAT → Add Beta plugin.
Enter staff-000/nutegg-obsidian-release and click Add Plugin.
Enable NutEgg once installed.

AI Execution Architecture

NutEgg uses an intelligent dual execution architecture (Protocol 3) that gives you full flexibility between bring-your-own-API-key privacy and zero-key subscription convenience:

🔒 Core Privacy Invariant: API Keys Never Leave Chrome

In Connected API Mode, Obsidian orchestrates vault operations, prompt assembly, and egg indexing, but delegates all AI calls back to Chrome via an authenticated local WebSocket. Chrome executes the call using its locally stored API key. Your API keys are never transmitted to Obsidian, never written to vault notes, and never leave the browser.

┌─────────────────────────────────────────────────────────────────────────────┐
│                           CONNECTED API MODE (Default)                      │
│                                                                             │
│  Chrome Profile A ──(1) HTTP /analyze /confirm──►  Obsidian Plugin          │
│  (Holds API Key A)                                 (127.0.0.1:27123)        │
│                                                            │                │
│                   ◄─(2) WebSocket AI Call /socket──────────┤ Reads _index.md│
│  Calls Provider A                                          │ Assembles prompt│
│  (OpenAI / Claude / Gemini / DeepSeek)                     │                │
│                   ──(3) Authenticated Result─────────────► │                │
│                                                            ▼                │
│  Receives Final Result ◄──────(4) HTTP Result────── Saves to Vault          │
│                                                     (_raw/ & <egg>.md)      │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                       SHARED SUBSCRIPTION MODE (Zero API Keys)              │
│                                                                             │
│  Chrome Profile A ────┐                                                     │
│                       ├──► Obsidian Plugin (127.0.0.1:27123)                │
│  Chrome Profile B ────┘        │                                            │
│                                ▼                                            │
│                       SubscriptionService (Local CLI or OAuth)              │
│                       ├── ChatGPT Sign-In (OpenAI Responses API)            │
│                       ├── Codex CLI (@openai/codex)                         │
│                       ├── Claude Code CLI (claude auth login)               │
│                       └── Google Gemini (Antigravity CLI: agy)              │
└─────────────────────────────────────────────────────────────────────────────┘

Mode 1: Connected API Mode (Default)

In this mode, you configure your AI provider and API key directly in Chrome Extension Options. Obsidian coordinates the knowledge workflow while Chrome acts as the secure local AI runner.

Supported Cloud Providers: Anthropic (Claude 3.5 Sonnet, Claude 3.7 Sonnet), OpenAI (GPT-4o, o-series), Google Gemini (2.0 Flash, 2.5 Pro), DeepSeek (V3, R1), Kimi, Qwen, Zhipu, and OpenRouter.
Local LLMs (Ollama, LM Studio, llama.cpp, vLLM): Configure local endpoints directly in Chrome. NutEgg connects to your local model without sending data outside your machine.
Independent Chrome Profiles: If you use multiple Chrome profiles (e.g. Work and Personal), each profile can use its own provider, model, and API key. They connect to the same Obsidian vault without key collisions.
Obsidian-Native Actions: Vault-only maintenance tasks (such as manual egg merging in Obsidian) use native settings safely stored in Obsidian's SecretStorage. Clicking Save & continue in a connected Chrome profile securely updates the native account in SecretStorage.

Mode 2: Shared Subscription Mode & ChatGPT Sign-In

Don't want to manage API keys or pay-per-token credits? NutEgg supports direct sign-in and local developer CLI subscriptions managed inside Obsidian:

Option A: Direct ChatGPT Sign-In (No CLI needed)

In Obsidian, open Settings → NutEgg.
Under AI connection, select ChatGPT sign-in.
Click Continue with ChatGPT, complete the browser authorization flow, and allow plan usage.
Choose your account model (e.g. gpt-4o).
All connected Chrome profiles immediately follow this connection with zero API key setup. Credentials live securely in per-installation OS keychain storage and are never sent to Chrome or stored in vault files.

Option B: Local CLI Subscriptions (Codex, Claude, Gemini)

NutEgg can run official developer CLI tools already installed and logged in on your machine:

Provider	CLI Installation	Authentication	Model Discovery
Codex CLI	`npm install -g @openai/codex`	`codex login`	Automatic via app-server
Anthropic Claude	Claude Code	`claude auth login --claudeai`	Sonnet, Opus, Haiku, or custom ID
Google Gemini	Antigravity CLI	`agy` browser flow	Automatic via `agy models`

In Obsidian Settings → NutEgg, simply select your CLI under AI connection. NutEgg's internal SubscriptionService runs inference in a bounded serial queue locally. No separate bridge server or port 27124 is needed.

Local Sync Server & Security

When the plugin is enabled, it automatically boots a background HTTP and WebSocket listener on 127.0.0.1:27123.

🔒 Privacy & Origin Security

The local server binds strictly to the localhost loopback address (127.0.0.1). It enforces strict X-NutEgg-Extension-Origin and token validation, preventing ordinary web pages from accessing your vault. WebSocket connections authenticate on their very first frame.

Workflow & Prompt Customization

NutEgg powers its AI analysis through modular, editable Markdown prompts stored directly in your vault under nutegg/_workflow/:

Editable Templates: Customize prompts for content analysis, egg comparison, routing, and follow-ups.
Non-Destructive Updates: When NutEgg releases updated prompt templates, your customized workflows are automatically preserved without being overwritten.