Matrix

Matrix for Claude Code

Claude Code can grep code, but it cannot search PDFs, Word files, scans or charts by meaning. Matrix gives it a local semantic index over your document folders, with citations to file, page and passage, cross-references between provisions and tables over many documents — everything runs on your computer, and Claude Code itself is the language model, so no extra model or API key is needed. DEMO.md compares it with Claude Code alone on 442 and on 1,592 pages of public documents.

Why use it

Measured twice, Claude Code alone vs. with the plugin (DEMO.md has the numbers, the questions and the right answers): on 442 pages of EU regulations and a report (4 questions, 2 runs each), and on 1,592 pages in 14 documents in four languages (version 0.2.3, 4 questions, 1 run each).

• Less effort on large document sets. 442 pages: on average 42 s instead of 126 s per question (about 3×; 2–4× depending on the question), with less than half the tool calls (9.5 instead of 21.4) and less than half the input tokens (303 k instead of 651 k). 1,592 pages: 35 % less time (117 s instead of 180 s for the four questions), 34 % fewer input tokens (405 k instead of 615 k), 60 % fewer output tokens and half the rounds. The gain is largest for a question about one provision asked in other words or another language, and smallest where the answer is spread over several acts (almost none: Claude searches once per act either way).
• Index once, ask many times. Indexing runs once on your computer and costs no Claude tokens; the index stays across sessions and follows its folder by itself. Every further question about the same documents is then faster and uses fewer tokens (DEMO.md). This pays off when there are many or long documents, further questions about the same set are likely and answers should come with evidence — for example contracts, regulations, project files, technical manuals, studies, minutes or reports. For a one-off question Claude may search the files itself, and says so when an answer has no evidence from your files.
• Citations with file, article and passage, checked against the text. Every answer in both tests named the right document, article and passage. Two page numbers on the large set were one page off, where a passage runs over a page break; fixed since: a hit lists every page its passage covers, and the passage text marks each page change with [p. N].
• Finds paraphrases, scans and charts. Search is by meaning, so a question in other words than the text still finds the provision, and a value that exists only in a chart is found on the chart page. On 30 test questions the right place was first for 17 (12 in 0.2.2) and among the first five for 27 (19 before), with the optional re-ranking model; one search result is about 1,160 tokens instead of 5,500. In folders that mix languages, search works best in the documents' language; the skills tell Claude to search in it too.
• Tables over many documents. One question put to every document or passage, as a table with a source per cell.
• Everything local, no extra model access. Index and search run on your computer; Claude Code itself is the language model, so no second model or API key is needed.
• Claude Code alone answered all questions correctly too (8/8 and 4/4); with the plugin one answer in the first runs of the 442-page test was wrong (a chart label too small to read), fixed in the ask skill, then 4/4 correct. The gain is effort, not correctness.

It brings little for small, well-structured collections that Claude Code reads quickly anyway: one short document is answered just as well without it, and indexing costs minutes once per folder.

Install

Runs on macOS (Apple silicon), Windows 10 or later (x64) and Linux (x64 and arm64, glibc 2.34 or later, for example Ubuntu 22.04, Debian 12, RHEL 9), with Node.js 18 or later (for npx).

claude plugin marketplace add matthiasnordwig/matrix-mcp

claude plugin install matrix@matrix-mcp

Then start claude (best in the folder with your documents) and just ask Claude about your documents — it sets Matrix up with you the first time (or run /matrix:setup). You do not need to read anything else.

How it works

• Documents are split along their own structure — PDF layout, headings, articles, tables — not by a language model (the semantic chunker is not the default).
• Documents are cut by their kind: laws and standards along articles, mails into one passage per message of a thread (passages and attachments repeated in several mails are kept once, attachments become documents of their own), minutes, transcripts, slides, books and source code each by their own markers; a text of no clear kind by paragraphs.
• Search is by meaning plus keywords, and follows cross-references between provisions; scans and charts are found too. It can be narrowed to the mails of one sender, a date range or a folder ("what did X write in autumn 2001").
• The best passages are put first by a second, small model (re-ranking, optional: about 0.6 GB from Hugging Face, license Apache-2.0, downloaded once and only after you agree; without it search works as before).
• Hits are compact: an excerpt of about 300 characters with file, pages and the outline path (document › chapter › article › paragraph), hits of one article merged. Claude reads the full text with get_chunks, and a whole article or section with get_section, before it cites.
• Every answer cites file, page and passage, and the citations are checked against the text.
• Tables over many documents hand small model tasks to Claude through a queue (llm_tasks / llm_answer); they run in your Claude Code session and use your Claude quota.
• Index, models and the list of allowed folders live in ~/Library/Application Support/Matrix MCP (macOS), %APPDATA%\Matrix MCP (Windows) or ~/.local/share/matrix-mcp (Linux); nothing leaves your computer except the passages Claude reads.
• Matrix reads the folder you started Claude Code in; for any other folder it asks you (Accept / Decline) and remembers your answer.
• An indexed folder stays in sync: new and changed files are read again by themselves (checked at start and before searches, at most once a minute); a deleted file stays in the collection, marked missing and left out of searches — nothing is deleted for you.
• While Matrix reads or searches, it keeps the computer from sleeping, as the Matrix app does.
• /matrix:status shows what Matrix holds and does at any time.

Use

You can also just ask; Claude picks the matching skill. The server also offers its own prompts (type / and look for index_and_ask, compare_documents, …). Tables hand Claude small model tasks (llm_tasks, answered with llm_answer). With more than about ten, Claude starts the plugin's worker agent matrix:llm-worker (Sonnet, only these two tools) for each batch: it fetches and answers the tasks itself and reports only counts, so the passages do not fill your conversation. They use your Claude Code session like any other work you ask for; Claude tells you the number first.

Details

Folders. Matrix reads the folder where you started Claude Code. For any other folder it asks you first (Accept / Decline) and keeps your answer until you take it back (ask Claude to revoke it). It never reads /, your whole home folder, system folders, hidden folders in your home folder or ~/Library, and never changes or deletes your files. To always allow folders without being asked, set them when installing (several separated by commas; a folder name must not contain a comma) — Claude Code 2.1.222 has no Configure screen under /plugin:

claude plugin install matrix@matrix-mcp --config folders=/path/one,/path/two

Restart Claude Code after changing settings. The same works for --config embedding_model=... and --config embedding_api_key=.... A folder that does not exist or cannot be read is reported by name (/matrix:status); on macOS the privacy protection of Documents, Desktop and Downloads can be the reason — allow the app that runs Claude Code under System Settings › Privacy & Security › Files & Folders. The index folder (~/Library/Application Support/Matrix MCP (macOS), %APPDATA%\Matrix MCP (Windows) or ~/.local/share/matrix-mcp (Linux); MATRIX_MCP_DATA_DIR sets another) must exist or be creatable and be readable and writable for you; do not delete it while Claude Code runs.

Search model. Leave embeddinggemma-2 (multilingual, also searches charts and scans). The first time it is needed Claude tells you the size (about 1.2 GB, from Hugging Face, once) and asks before downloading. Alternatives: embeddinggemma-2-q4 (0.2 GB, text only), onnx-folder:/path (a model you already have), endpoint:https://host/v1#model (your own embedding service; the API key is stored in the system keychain).

Re-ranking. After the search model, Claude offers once to download the re-ranking model (bge-reranker-v2-m3, int8, about 0.6 GB from Hugging Face, license Apache-2.0) and does so only after you agree. It re-orders the first 20 candidates by relevance, which costs about 4 s per search on an Apple-silicon Mac (not yet measured on Windows and Linux). For a long mail it reads the paragraph closest to the question instead of the header and recipients. Declined or not installed: the search runs as before. Claude Code starts the server with npx -y @matthiasnordwig/matrix-mcp@0.2.5: npm fetches the program once (about 20 to 30 MB, only the package for your system, no install script). For Claude Desktop, each release also carries matrix-standalone.mcpb, the same program as a desktop extension.

Allow the reading tools once. To stop Claude Code from asking before every read, add this to the permissions.allow list of your settings.json (~/.claude/settings.json, or .claude/settings.json in a project). It lists only tools that read the index and change nothing; wildcards like mcp__plugin_matrix_matrix-standalone__* exist but would also allow reading folders and the model download, so they are not used here.

{

"permissions": { "allow": [ "mcp__plugin_matrix_matrix-standalone__find_citing_chunks", "mcp__plugin_matrix_matrix-standalone__get_chunks", "mcp__plugin_matrix_matrix-standalone__get_page_image", "mcp__plugin_matrix_matrix-standalone__get_section", "mcp__plugin_matrix_matrix-standalone__get_status", "mcp__plugin_matrix_matrix-standalone__grid_results", "mcp__plugin_matrix_matrix-standalone__job_status", "mcp__plugin_matrix_matrix-standalone__list_allowed_folders", "mcp__plugin_matrix_matrix-standalone__list_contexts", "mcp__plugin_matrix_matrix-standalone__list_documents", "mcp__plugin_matrix_matrix-standalone__list_grid_profiles", "mcp__plugin_matrix_matrix-standalone__list_grid_runs", "mcp__plugin_matrix_matrix-standalone__list_norm_references", "mcp__plugin_matrix_matrix-standalone__l