› cavi-ai/
GitHub ↗

Getting started

Install Companion for Claude, connect Claude, and get to a useful first answer. The API-key path takes no terminal; desktop subscribers can instead use an already installed and signed-in Claude Code CLI.

1. Install

From the community store — *Settings → Community plugins → Browse* → search "Companion for Claude" → *Install* → *Enable*. Or open it directly in Obsidian.

Pre-release builds (BRAT) — install the BRAT plugin, then *Add beta plugin* and enter cavi-ai/companion-for-claude. Releases are published from that mirror repo; the store listing tracks it.

2. Connect Claude

On desktop, the first-run card offers Use Claude Code sign-in when the installed claude command is signed in. That runs chat on your Claude subscription without saving an API credential. Each saved Companion conversation resumes its own Claude Code session. The CLI backend is desktop only and covers chat; utility work such as source enrichment still needs a direct API credential or a local model.

The simple path on every device is an Anthropic API key:

  1. Open the Anthropic Console → API keys and create a key.
  2. In Obsidian, go to *Settings → Companion for Claude → Connection*.
  3. Leave Authentication on API key and paste the key into Anthropic API key.
  4. Click Save & test connection. A green result means you're done.

You pay Anthropic for usage; nothing is billed by this plugin, and there is no account to create with us.

Already have a Claude subscription, a long-term OAuth token, or an ANTHROPIC_API_KEY in your shell? See auth.md for the differences and for pointing direct API traffic at a gateway.

3. Your first chat

Open the panel from the sparkles ribbon icon (*Open Companion for Claude*) or the command palette (*Open chat panel*).

!The Companion chat panel with vault context attached

Above the composer is a row of Context chips. Toggle one on and its content rides along with your next message:

  • Active note — the note you're looking at.
  • Selection — just the text you highlighted.
  • Linked / Backlinks — notes the active note points at, and notes pointing back.
  • Search — a keyword (or semantic, if enabled) sweep of the whole vault.

You can also @-mention a specific note, folder, PDF, or image in the composer, or paste a screenshot straight into it.

Paste a URL and you'll get a pill offering to attach the page — Companion fetches it and reduces it to clean readable markdown (the same Defuddle engine behind Obsidian's Web Clipper). The fetch only happens when you ask for it, and a failure shows on the pill instead of derailing the chat.

Try: open a note with some substance, toggle Active note, and ask *"What am I actually claiming here, and what's unsupported?"*

Companion trims attached context to a character budget (default 24,000 characters, 6 notes) so a big vault can't blow up a request. Both are adjustable under *Settings → Companion for Claude → Behavior*.

4. Your first artifact

Type / in the composer to open the slash palette — 24 built-in commands plus your workflows, fuzzy-searchable.

<!-- screenshot: ../assets/slash-palette.png — pending capture -->

Pick `/artifact` with a note open. Claude replies with a fenced claude-html block, and Companion renders it inline in the chat, inside a sandboxed iframe — a real interactive page, not a picture of one.

!A claude-html artifact rendered inline

From there you can open it in your real browser or save it as a portable note. See artifacts.md for the sandbox rules and the design system.

Other good first commands: /summarize, /ask (answers across the whole vault), /diagram, /canvas, /research.

Your own slash commands

Any Markdown note in your templates folder (*Settings → Companion for Claude → Storage → Templates folder*, default Claude/Templates) becomes a slash command. Frontmatter carries name and description, plus optional model and context-toggle defaults; the body is the prompt.

{selection} and {active_note} are substituted at run time — unknown placeholders are left alone rather than mangled. A note named Standup Summary becomes /standup-summary.

5. Agent mode

Agent mode is on by default. It's what lets Claude search and read your vault on its own mid-answer instead of relying only on the chips you pre-attached. Each step it takes shows up as a tool chip you can expand.

<!-- screenshot: ../assets/agent-tool-chips.png — pending capture -->

Under *Settings → Companion for Claude → Agent (act on your vault)*:

  • Let Claude use vault tools — the read-only loop (search, read, follow links). On by default. Turn it off for plain chat with only pre-attached context.
  • Allow write tools — also lets Claude create, edit, and move notes. On by default, and every single write asks you first.
  • Max tool iterations per turn — how many search/read/write rounds Claude may take before it has to answer. Default 10.

Note edits are a separate, safer path: Claude proposes exact replacements. If the target note is open, you review word-level changes directly in the editor; otherwise Companion opens the red/green modal. Only accepted hunks are written, even with write tools off.

The agent isn't Claude-only: on the Local only backend it runs against your Ollama server too, as long as the selected model supports tools (settings badge each detected model's tools/thinking capabilities). The composer's reasoning indicator lights up whenever the active backend thinks before answering.

Full detail in agent-mode.md.

6. Desktop integrations

The in-chat Claude Code backend does not require the background MCP bridge. On desktop, open Options → Desktop integrations from any Companion page (or use the button at the top of Companion settings) for two optional connections:

  • Claude Code — Companion checks for the claude and official obsidian

CLIs, then can add cavi-ai/plugins and install obsidian-agent@cavi-ai at user scope with one confirmed action. Claude Code uses the official Obsidian CLI by default; no background MCP server is needed. The Obsidian CLI has to be on first — Open Obsidian CLI settings in that panel takes you straight to the switch and the Register step (Obsidian 1.12.7+). See claude-code-bridge.md for both steps and for what *installed, not responding* means.

  • Claude Desktop — the confirmed setup enables Companion's read-only

loopback MCP bridge and merges an obsidian-vault entry into Claude Desktop's local configuration. Restart Claude Desktop after setup and keep Obsidian open while using it.

Companion never installs Claude Code or Obsidian itself, silently edits external configuration, or enables MCP writes. See claude-code-bridge.md for manual recovery and the advanced live-vault API.

Next steps