Skip to content
Back to search

plug-n-rag

MarketplaceWorks with Claude CodeGitHub

Extensions for Claude Code by sign-u-p around plug-n-rag: Claude finds what fits your question in your notes and documents. English and German. Deutsch: Erweiterungen rund um plug-n-rag, auf Englisch und Deutsch.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sign-u-p/plug-n-rag with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sign-u-p/plug-n-rag'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sign-u-p--plug-n-rag/badge.svg)](/listings/sign-u-p--plug-n-rag)

HTML

<a href="/listings/sign-u-p--plug-n-rag"><img src="/api/listings/sign-u-p--plug-n-rag/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pick one way. A is the easiest.

**A: Through the plugin page** (desktop app or claude.ai)

1. Open **Settings → Plugins** (on claude.ai: "Customize" → "Plugins"). In the desktop app this page also opens when you type `/plugin`. 2. Top right, choose **Add → Add marketplace**, enter `sign-u-p/plug-n-rag` and confirm. 3. Click **Add** next to **plug-n-rag**. 4. Done. The plugin now belongs to your Claude account and is there from the next session (in an open session: type `/reload-plugins`).

**B: In the terminal**

claude plugin marketplace add sign-u-p/plug-n-rag
claude plugin install plug-n-rag@plug-n-rag

**C: Let Claude do it.** Write in a session: "Please run `claude plugin marketplace add sign-u-p/plug-n-rag` and `claude plugin install plug-n-rag@plug-n-rag`." Then type `/reload-plugins`.

For the browser (claude.ai/code) there is a way of its own, see [Use it in the cloud](#use-it-in-the-cloud).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "plug-n-rag",
  3. "description": "Extensions for Claude Code by sign-u-p around plug-n-rag: Claude finds what fits your question in your notes and documents. English and German. Deutsch: Erweiterungen rund um plug-n-rag, auf Englisch und Deutsch.",
  4. "owner": {
  5. "name": "sign-u-p"
  6. },
  7. "plugins": [
  8. {
  9. "name": "plug-n-rag",
  10. "source": "./plugins/plug-n-rag",
  11. "description": "Claude finds what fits your question in your Obsidian notes and documents, even in other words, and reads only the matching sections: answers with sources, fewer tokens, your notes stay unchanged and private. English and German (search model chosen for its especially good German). Deutsch: Claude findet in deinen Obsidian-Notizen und Dokumenten, was zu deiner Frage passt, auch bei anderen Worten, und liest nur die passenden Abschnitte."
  12. },
  13. {
  14. "name": "plug-n-rag-anzeige",
  15. "source": "./plugins/plug-n-rag-anzeige",
  16. "description": "Shows calmly in the chat, and in detail on click, what plug-n-rag does: notes found, sections read, whether everything is up to date and how much was saved. Optional add-on to plug-n-rag. Deutsch: Zeigt im Chat ruhig, was plug-n-rag tut."
  17. }
  18. ]
  19. }
README.md · README · 615 lines
  1. # plug-n-rag
  2. **English** · [Deutsch](README.de.md)
  3. **Claude knows your notes and reads only what it really needs for your question.**
  4. plug-n-rag is an extension for [Claude Code](https://code.claude.com). It makes your Obsidian
  5. notes (and, if you like, other folders full of documents) searchable for Claude. When you ask
  6. Claude something, it first looks in your own notes, reads only the matching passages and tells you
  7. where each statement comes from.
  8. plug-n-rag is meant for anyone who works with a collection that has grown over time: project and
  9. meeting notes, reading notes, a Zettelkasten, material from studies and training, or a folder of
  10. reference books as PDFs. You don't need to know how to program. plug-n-rag speaks English and
  11. German.
  12. ## What's in it for you?
  13. - **Answers from your own knowledge, with sources.** For every statement Claude names the note and
  14. the lines it comes from. You can check everything.
  15. - **Hits even when the words differ.** You ask about the "cost" of a project and also get the note
  16. that talks about the "budget".
  17. - **Fewer tokens.** Claude no longer reads whole notes, just the two or three matching sections.
  18. That spares your usage limits (or costs) and leaves more room for the actual task. Fewer tokens
  19. also means less computing power and energy.
  20. - **Honest answers.** If something isn't in your notes, Claude says so instead of making it up.
  21. - **Your notes stay as they are.** plug-n-rag never changes a note and sends nothing to additional
  22. services without your consent.
  23. ### What it looks like
  24. **In your vault**, for example with project and meeting notes:
  25. > **You:** What did we decide about the budget for the website relaunch?
  26. >
  27. > **Claude:** According to your notes:
  28. > – At the kick-off a frame of €12,000 was set, €2,000 of it as a reserve
  29. > (meetings/2026-09-03 Kick-off relaunch.md, l. 14–22).
  30. > – In October the reserve was released for the accessible implementation
  31. > (projects/Website relaunch.md › Decisions, l. 40–47).
  32. > Who gave the approval is not in your notes.
  33. Claude read two short sections for this instead of every note about the project.
  34. **In a library**, for example a folder of reference books as PDFs:
  35. > **You:** What do my books say about preparing feedback conversations?
  36. >
  37. > **Claude:** Two of your books cover this:
  38. > – Write down the goal and your observations beforehand, and keep judgements separate
  39. > (Leadership/Conversations.pdf, p. 45, printed p. 37).
  40. > – Tell the other person in advance what it will be about, so they can prepare
  41. > (Leadership/Leading teams.pdf, p. 112–113).
  42. The figures and contents are made up; this is what the source references look like.
  43. What happens in the background is shown in two short diagrams: [At a glance](#at-a-glance).
  44. ## English and German
  45. plug-n-rag works equally well with English and German notes, even mixed in one vault. The search
  46. model (multilingual-e5-small) was chosen on purpose because it handles German texts and compounds
  47. such as "Datenschutzbeauftragte" especially well, but it handles English just as well, plus about
  48. 100 other languages. An English question can also find a German note and vice versa; it is most
  49. reliable in the language of the notes.
  50. - **Claude answers in your language**, whatever language the notes are in.
  51. - **plug-n-rag's fixed texts** (search results, status, overview, the display in the chat) follow
  52. the language chosen during setup. To switch: ask Claude, or run
  53. `plug-n-rag config --set language=de` (or `language=en`).
  54. - **Every command exists in both languages**, e.g. `plug-n-rag search` and `plug-n-rag suche`,
  55. `/plug-n-rag:ingest` and `/plug-n-rag:aufnehmen`.
  56. Why this matters: plug-n-rag saves tokens, and with them computing power and energy. That should
  57. not stop at a language border.
  58. ## Terms in one minute
  59. You don't need to know these words to use plug-n-rag, but they help when reading on.
  60. | Term | Meaning |
  61. | --- | --- |
  62. | **Claude Code** | Claude as a workspace on your computer (desktop app or terminal) or in the browser. Unlike the normal chat, Claude may work with your files there. |
  63. | **Plugin** | An extension that gives Claude Code new abilities. plug-n-rag is a plugin. |
  64. | **Marketplace** | A directory you install plugins from. This repository is such a directory. |
  65. | **Vault** | A folder of Obsidian notes (recognisable by the hidden subfolder `.obsidian`). |
  66. | **Collection** | Any other folder of documents (text, Markdown, PDF) you want to make searchable. |
  67. | **Token** | The unit in which Claude reads and bills text, roughly four letters. Fewer tokens read means less usage. |
  68. | **Index** | A directory for finding things quickly, like the index of a book. plug-n-rag builds one for your notes. |
  69. | **Git, GitHub, repo** | Git stores versions of files, GitHub keeps them online. A repo (repository) is a folder managed this way. Optional for plug-n-rag, but needed if you want to work on several devices or in the browser. |
  70. | **Cloud session** | Claude Code in the browser (claude.ai/code) or in the mobile app. Claude then works on a computer run by Anthropic, with a copy of your repo. |
  71. ## Get started in three steps
  72. ### 1. Prepare
  73. - Install **Claude Code** and sign in: [guide](https://code.claude.com/docs/en/quickstart).
  74. - Install **uv**. uv is a small helper that starts plug-n-rag and brings everything it needs
  75. (such as Python) by itself. You can also skip this: if uv is missing, Claude offers to install it.
  76. - macOS or Linux, in the terminal:
  77. ```bash
  78. curl -LsSf https://astral.sh/uv/install.sh | sh
  79. ```
  80. - Windows, in PowerShell:
  81. ```bash
  82. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  83. ```
  84. ### 2. Install
  85. Pick one way. A is the easiest.
  86. **A: Through the plugin page** (desktop app or claude.ai)
  87. 1. Open **Settings → Plugins** (on claude.ai: "Customize" → "Plugins"). In the desktop app this
  88. page also opens when you type `/plugin`.
  89. 2. Top right, choose **Add → Add marketplace**, enter `sign-u-p/plug-n-rag` and confirm.
  90. 3. Click **Add** next to **plug-n-rag**.
  91. 4. Done. The plugin now belongs to your Claude account and is there from the next session (in an
  92. open session: type `/reload-plugins`).
  93. **B: In the terminal**
  94. ```bash
  95. claude plugin marketplace add sign-u-p/plug-n-rag
  96. ```
  97. ```bash
  98. claude plugin install plug-n-rag@plug-n-rag
  99. ```
  100. **C: Let Claude do it.** Write in a session: "Please run
  101. `claude plugin marketplace add sign-u-p/plug-n-rag` and
  102. `claude plugin install plug-n-rag@plug-n-rag`." Then type `/reload-plugins`.
  103. For the browser (claude.ai/code) there is a way of its own, see [Use it in the cloud](#use-it-in-the-cloud).
  104. ### 3. Set up
  105. 1. Open Claude Code **in your vault's folder** (in the desktop app: choose this folder as the
  106. project). Claude then reports: "Obsidian vault detected, but not set up yet."
  107. 2. Type `/plug-n-rag:setup`.
  108. 3. Claude calmly walks you through the setup and explains each step. You decide, Claude does the
  109. work:
  110. - an inventory of your notes,
  111. - a short note on which data goes where,
  112. - the question which folders stay private (e.g. a journal),
  113. - if you like, a private repo on GitHub so it works on several devices,
  114. - an estimate of how long the setup takes and what it costs (locally: nothing),
  115. - the first indexing, an overview of your vault and a test search.
  116. 4. On the first start Claude Code may ask whether plug-n-rag may run automatically. Please allow
  117. it, otherwise the search does not stay up to date.
  118. During the first setup plug-n-rag downloads a language model once (about 470 MB, a few minutes
  119. depending on your connection). Keyword search works before that.
  120. ### And then: just ask
  121. - "What did I note down about time management?"
  122. - "Summarise my meeting notes from October. Which tasks are still open?"
  123. - "Research everything in my vault I collected about data protection in associations."
  124. - "What do my reference books say about service charge statements?"
  125. - "Write a summary for the team from my reading notes."
  126. If an answer was too short or too long, just say so ("that was too shallow"). plug-n-rag remembers
  127. that for this kind of task.
  128. ## Good to know
  129. **Privacy in brief**
  130. - What Claude reads goes to Anthropic, as with any use of Claude. With plug-n-rag that is usually
  131. *less* than without, because Claude reads only matching sections.
  132. - The search itself runs on your computer. Nothing goes to other services without your consent.
  133. - Folders and notes you mark as private are never searched and never stored.
  134. <details>
  135. <summary>Privacy in detail</summary>
  136. - **What goes where:**
  137. | Service | What | When |
  138. | --- | --- | --- |
  139. | Anthropic | the sections Claude reads, and your questions | whenever you use Claude |
  140. | Anthropic | whole scanned documents for transcription | only after asking you explicitly |
  141. | Hugging Face | nothing of yours: only the language model is downloaded from there, once | during the first setup |
  142. | Voyage AI | note texts for computing the search data | only if you explicitly choose this service |
  143. | GitHub | notes and search index in **your private** repo | only if you use a repo |
  144. - **The search index contains no note text**, but it represents content as numbers. Treat it as
  145. confidentially as the notes themselves. A repo must be private; setup and status check this and
  146. warn if not.
  147. - **Private areas:** folders you enter as private (`private_folders`) and notes with
  148. `privat: true` in the properties at the top of the note (frontmatter) are left out completely.
  149. If a note becomes private later, plug-n-rag removes its search data at the next sync.
  150. - **Log:** so that plug-n-rag can learn, it remembers which notes were found and read (paths and
  151. numbers), but never your questions and never note contents. The log stays on your computer.
  152. - **Keys for Voyage AI** belong only in the environment variable `VOYAGE_API_KEY` (in the cloud: in
  153. a "network secret"), never in a file in the repo.
  154. </details>
  155. **Cost:** with the local language model plug-n-rag costs nothing beyond your normal Claude usage,
  156. and it lowers that. The optional service Voyage AI charges by amount of text; Claude tells you the
  157. current price beforehand.
  158. **What plug-n-rag creates:**
  159. | What | Where |
  160. | --- | --- |
  161. | settings and search index (transcripts too, if you like) | a folder `.plug-n-rag/` in your vault. Obsidian hides it. |
  162. | working files (the actual search database, log, intermediate states) | in your user account's cache, never in the vault, never online |
  163. | transcripts of PDFs | as normal notes, next to the PDF or in a folder "Abschriften/" (your choice) |
  164. To get rid of plug-n-rag: uninstall the plugin and delete the folder `.plug-n-rag/`.
  165. ## How plug-n-rag works
  166. For everyone who wants to know exactly. None of this is needed to use it. First an overview, then
  167. the details; each detail section expands.
  168. ### At a glance
  169. **When new information arrives** (a new or changed note, a PDF):
  170. ```mermaid
  171. flowchart TD
  172. A["📝 New or changed note<br/>or 📄 PDF"] --> B{"Scanned PDF?"}
  173. B -- "no" --> D["Split into sections<br/>at the headings"]
  174. B -- "yes" --> C["Get the text: text layer →<br/>local text recognition →<br/>Claude transcribes, only with your consent"]
  175. C --> D
  176. D --> E{"Section already known?<br/>(checksum)"}
  177. E -- "yes, e.g. renamed" --> G
  178. E -- "no" --> F["Compute its meaning as numbers<br/>on your computer"]
  179. F --> G["Index file in .plug-n-rag/index/<br/>no note text, travels with your repo"]
  180. G --> H["Search database<br/>rebuilt locally at every start"]
  181. ```
  182. plug-n-rag splits the note into sections, computes only what is new and stores the result next to
  183. your notes. Your notes themselves stay unchanged.
  184. **When you ask a question:**
  185. ```mermaid
  186. flowchart TD
  187. Q["💬 Your question"] --> W["Whole words"]
  188. Q --> T["Word parts"]
  189. Q --> M["Meaning"]
  190. W --> R["One shared ranking"]
  191. T --> R
  192. M --> R
  193. R --> K{"Anything relevant<br/>enough?"}
  194. K -- "no" --> N["“Nothing relevant found”:<br/>Claude does not make anything up"]
  195. K -- "yes" --> L["List of hits: note, section,<br/>lines, relevance in words"]
  196. L --> S["Claude reads only<br/>the matching sections"]
  197. S --> A2["✅ Answer with source"]
  198. ```
  199. Three searches run at once and are merged into one ranking. Claude sees a short list first and
  200. then reads only the passages it needs, which is where the tokens are saved.
  201. ### In detail
  202. <details>
  203. <summary><b>1. Splitting notes into sections</b></summary>
  204. plug-n-rag splits each note at its headings. Very long sections are also split at paragraphs (guide
  205. value: about 500 tokens, with some overlap so that no thought gets lost at a cut). Each section
  206. knows its place in the note, e.g. "Website relaunch › Decisions", and its lines. PDFs are split by
  207. page, so that sources always name an exact page.
  208. Properties at the top of the note (frontmatter), tags and links (`[[…]]`) are not searched as text
  209. but stored as extra information, e.g. for the question "What is linked to this note?".
  210. </details>
  211. <details>
  212. <summary><b>2. Meaning as numbers: a section's "fingerprint"</b></summary>
  213. So that Claude finds things even when the words differ, a **language model** computes a series of
  214. 384 numbers for each section, a kind of fingerprint of its meaning (technical term: *embedding*).
  215. Sections with similar meaning get similar series of numbers, whatever words they use. For a
  216. question plug-n-rag computes the same fingerprint for the question and looks for the most similar
  217. sections.
  218. By default the model runs **on your computer** ("multilingual-e5-small", about 470 MB once). It was
  219. chosen for its especially good German and understands English and about 100 other languages just
  220. as well. It is pinned to a fixed version so that results never change unnoticed. If you prefer,
  221. you can use the Voyage AI service instead: faster on weak computers, but it costs money and sends
  222. texts there.
  223. The text cannot simply be recovered from the numbers, but they reveal roughly what it is about.
  224. That is why they count as confidential.
  225. </details>
  226. <details>
  227. <summary><b>3. Three ways of searching, one ranking</b></summary>
  228. Every search runs three ways at once:
  229. 1. **whole words**, like a classic keyword search,
  230. 2. **word parts**, so that "privacy" also finds "privacy-friendly", and German compounds such as
  231. "Datenschutz" find "Datenschutzbeauftragte",
  232. 3. **meaning**, using the fingerprints from step 2.
  233. The three rankings are merged into one: a section that ranks high on several ways ends up at the
  234. top (technical term: *reciprocal rank fusion*). Long, rare words from your question count more
  235. than frequent ones. Reference lists are ranked down, because they contain many technical terms but
  236. rarely the answer.
  237. Then plug-n-rag decides **how many** hits to show: it cuts where relevance drops clearly, instead
  238. of always returning a fixed number. If nothing is above a minimum threshold, the result is "Nothing
  239. relevant found", and Claude should then not pretend it is in your notes.
  240. plug-n-rag shows relevance in words ("very relevant", "relevant", "marginal"), not as a number.
  241. </details>
  242. <details>
  243. <summary><b>4. Reading step by step: where the savings come from</b></summary>
  244. Claude works like a good researcher:
  245. 1. **Overview:** at the start Claude gets a short overview of your vault (areas, counts).
  246. 2. **Search:** a list of hits names note, section, lines and relevance, but no full text yet.
  247. 3. **Outline:** for long notes Claude first looks at the headings.
  248. 4. **Read a section:** only now does Claude read exactly the matching passages.
  249. Claude reads whole notes only when the context is really needed, for example when you have it write
  250. a text from your notes. plug-n-rag keeps estimating the savings: tokens read compared to what
  251. reading all hit files completely would have cost. `/plug-n-rag:status` shows them.
  252. </details>
  253. <details>
  254. <summary><b>5. Always up to date, without you doing anything</b></summary>
  255. plug-n-rag runs automatically at two points:
  256. - **At the start of every session:** fetch the newest state (if you use a repo), sync the notes,
  257. build the search database, give Claude the short overview. This usually takes a few seconds;
  258. anything longer continues in the background.
  259. - **After each of Claude's answers:** a short sync in the background in case something changed,
  260. even if you wrote in Obsidian in the meantime.
  261. The sync recognises changes by a checksum (a unique value per file). Only new or changed sections
  262. are recomputed. If you rename or move a note, plug-n-rag recognises the sections and recomputes
  263. nothing at all. Deleted notes disappear from the search.
  264. In a project without a vault plug-n-rag does nothing: it checks within a few milliseconds whether
  265. there is a vault and otherwise exits immediately.
  266. </details>
  267. <details>
  268. <summary><b>6. Why the search index lives in your vault</b></summary>
  269. Computing the fingerprints takes time (and, with Voyage AI, money). That is why plug-n-rag stores
  270. them as small files in `.plug-n-rag/index/`, one per note, without note text. If your vault is in a
  271. repo, they travel with it: on a second computer or in a cloud session everything is ready to search
  272. at once, without recomputing.
  273. The actual search database (SQLite with full-text and vector search), by contrast, is rebuilt from
  274. these files and your notes at every start, on your computer. It is never uploaded and never synced.
  275. There is no server and no database on the internet.
  276. </details>
  277. <details>
  278. <summary><b>7. Learning, with guard rails</b></summary>
  279. With every search Claude states what it is searching for: a **question** (few, precise hits),
  280. **research** (more breadth) or something to **create** (few notes, but more complete). plug-n-rag
  281. observes how deeply Claude reads afterwards and slowly adjusts how many hits a search returns: at
  282. most one step per session and always within fixed limits. Your own feedback ("too shallow") takes
  283. precedence. Reset with `/plug-n-rag:reset-learning`.
  284. </details>
  285. <details>
  286. <summary><b>8. PDFs and scanned pages</b></summary>
  287. `/plug-n-rag:ingest` gets the text out of PDFs, page by page, trying in turn:
  288. 1. the PDF's embedded text (free, exact),
  289. 2. text recognition on your computer (Tesseract, if installed),
  290. 3. a quality check (how confident was the recognition, how many real words),
  291. 4. only if that is not enough and **you agree**: Claude reads the page images and transcribes them
  292. word for word, with the inexpensive model Haiku, for handwriting with Sonnet if you wish.
  293. The result becomes a new note (vault) or a readable transcript in `.plug-n-rag/abschriften/`
  294. (collection). Existing files are never overwritten. plug-n-rag recognises printed page numbers
  295. where possible and includes them in sources.
  296. </details>
  297. ## More options
  298. ### See what plug-n-rag does
  299. The add-on **plug-n-rag Display** shows a calm line per step in the chat (e.g.
  300. "Searched: 3 notes · best very relevant") that you can expand. A narrow band above the prompt only
  301. appears while work runs in the background or something is waiting for you. On request (`/pnr`)
  302. there is a side pane with history, state and estimated savings. Claude sees none of it, so it costs
  303. nothing. It follows the vault's language.
  304. ```
  305. /plugin install plug-n-rag-anzeige@plug-n-rag
  306. ```
  307. It works in the desktop app, the terminal and VS Code, and in the mobile app as one quiet line. More:
  308. [plugins/plug-n-rag-anzeige/README.md](plugins/plug-n-rag-anzeige/README.md).
  309. ### Make other folders searchable
  310. This suits libraries of reference books, course material, contract folders or project archives.
  311. Tell Claude, for example: "Make my folder Reference searchable". It works with Markdown, text and
  312. PDFs whose text can be selected. Your files are never changed. Claude asks you where plug-n-rag
  313. should keep its own files:
  314. - **in the folder** (subfolder `.plug-n-rag`): good if you share or sync the folder, e.g. via
  315. Nextcloud or a network drive; the index then travels with it,
  316. - **central on your computer:** nothing changes in the folder at all.
  317. ### Use it in the cloud
  318. With a vault in a private GitHub repo, plug-n-rag also works in cloud sessions (browser, mobile
  319. app). It can even be set up entirely there: start a session at claude.ai/code with your vault repo
  320. and write:
  321. ```text
  322. Please install the Claude Code plugin plug-n-rag:
  323. claude plugin marketplace add sign-u-p/plug-n-rag
  324. claude plugin install plug-n-rag@plug-n-rag
  325. Then set up my vault with /plug-n-rag:setup. If that command is not available in this session
  326. yet, use ~/.claude/plugins/cache/plug-n-rag/plug-n-rag/<version>/scripts/plug-n-rag
  327. and follow the guide from "plug-n-rag guide setup".
  328. ```
  329. Claude sets up the vault and makes sure future cloud sessions have plug-n-rag automatically. For
  330. that the **cloud environment** (the settings of the computer Claude works on in the cloud) needs two
  331. things: permission for the model download and a small script that installs plug-n-rag at start.
  332. Claude proposes both or explains where to enter them (`/plug-n-rag:cloud`).
  333. <details>
  334. <summary>Set up the cloud environment by hand</summary>
  335. Why not simply through the repo? Cloud sessions do not install plugins that a repo requests itself
  336. (`.claude/settings.json`). That is why the installation belongs in the cloud environment.
  337. 1. In the session bar, tap the cloud environment's name, then "Edit" (or "Add" an environment of
  338. your own, e.g. "Vault").
  339. 2. **Network access:** "Limited", keep "Allow package managers" ticked. Under
  340. **Allowed domains** enter:
  341. ```text
  342. huggingface.co
  343. *.hf.co
  344. ```
  345. 3. Paste the **setup script**:
  346. ```bash
  347. #!/bin/bash
  348. command -v claude >/dev/null 2>&1 || exit 0
  349. claude plugin marketplace add sign-u-p/plug-n-rag >/dev/null 2>&1 \
  350. || claude plugin marketplace update plug-n-rag >/dev/null 2>&1 || true
  351. claude plugin install plug-n-rag@plug-n-rag >/dev/null 2>&1 || true
  352. P=$(ls -d "$HOME"/.claude/plugins/cache/plug-n-rag/plug-n-rag/*/ 2>/dev/null | sort -V | tail -1)
  353. if [ -n "$P" ]; then "${P}scripts/plug-n-rag" load-model --model intfloat/multilingual-e5-small || true; fi
  354. exit 0
  355. ```
  356. 4. Save and start a new session with the vault repo in this environment. The first start takes a
  357. few minutes (model download). After that the cloud keeps the finished environment, and new
  358. sessions are ready to search at once.
  359. 5. Check: ask Claude to run `plug-n-rag cloud --check`.
  360. Good to know:
  361. - The search index (`.plug-n-rag/index/`) must be in the repo, otherwise every cloud session
  362. recomputes it.
  363. - With Voyage AI instead of the local model the Hugging Face permission is not needed. Enter the
  364. Voyage key as a **network secret** of the environment for `api.voyageai.com`.
  365. - New versions of plug-n-rag reach the cloud environment when it is rebuilt (after about seven
  366. days at the latest, or after a change to the script).
  367. </details>
  368. ### Publish changes from the chat ("to main")
  369. Cloud sessions work on a branch of their own in your repo. What Claude changes in notes there only
  370. reaches the main state (`main`) when you take it over. You can do that right from the chat: say
  371. "put it on main" (or `/plug-n-rag:to-main`). Then you also see the changes in Obsidian.
  372. Nothing gets overwritten: if the main state has changed in the meantime (e.g. through Obsidian on
  373. your computer), it is merged first. If you and Claude changed **the same note** differently, Claude
  374. asks you which version should count. If something looks like a secret key, nothing is published at
  375. all.
  376. ## Reference
  377. ### Commands
  378. | Command | What for |
  379. | --- | --- |
  380. | `/plug-n-rag:setup` | guided setup (also to continue or check) |
  381. | `/plug-n-rag:status` | Is everything up to date? Any errors? How much was saved? |
  382. | `/plug-n-rag:ingest` (`aufnehmen`) | turn PDFs and scanned documents into searchable text |
  383. | `/plug-n-rag:cloud` | set up and check use in cloud sessions |
  384. | `/plug-n-rag:to-main` (`nach-main`) | publish changes from the chat to the repo's main state |
  385. | `/plug-n-rag:reindex` | recompute everything, e.g. after switching the model |
  386. | `/plug-n-rag:switch-model` (`modell-wechseln`) | choose the local model or Voyage AI |
  387. | `/plug-n-rag:reset-learning` (`lernen-zuruecksetzen`) | reset learned search habits |
  388. In the background Claude uses the tools `plug-n-rag search`, `outline`, `read`, `related` and `map`
  389. (German: `suche`, `gliederung`, `lesen`, `verwandt`, `karte`). You can also call them yourself in
  390. the terminal (`plug-n-rag --help`).
  391. <details>
  392. <summary>Settings (<code>.plug-n-rag/plug-n-rag.yml</code>)</summary>
  393. The easiest way to change settings is to ask Claude. The most important ones:
  394. | Setting | Meaning | Default |
  395. | --- | --- | --- |
  396. | `language` | language of the fixed texts (`en`, `de`); an older configuration without it counts as German | chosen during setup |
  397. | `embedding.provider`, `embedding.model` | which language model computes the fingerprints (`local` or `voyage`) | `local`, `intfloat/multilingual-e5-small` |
  398. | `private_folders` | folders that are never searched, e.g. `["Journal/**"]` | empty |
  399. | `exclude` | further excluded folders (e.g. templates) | system folders, detected templates |
  400. | `folders` | a short description per folder for the overview | empty |
  401. | `formats` | which file types are read (`markdown`, `text`, `pdf`) | vault: `markdown` |
  402. | `abschriften.ort` | where transcripts of PDFs go | asked the first time |
  403. | `transcription` | whether to ask before transcribing (`ask`, `allow`, `local_only`) | `ask` |
  404. | `anzeige` | source line in cloud sessions (`kompakt`, `aus`) | `kompakt` |
  405. | `tuning.commit_learning` | put what was learned into the repo too (otherwise local only) | `false` |
  406. | `git.auto_commit`, `git.auto_push` | automatically save or upload changes at start | off |
  407. </details>
  408. <details>
  409. <summary>Moving from an older version</summary>
  410. Up to version 0.5 the settings were in `plug-n-rag.yml` in the main folder and working files in
  411. `.plug-n-rag/cache`. That keeps working. At start plug-n-rag points out the tidier layout;
  412. `plug-n-rag migrate` (or asking Claude) switches over without recomputing anything. Pages already
  413. transcribed are kept. Configurations from before 0.9 have no `language` and stay German.
  414. </details>
  415. <details>
  416. <summary>For advanced users: MCP server</summary>
  417. plug-n-rag also ships the search tools as an MCP server (a standard interface through which Claude
  418. uses other programs' tools). It is not active automatically. After the first session with
  419. plug-n-rag you can register it like this:
  420. ```bash
  421. claude mcp add plug-n-rag -- ~/.cache/plug-n-rag/plug-n-rag mcp
  422. ```
  423. </details>
  424. ## Known limits
  425. - Markdown, text and PDFs with selectable text are read. Word, HTML and e-books will follow.
  426. - Text recognition for scanned pages on your computer needs the program Tesseract (Claude offers to
  427. install it). Without Tesseract, transcription by Claude remains, only after asking you.
  428. - The one-time model download is large, about 470 MB.
  429. - How strict "relevant" is was tuned on a small sample vault and will be adjusted with real vaults.
  430. Feedback helps.
  431. - On Windows, Git Bash is needed (it comes with "Git for Windows").
  432. - Several collections cannot be searched together yet.
  433. - Obsidian Git is limited on phones. Recommendation: Obsidian Sync for the devices, Git only on the
  434. computer.
  435. ## If something gets stuck
  436. | What you see | What helps |
  437. | --- | --- |
  438. | "uv missing" at start | step 1 above, or let Claude do the installation |
  439. | New notes are not found | `/plug-n-rag:status` shows whether something is still pending |
  440. | "keyword search only" | the language model is not there (yet) or does not fit; `/plug-n-rag:status` explains why |
  441. | plug-n-rag is missing in the cloud | the session runs in a different environment, or the setup script is missing (`/plug-n-rag:cloud`) |
  442. | Scanned PDFs are "waiting for ingestion" | `/plug-n-rag:ingest` |
  443. | The plugin page shows an old description, or plug-n-rag Display is missing | the app still knows an old catalogue: run `claude plugin marketplace update plug-n-rag`, or remove the marketplace on the plugin page and add `sign-u-p/plug-n-rag` again |
  444. More background (in German): [DECISIONS.md](DECISIONS.md) (why things are built this way),
  445. [OPEN.md](OPEN.md) (open points), [SPEC.md](SPEC.md) (original specification).
  446. ## For developers
  447. This repository is a marketplace with several plugins, each in a folder of its own:
  448. ```
  449. .claude-plugin/marketplace.json catalogue: plug-n-rag and plug-n-rag-anzeige
  450. plugins/plug-n-rag/ the main plugin
  451. .claude-plugin/plugin.json
  452. scripts/plug-n-rag launcher (uv, environment in the user cache; session start puts it on the PATH)
  453. hooks/hooks.json automatic runs at start and after each answer
  454. skills/ suche, setup, cloud, nach-main, status, reindex, aufnehmen, modell-wechseln,
  455. lernen-zuruecksetzen; English names: ingest, to-main, switch-model, reset-learning
  456. agents/ transkription (Haiku)
  457. src/plug_n_rag/ Python core (i18n.py: English/German)
  458. tests/ pytest, sample vault, PDF generator
  459. plugins/plug-n-rag-anzeige/ optional mod: display in the chat (TypeScript)
  460. tools/check.sh checks the catalogue and all plugins
  461. ```
  462. Check everything:
  463. ```bash
  464. tools/check.sh --schnell
  465. ```
  466. Without `--schnell` the tests with the real language model run too (about 470 MB once), including
  467. English and cross-language searches. Tests against Voyage AI only run with `VOYAGE_API_KEY` set. How
  468. to add another plugin: [CONTRIBUTING.md](CONTRIBUTING.md) (German).
  469. Licence: MIT. Ideas taken over and their licences: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.