Academic Writer: the full guide

1. What it does

Academic Writer is a plugin (an add-on) for Claude Code, Anthropic's AI assistant that runs in a text window on your computer. You talk with Claude in plain language, and the plugin guides the conversation from a vague topic to a finished, footnoted article.

It works in Hebrew and in English, including right-to-left layout and Hebrew footnotes. For example, a Hebrew paragraph in the finished file looks like this:

הטענה המרכזית של המאמר היא שהפולמוס לא נסב על שאלת הסמכות בלבד, אלא על הגדרת הקהילה עצמה.¹

2. Before you start

You need three things. Setup (step 4) checks each of them for you and explains anything that is missing.

Helpful, but optional:

• 5 to 10 of your published articles (PDF or Word), so the plugin can learn your writing style.
• Your source texts as PDFs or Word files. The optional Trove library (an online bookshelf for your sources) lets the plugin search them page by page.
• Python 3, a free program that reads and writes Word and PDF files. Some Macs and most Linux computers already have it; if yours does not, setup shows you how to install it from python.org, step by step. Setup also asks before installing the small helper packages it needs.

3. Install

Installing happens once; allow about 15 minutes if you have never used Claude Code. Each step says what you should see.

A. Get Claude Code and sign in (skip if you already use it)

1. You need a Claude plan that includes Claude Code (Pro, Max, Team or Enterprise; the free plan does not). Subscribe or sign in at claude.ai.
2. Open the Terminal app (see "How to open a terminal" below).
3. Paste this line and press Enter. It shows no progress for a minute; that is normal. On Windows PowerShell use irm https://claude.ai/install.ps1 | iex instead.

   curl -fsSL https://claude.ai/install.sh | bash

4. Make a folder for your research (for example Academic inside Documents). In Terminal type cd (with a space), drag the folder into the window, press Enter, type claude and press Enter.
5. The first time, your web browser opens so you can sign in. Sign in and return to the Terminal window. You now see Claude Code's prompt box, where you type to Claude.

If Terminal says command not found: claude, close it, open a new Terminal window and repeat step 4.

B. Add the plugin

In the prompt box, type these two lines one at a time, pressing Enter after each. Each prints a short confirmation. If the first one says it cannot find the marketplace, check the line is typed exactly and try again; if it still fails, copy the message to Claude:

/plugin marketplace add yodem/academic-writer

/plugin install academic-writer@yodem

The first line tells Claude Code where to find the plugin (a marketplace is simply a list of plugins). The second installs it.

C. Restart, then check

Type /exit and press Enter, then type claude again in the same folder, so the new commands appear. To check, type /plugin, open the Installed tab with the arrow keys and look for academic-writer.

If you prefer the regular terminal window instead of Claude Code's prompt box, the same two steps are:

claude plugin marketplace add yodem/academic-writer
claude plugin install academic-writer@yodem

4. First run

In Claude Code, inside your research folder, type:

/academic-writer:setup

Setup is a short conversation, one question at a time, about 10 minutes. It:

1. asks your field of study and the citation style you use;
2. walks you through getting a free Gemini key, click by click, and tests that it works;
3. checks the small helper tools the plugin needs and asks your permission before installing anything;
4. writes one short sample paragraph so you can see it working.

After you store the Gemini key, setup asks you to restart once: quit Claude Code completely (type /exit), open it again in the same folder, type /academic-writer:setup and choose Check my Gemini key. Your answers are saved, so nothing is asked twice.

After setup, if you want the plugin to learn your personal style, copy 5 to 10 of your published articles (PDF or Word) into the past-articles folder inside your research folder (setup created it), then run:

/academic-writer:init

init reads your articles, shows you what it learned about your style so you can correct it, and helps you connect your source library. It is safe to run setup or init again later; they update your profile and never erase it.

Setup and init also ask whether to add PageIndex, an optional second library for your books. The safe answer is "Not now": your books are then read from Trove, exactly as before. Section 11 explains the choice.

What you can do now

At the end, setup shows a short list of the commands that are ready for you, based on whether you are a student, a researcher or a teacher. Only commands whose tools are in place are listed. To see the list again, run /academic-writer:setup; for the full tour, run /academic-writer:intro.

Setup also asks you to choose one visible home folder. It keeps your details, your courses and the list of your project folders in one place you can open yourself.

5. Your first article

Type /academic-writer:write. The first part is a conversation; the second part the plugin does on its own while you wait.

1. Topic and language. Say what you want to write about, as roughly as you like, and in which language. Claude asks follow-up questions.
2. Choose your sources. You see the sources you have made available and pick the ones for this article.
3. Deep reading. The plugin reads the chosen sources and maps the evidence they contain: arguments, quotations, page numbers, and gaps.
4. Thesis. You get two or three possible theses based on that evidence. Pick one, adjust one, or write your own.
5. Outline. Together you shape the sections and what each one argues. Nothing is written until you say the outline is ready.
6. Drafting. The plugin writes the article paragraph by paragraph from the approved outline, in your style.
7. Citation check. A separate checker compares every footnote with your sources. Paragraphs that fail are rewritten; if one still fails, it is named for you to look at.
8. Word file. You receive a .docx with real Word footnotes and a bibliography. Claude tells you where it saved it.
9. Your comments. Open it in Word. Add comments or tracked changes anywhere you want something changed. Save and close it.
10. Revise. Run /academic-writer:revise. It reads your comments, groups them, asks you to confirm each group, updates the text and makes a new Word file. Repeat 9 and 10 as often as you like.

6. All commands

Type any of these in Claude Code. This list is generated from the plugin itself, so it always matches the version you have installed.

You can also just describe what you want in your own words ("proofread my article", "how does this plugin work?"); Claude picks the right command for most requests. Setup, init and voice only run when you type them, because they change your settings.

7. Where your files live

There are two places. Neither is uploaded anywhere by the plugin except as described under Privacy.

In your research folder (one per project)

In the plugin's own data folder (shared by all your projects)

Your voice data (the passages you chose as examples of your style, the writing habits the plugin learned, your preferred terms, and the before-and-after pairs from your own corrections) lives in one place so every project benefits. It is inside your home folder under .claude/plugins/data/, in a folder whose name starts with academic-writer. The same folder keeps a small log of plugin mistakes you flagged during /academic-writer:revise, so they can be fixed. If you chose to install the plugin's own PageIndex helper (section 11), it lives here too, in a folder called pageindex, together with the books you prepared for it.

This folder survives plugin updates. It is removed if you uninstall the plugin, unless you ask to keep it (see section 10).

8. Privacy

• Anthropic (Claude). Your conversation with Claude, and the text Claude reads to help you (your drafts, the passages of sources it checks), are sent to Anthropic, as with any use of Claude Code.
• Google (Gemini). If you set up a Gemini key, the paragraphs being drafted, edited, proofread or summarised, the source passages they rely on, and any scanned pages you ask it to read are sent to Google's Gemini service. On Google's free tier, Google may use what you send to improve its products; check Google's current terms, and consider a paid key for unpublished work you consider sensitive.
• Google and PageIndex (optional). If you prepare a book for PageIndex and choose Gemini summaries, the text of each section of the book is sent to Google so Gemini can write a short outline. The plugin tells you how much text and asks first, every time. There is a free choice that sends nothing to Google: it reuses the notes already written for Trove. Nothing is ever sent to PageIndex Cloud; the plugin has no code for it and needs no PageIndex account.
• Anthropic or OpenAI and the library comparison (optional). The comparison in section 11 runs a separate Claude Code (or Codex, if you choose it). The claims from your draft and the page text it reads go to Anthropic (or OpenAI), on your own plan, after you have seen an estimate and said yes. The quiet background test of a second library uses no AI model at all.
• Trove (optional). Only the sources you choose to upload to your Trove library are stored there.
• Your keys. When you save your Gemini key through the plugin's settings, Claude Code stores it in your computer's secure keychain (or a protected credentials file), never in a plain text file in your project. The plugin never prints it or writes it into your research folder.
• Nothing else. The plugin writes only inside your research folder and its own data folder. It does not send your files anywhere else.

9. Troubleshooting

python3 -m pip install python-docx lxml pdfplumber pymupdf jsonschema

Still stuck? Report the problem at github.com/yodem/academic-writer/issues and include the output of /academic-writer:health (it contains no keys).

10. Updating and uninstalling

Updating

Type these in a terminal (or with /plugin in Claude Code), then restart Claude Code:

claude plugin marketplace update yodem
claude plugin update academic-writer@yodem

Updating keeps your profile, drafts and voice data.

Uninstalling

claude plugin uninstall academic-writer@yodem --keep-data

11. Choosing a library (optional)

You can skip this section. Unless you choose otherwise, your books are read from Trove, as before, and nothing here changes how the plugin works for you.

The choices

PageIndex is a second library that keeps a short outline of every book, with a few lines on each section, so Claude can go straight to the likely page. For each article you choose where its books are read from, and you can change your mind later with /academic-writer:update-tools.

Adding PageIndex

Setup, init and update-tools offer two ways, explain each in plain words, and ask before doing anything:

1. The plugin's own helper. A small program that the plugin installs in its own data folder, not in your system. The basic helper is about 100 MB and needs Python 3.9 or newer; it prepares books that have a table of contents. A larger helper (about 500 MB, Python 3.10 or newer and, on a Mac, the pango add-on) can also prepare a book that has no table of contents. The plugin shows you the plan and the size, installs only after you say yes, never installs Python for you, and can remove the helper again.
2. Your own PageIndex. If you already run PageIndex yourself, for example on a server, you type its command into the plugin's pageindex_command setting (type /plugin, open Installed, choose academic-writer, then Configure). A command you set yourself always wins over the built-in helper. Never put a password in that setting.

/academic-writer:update-tools

Say you want PageIndex and choose Set it up on this computer. Then run /academic-writer:health to see which helper is in use and that it is ready.

Preparing your books

A book must be prepared once before PageIndex can read it. When you add a book with /academic-writer:ingest or /academic-writer:ingest-book, the plugin writes it to Trove first, checks it, and then offers to prepare it for PageIndex too. It uses the same table of contents and the same page numbers, so a citation means the same page in both libraries. For each book it tells you how much text would be sent to Google for the summaries, and you choose: Gemini summaries, the free option that sends nothing, or not now. A problem here never undoes the Trove upload.

You can also add a reading to a book you already have, and prepare the books already in Trove in one go (a "backfill"). Both are safe to repeat: summaries already paid for are reused, and Trove is never changed.

Measuring the libraries

Every lookup and every citation check is noted on your computer, in .academic-helper/retrieval.jsonl: how long it took, an estimate of how much text came back, and the citation checker's verdict. Ask Claude to "show me the library report" for a plain-language comparison on your real articles: speed, failures, how often the two libraries return the same page, how often the citation checker passes, the size of the text returned and the cost of any preparation or comparison runs. The size figures are estimates, not a bill. Nothing in that log is uploaded.

The blind comparison: judge it yourself

/academic-writer:library-eval answers a sharper question on your own sources: for the claims in this article, which library finds the better pages?

1. Plan. The plugin picks claims from one of your drafts and tells you how many helper runs this needs and what they are likely to cost. Nothing is spent until you say yes.
2. Find. For each claim, a separate Claude (or Codex) looks up the supporting pages in each library, one library at a time.
3. Judge. You open one private page that works offline, in Hebrew and English. For each claim it shows two answers, "A" and "B", in random order, with no library names. You choose Better: A, Better: B, Same or Neither, and may add a note. You can stop and come back, and then save your judgments as a file.
4. Reveal. The plugin imports your judgments and only then reveals which library was which, with how many pairs each won, a confidence range, the time, tokens and cost of each, and how often each found the page the citation checker had confirmed.

Full details, the report explained line by line and the known limits are in docs/library-routes.md in the project repository.