Grimoire

Local-first AI agents for your Obsidian vault.

English · 简体中文 · 繁體中文 · 日本語 · Deutsch · Français · Español · Русский

_{Chat with local CLI agents from the same Obsidian workspace where your notes live.}

Grimoire brings agentic CLI assistants into Obsidian. Claude Code, Codex, Antigravity CLI, Gemini CLI (Legacy), and OpenCode all live in one side panel, where they read your notes, edit files, run commands, call tools, and keep session history against your real vault. Nothing routes through a Grimoire server. There's no telemetry, no hosted backend, and no proxy sitting in the middle.

It's built for people who already work in Obsidian and want AI help that behaves like part of the vault: local context, local files, a provider you pick on purpose, and usage you can actually see.

Why Grimoire

• Use the CLI agents you already trust, right inside your notes.
• Switch providers from the composer. Claude Code, Codex, Antigravity CLI, legacy Gemini CLI, and OpenCode share one model picker.
• Ground every turn in your vault. Mention notes, folders, and MCP tools instead of pasting paths by hand.
• See cost and limits next to the model selector, where you're making the decision anyway.
• Stay local-first. Grimoire doesn't collect telemetry, proxy prompts, or run a backend.

What each provider can do

Installation

Grimoire is a desktop plugin. It drives your provider CLIs locally, so there's no mobile build.

From Community plugins (recommended)

Install Grimoire from the Obsidian community plugin directory:

1. Open Settings, go to Community plugins, and turn off Restricted mode if it's on.
2. Click Browse, search for Grimoire, and install it.
3. Enable Grimoire, then open its panel from the ribbon or the command palette.

From GitHub Releases

Install the current release manually if you can't use Community plugins:

1. Download main.js, manifest.json, and styles.css from the latest Grimoire release.
2. Create /path/to/your/vault/.obsidian/plugins/grimoire.
3. Put all three files in that folder.
4. Enable Grimoire from Settings, Community plugins.

With BRAT

BRAT can install Grimoire from GitHub Releases if you want to track tagged builds outside the community directory:

1. Install the "Obsidian42 - BRAT" plugin.
2. In BRAT, add a beta plugin from sandsaber/Grimoire.
3. Enable Grimoire.

From source (developers)

Build the release bundle and drop it into your vault:

npm install
npm run build:release

mkdir -p /path/to/your/vault/.obsidian/plugins/grimoire
cp dist/grimoire/main.js dist/grimoire/manifest.json dist/grimoire/styles.css \
  /path/to/your/vault/.obsidian/plugins/grimoire/

Then enable Grimoire from Settings, Community plugins.

Whichever path you pick, install at least one CLI provider before you start. Grimoire wraps the provider CLIs. It doesn't replace their account setup, model access, quotas, or terms.

Set up a provider

Enable the providers you want under Settings, Grimoire, Providers, and they'll appear in the model selector. Codex is enabled on first launch; the rest are opt-in.

Claude Code

Pick Claude Code when you want its native project memory, slash commands, MCP configuration, plans, and rewind/fork, backed by your Claude subscription or API key.

npm install -g @anthropic-ai/claude-code
claude

Authenticate through Claude Code, then enable it in Grimoire.

• Claude Code getting started
• Claude Code CLI reference

Inside Grimoire, Claude Code reads and preserves your .claude/ files, runs on the Claude Code SDK, and supports slash commands, MCP settings, agents, skills, plans, rewind, and fork. When Claude reports both, you'll see quota windows and API spend side by side.

Respect Claude Code settings is enabled by default. Grimoire reads Claude Code user settings (~/.claude/settings.json) and vault settings (.claude/settings.json) for model and env, then uses those values in the Claude model selector and runtime environment. This lets Claude Code custom models work in Grimoire too, including Anthropic-compatible gateways such as MiniMax, Z.ai, and others. Project settings override user settings, and explicit Grimoire environment settings override both.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash"
  }
}

Codex

Codex is the default provider on first launch. Pick it for OpenAI Codex in a local CLI, signed in with your ChatGPT plan or an API key.

npm install -g @openai/codex
codex

You can also install it through the official Codex installer or Homebrew. Run it once, sign in, then enable it in Grimoire.

• Codex CLI README
• Codex getting started
• OpenAI code generation guide

Inside Grimoire, Codex runs on its app-server protocol with native history, fork, plan mode, image input, and reasoning effort controls. Plan usage shows up when Codex reports rate-limit metadata.

Antigravity CLI

Antigravity CLI is Google's recommended replacement for consumer Gemini CLI use. Pick it for Google's multi-model agent CLI, including Gemini, Claude, GPT-OSS, and other model families that your Antigravity account can access.

agy

Install the official Antigravity CLI from Google, authenticate it locally, then enable Antigravity in Grimoire. Grimoire auto-detects agy from PATH, or you can set a custom CLI path in provider settings.

• Antigravity CLI
• Gemini CLI migration guide

Inside Grimoire, Antigravity is the recommended Google provider. It runs through agy --print with optional model selection from agy models, and Grimoire folds the active note plus editor, browser, canvas, vault-search, and project-workspace context into that print prompt. Persistent sessions, native history, images, plan mode, streaming, and auxiliary workflows stay disabled until Antigravity exposes a compatible runtime surface for them.

agy --print does not expose Grimoire file-edit approval hooks. For safety, Antigravity's shared Safe/normal mode is blocked in Grimoire; switch the Antigravity toolbar toggle to Auto-approve only when you are comfortable with AGY editing files without Grimoire prompts.

Gemini CLI (Legacy)

Gemini CLI remains available as a legacy compatibility provider for Gemini Code Assist Standard, Enterprise, Google Cloud, and paid API-key users where Google continues serving Gemini CLI requests. Consumer Google AI Pro, Ultra, and free-tier accounts should use Antigravity instead after Google's June 18, 2026 transition.

gemini

Enable Gemini CLI only if your account tier is still supported. Grimoire runs it through gemini --acp, folds the active note plus editor, browser, canvas, vault-search, and project-workspace context into the ACP prompt, keeps its model and mode discovery provider-owned, and labels it as legacy so it does not look like the recommended Google path.

OpenCode

Pick OpenCode for a model-agnostic agent that brings its own provider configuration.

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash
opencode

Homebrew and Go installs work too. Configure your provider credentials in OpenCode, then enable it in Grimoire.

• OpenCode GitHub repository
• OpenCode provider docs
• OpenCode config docs

Inside Grimoire, OpenCode runs over ACP with Grimoire-managed launch artifacts, plus persistent runtime, native history, plan mode, image input, provider commands, and reasoning effort. It reports monthly spend when cost metadata is available.

Your first chat

1. Pick a provider and model in the composer.
2. Set reasoning effort and a permission mode.
3. Mention any notes, folders, or context you want in scope.
4. Send the turn.
5. Watch tool calls, usage, and output land in the panel.

Features

Chat workspace

A focused side panel with multiple tabs. Each tab keeps its own draft, provider, model, context, and runtime. Close and reopen Obsidian and your sessions come back, with the provider, model, and reasoning effort preserved on every response. Rewind and fork appear when the active provider supports them. Auto-scroll backs off the moment you scroll away to read something.

Model selector

One picker, grouped by provider and sorted by label: Antigravity, Claude Code, Codex, Gemini CLI (Legacy), OpenCode. Search runs across labels, descriptions, groups, and model IDs without resizing the menu while you filter. Catalogs load lazily and remember which groups you collapsed. Add custom aliases and context-window overrides in settings. Claude's 1M variants are extra options, not replacements for the base models.

Usage and cost

A badge next to the model selector keeps the active provider's usage in view, with fuller readouts inside the model menu: quota windows where a provider exposes them, spend where only cost is available. Stale numbers stay put while a refresh is in flight or fails, so the meter never blanks out. Turn the whole thing off in settings if you want a quieter UI.

Context and mentions

Mention vault notes and folders straight from the composer, pull in the current or linked note, and add persistent external context paths in settings. Paste or drop images when the provider takes image input. Mention MCP servers where the provider integration supports it.

Inline editing

Run "Grimoire: Inline edit" on a selection. A prompt opens next to the text, the edit comes back as a diff you accept or reject, and it routes through the provider-backed inline edit service. It handles both replacing a selection and inserting new text.

Clarifying questions

When a provider asks for structured user input, Grimoire pauses the turn and renders the question over the composer. Single-select, multi-select, and freeform answers resolve back into the provider run, so the agent can continue without a separate chat message.

Commands

Built-in commands cover Grimoire workflows like image generation and resume. Providers that expose their own commands, such as Claude Code slash commands and OpenCode runtime commands, surface them through provider-owned catalogs. Hide the ones you don't use from the dropdown in settings.

Image generation

Paste or drop images to attach them. The built-in /image [prompt] command doesn't call any image API itself. It hands a normal turn to the active provider with instructions to use whatever image generation you've configured: provider-native tooling, MCP tools, or a local command. The agent saves the result in your vault and returns an embed like ![[path/to/image.png]]. If nothing is set up for image generation, you get a plain answer explaining what's missing.

Safety and permissions

Permission modes belong to the provider, so Grimoire surfaces them through shared composer controls instead of reinventing them. Safe mode and permission prompts stay visible while you work. Bang-bash mode only shows up when an enabled provider offers it. Treat configured MCP servers, shell access, and API keys as sensitive, because they are.

Debug logging

Off by default. Turn it on and Grimoire writes sanitized JSONL to .grimoire/logs/YYYY-MM-DD.jsonl, with prompts, answers, note contents, paths, environment values, and secrets redacted. It's for diagnosing provider and runtime issues, not for keeping a transcript.

Settings

General settings cover Obsidian-following theme behavior, auto-scroll, title generation, usage indicators, debug logging, locale, tabs, and which provider owns the settings view. Per-provider tabs handle CLI paths, model behavior, commands, agents, skills, and provider-owned config where it exists. You can also set project workspace environment variables, scoped per provider when needed.

Where Grimoire keeps your data

Provider-native files under .claude/, .codex/, and .opencode/ are read and written in place, so your provider setup stays portable outside Grimoire.

Privacy

Grimoire runs inside Obsidian, on your machine. It has no backend, adds no telemetry, and never uploads your prompts, answers, notes, files, tool output, API keys, or usage logs to any Grimoire service. The only logs it writes are the optional, sanitized debug logs above, and those stay in your vault.

What it can't hide is the provider itself. Whichever CLI you enable receives the prompt, the context you selected, and the files, images, tool output, and commands a request needs. That CLI may then talk to Anthropic, OpenAI, Google, your configured OpenCode vendors, MCP servers, or anything else it's set up to reach. Terms, retention, billing, rate limits, and privacy policies are the provider's, not Grimoire's. Grimoire's job is to make that boundary visible and keep it under your control inside Obsidian.

For an Obsidian policy-oriented summary of network use, account requirements, external file access, logging, and telemetry, see DISCLOSURES.md.

Development

npm install
npm run dev
npm run typecheck
npm run lint
npm run test
npm run build
npm run build:release

Before publishing or pushing meaningful UI or provider changes, run the full local gate:

npm run test -- --selectProjects unit
npm run typecheck
npm run lint
npm run build:release

npm run build:release refreshes the generated main.js, the root styles.css, and dist/grimoire.

npm is the canonical package manager for development, CI, and releases. Keep package-lock.json current when dependencies change; secondary package-manager lockfiles are intentionally not committed.

Releases

Grimoire releases are published from semver tags such as 1.0.0. The release workflow runs the local gate, builds the Obsidian bundle, verifies that the tag matches package.json and manifest.json, then attaches main.js, manifest.json, and styles.css to the GitHub Release.

Obsidian Community plugins are the recommended user install path. GitHub Releases still carry the bundle assets for manual installs and BRAT. Use main for releasable development, then publish by tagging the version that matches the manifest.

Roadmap

Today Grimoire ships with Claude Code, Codex, Antigravity CLI, Gemini CLI (Legacy), and OpenCode.

Next on the list: Qwen Code, GitHub Copilot CLI, other ACP-compatible providers, and local model CLIs once their runtime is stable enough to embed in Obsidian. Implementation notes live in docs/provider-roadmap.md.

License

MIT. See LICENSE.