src

Academic Writer

Academic Writer is a plugin (an add-on) for Claude Code that helps humanities researchers write scholarly articles in Hebrew or English. You talk with Claude in plain language. The plugin takes you from a rough topic to a footnoted Word file: it reads the sources you choose, helps you settle a thesis and an outline, drafts in your own style, checks every citation against your sources, and then folds your Word comments back into the text.

See it in action on the Academic Writer site (English and Hebrew). A fuller, step-by-step version of this page is the Academic Writer guide, which you can read online with no install. It also ships with the plugin as an offline guide: after installing, type /academic-writer:intro to open it in your browser.

What you need

Also useful:

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

Install

You install once. About 15 minutes if you have never used Claude Code. Each step says what you should see.

Step 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). Subscribe or sign in at claude.ai.
2. Open the Terminal app (a window where you type commands instead of clicking). Mac: press Cmd+Space, type Terminal, press Enter. Windows: Start menu, type PowerShell, press Enter. Linux: Ctrl+Alt+T on most systems.
3. Paste this line and press Enter (Windows PowerShell: irm https://claude.ai/install.ps1 | iex). It shows no progress for a minute; that is normal.

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

1. Make a folder for your research (for example Academic inside Documents). In Terminal type cd (with a space), drag that folder into the window, press Enter, type claude and press Enter.
2. The first time, your web browser opens so you can sign in. Sign in, then 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 and open a new Terminal window, then try step 4 again. Prefer an app? Anthropic also offers a Claude desktop app with Claude Code; the website steps for it are at yodem.github.io/academic-writer.

Step B. Add the plugin. In the prompt box, type these two lines, one at a time, pressing Enter after each:

/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 a list of plugins; this one is called yodem). The second installs it. Each prints a short confirmation. If the first one says it cannot find the marketplace, check the line is typed exactly as above and try again; if it still fails, copy the message and paste it to Claude. (A line starting with / is typed in Claude Code's prompt box, not in Terminal.)

Step C. Restart. Type /exit and press Enter, then type claude again in the same folder, so the new commands appear.

Step D. Check it. Type /plugin, open the Installed tab with the arrow keys, and look for academic-writer. If it is missing, repeat Step B. Then go to First steps below.

If you prefer to add the plugin from Terminal instead of the prompt box, the same two steps are:

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

First steps

Run these inside Claude Code, started in your research folder (not your main home folder).

1. /academic-writer:intro opens the full guide in your web browser.
2. /academic-writer:setup is a short guided conversation, one question at a time, about ten minutes. It asks your field, article language and citation style; checks the tools the plugin needs and asks your permission before installing anything; walks you through getting and safely storing a free Gemini key, then tests it; and writes one short sample paragraph. After you store the key, setup asks you to quit Claude Code completely, open it again in the same folder, type /academic-writer:setup and choose Check my Gemini key; your answers are saved.
3. /academic-writer:init (recommended) builds your full profile. First copy 5 to 10 of your published articles (PDF or Word) into the past-articles folder inside your research folder (setup created it). Init reads them, shows you what it learned about your style so you can correct it, and helps you connect your source library.
4. /academic-writer:write starts your first article.

Running setup or init again later is safe: they update your profile and never erase it.

How writing an article works

/academic-writer:write has a conversation part, where you make every decision about the argument, and a drafting part the plugin runs on its own.

1. Your voice. Before anything else, write checks that your voice profile (the examples and writing habits drafts should follow) exists. If it does not, it asks whether to build it first with /academic-writer:voice (about 10 minutes, using 3 or more of your past articles) or to write in a neutral scholarly voice for now.
2. Topic and language. Say what you want to write about and in which language.
3. Sources. You pick the sources for this article from the ones you made available.
4. Your thesis. You state the thesis in your own words; the plugin records it exactly as you wrote it.
5. Verified evidence. The plugin reads the chosen sources and keeps only passages whose quotations match the source word for word. These are the only passages the draft may quote or cite.
6. Outline. Together you shape the sections. You approve each section's claim; nothing is drafted until every claim is approved.
7. Drafting. Gemini drafts the article from the approved outline, section by section, in your style, with the introduction and conclusion written last. Automatic checks reject any draft that cites a source not on your list, quotes text that is not in the verified passages, or breaks your style rules.
8. Citation check. Claude then checks every paragraph's citations against your sources. A paragraph that fails is rewritten. If it still fails after the allowed number of attempts, it is marked [NEEDS REVIEW] and named in the final report so you know exactly what to check.
9. Word file. You get a .docx with real Word footnotes. Claude tells you where it saved it.
10. Your comments. Open it in Word, add comments or tracked changes wherever you want something changed, save and close.
11. Revise. Run /academic-writer:revise. It reads your comments and tracked changes, groups them, asks you to confirm each group, updates the text and makes a new Word file. With your agreement, it also learns from your rewrites so later drafts sound more like you. Repeat steps 10 and 11 as often as you like.

Before you submit, run /academic-writer:proofread for a typo, language and editorial pass (the original is never changed; you get a corrected copy, a report and an editorial memo), and /academic-writer:review for a scorecard of the article's structure, argument and citations.

Commands

Type any of these in Claude Code. You can also describe what you want in your own words ("proofread my article"), and Claude picks the right command for most requests. Setup, init and voice run only when you type them, because they change your settings.

A few more things the plugin can do have no command of their own. Ask for them in plain words:

• Learn from new papers or your corrections: "I added new papers to past-articles, update my voice."
• Follow-on materials: "Make a conference talk outline (or a journal abstract, or a chapter proposal) from this article."
• Change your field of study: "Change my field in my profile to ..."
• Connect or disconnect Trove or NotebookLM: "Turn on Trove in my profile."

Choosing a library (optional)

Your books are read from Trove unless you choose otherwise. Nothing here changes how the plugin works for you today, and you can skip this whole section.

What the choices are. Each article project can read its books from Trove (the default), from PageIndex, or from both, where one library answers and the other is tested quietly in the background without ever changing, slowing or failing your result. 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. You choose per article, and you can change your mind with /academic-writer:update-tools.

Two ways to get PageIndex. Setup, init and update-tools offer both, in plain words, and ask before doing anything:

1. The plugin's own helper. The plugin sets up a small helper in its own data folder (not in your system). The basic helper is about 100 MB and needs Python 3.9 or newer; a larger one (about 500 MB, Python 3.10 or newer and, on a Mac, the pango library) can also prepare a book that has no table of contents. You can remove it again. The steps are below.
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 (/plugin, then Installed, then academic-writer, then Configure). A command you set yourself always wins over the built-in helper.

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, with the same table of contents and the same page numbers, so a citation means the same page in both. You can also add a reading to a book you already have, and prepare the books already in Trove (a "backfill") in one go. For each preparation the plugin tells you in advance how much text would be sent to Google and asks you; the free choice sends nothing (see Privacy).

What is measured. Every lookup and every citation check is logged on your computer in .academic-helper/retrieval.jsonl, with the time it took, an estimate of how many tokens of text it returned, and the citation checker's verdict. aw library report turns that into a comparison on your real articles: speed, failures, how often the two libraries return the same page, the citation checker's pass rate, tokens, and the cost of any preparation and evaluation runs. Token figures from the log are estimates, not a bill.

Judge it yourself: a blind evaluation. /academic-writer:library-eval picks claims from one of your drafts, has a separate Claude (or Codex) look up the supporting pages in each library, and shows you the two answers side by side as "A" and "B" in random order on a private page that works offline, in Hebrew and English. You mark each pair better A, better B, same or neither, with a note. Only after you finish does the plugin reveal which library was which, with win rates, a confidence range, time, cost and how often each found the page the citation checker had confirmed. With too few pairs it tells you it is only a first look.

Install steps for the built-in helper. Run these in Claude Code, started in your research folder, and answer the questions it asks:

1. Type /academic-writer:update-tools (or /academic-writer:setup, the first time) and say you want PageIndex. Among the choices it offers, pick Set it up on this computer.
2. Read the plan it shows (which size, how much disk space, where it goes) and say yes if you want it. Nothing is installed before that.
3. If it says your Python is too old or pango is missing for the larger helper, you can accept the basic helper or follow the short steps it gives for your system. It never installs Python for you.
4. Type /academic-writer:health to confirm it is ready. It shows which helper is in use.

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

Your Gemini key

What it is. Gemini is Google's AI model. In this version, the plugin's own drafting tool (aw) sends every drafting, evidence-extraction (used by write and research), synthesis, editing, proofreading, OCR and voice-analysis step to Gemini, while Claude runs the conversation and checks every citation.

Is it optional? Setup lets you answer "Not now", and nothing is then sent to Google. Planning and review still work, but the steps listed above need the key, so in practice you need one to write, research, proofread or OCR. Setup tells you this when you choose.

Cost. Google's free tier is enough for normal use, and creating a key normally needs no credit card. Get one at aistudio.google.com/apikey; it starts with AIza.

Where to keep it. Never paste the key into the Claude chat: the conversation is saved, so a key there could be read later. Use one of these:

1. Plugin settings (recommended). In Claude Code, type /plugin, open Installed, choose academic-writer, then Configure, and paste the key into google_api_key. Claude Code keeps it in your computer's keychain (on Linux, a protected credentials file), not in a plain settings file. At the start of each session the plugin passes it on to its tools, but only in a research folder that already has a profile (.academic-helper/profile.md), which setup creates.
2. An environment variable. Set GOOGLE_API_KEY in your shell profile (macOS/Linux) or as a user environment variable (Windows). This also works for other tools on your computer. /academic-writer:setup shows the exact steps for your system.

Either way, the key is picked up only when a new Claude Code session starts. The plugin reads nothing else: a .academic-helper/secrets.json file is not used.

Privacy

• Anthropic (Claude). Your conversation with Claude, and the text Claude reads to help you (your drafts, the source passages it checks), go to Anthropic, as with any use of Claude Code.
• Google (Gemini). With a Gemini key, the text being drafted, edited, proofread or summarised, the source passages it relies on, and any scanned pages you ask it to read are sent to Google. 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 (Gemini) and PageIndex. If you prepare books for PageIndex and choose Gemini summaries, the text of each section of the book is sent to Google, with your Gemini key, so Gemini can write the short outline. The plugin tells you how much text, and asks first, every time. The free option (--summaries hints, offered alongside) sends nothing: it reuses the hints already written for Trove. The same Google terms as above apply. Nothing is ever sent to PageIndex Cloud: the plugin has no code for it and needs no PageIndex account.
• Anthropic (or OpenAI) and the blind evaluation. /academic-writer:library-eval runs a separate Claude Code (or Codex, if you choose it) to find supporting pages. 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 are stored there. If you use Trove, your voice profile is also synced there so it follows you between computers.
• Jev (advanced, off by default). Only if you enter the optional jev_api_key setting, the question and context at a few decision points are also sent to the Jev service. In this version its answers are only logged and never change your results. Most users should leave it empty.
• Your keys. Saved through the plugin settings, the key is kept in your keychain. The plugin never prints it or writes it into your research folder.

What stays on your computer, and where:

Folders whose names start with a dot are hidden by default. On a Mac, press Cmd+Shift+. in Finder; on Windows, choose View, then Show, then Hidden items in File Explorer.

Uninstalling deletes the plugin's data folder, including your voice data, unless you keep it:

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

Your research folders, drafts and Word files are never touched by uninstalling.

Troubleshooting

Start with /academic-writer:health. It checks your profile, key, tools and sources, and tells you in plain words what to fix. Its report contains no keys, so you can share it when asking for help.

• The /academic-writer: commands do not appear. Quit Claude Code completely and open it again. Then type /plugin and check that academic-writer is listed and enabled. If not, repeat the two install lines.
• "missing Google API key" or "API key not valid". Run /academic-writer:setup again and choose to check the Gemini key. After saving a key, start a new Claude Code session in your research folder.
• "No profile found". Make sure you started Claude Code inside your research folder. In a new folder, run /academic-writer:setup first.
• Write asks about your voice profile. Choose "Build my voice first" and run /academic-writer:voice, or continue without it and build it later.
• The Word file is not created, or a "missing Python package" message. Run /academic-writer:setup; it offers to install the add-ons. To do it yourself: python3 -m pip install --user python-docx lxml pdfplumber pymupdf jsonschema.
• Proofreading a Word file fails. The proofread command converts .docx files with pandoc, a free document converter, which setup does not install. Install it from pandoc.org/installing.html, or proofread a Markdown copy.
• The PageIndex helper will not install, or aw library status says PageIndex is not reachable. Run /academic-writer:health; it names the cause (Python older than 3.10 for the larger helper, a missing pango library on a Mac, no network, or an old command in pageindex_command). The basic helper works with Python 3.9. Trove keeps working either way.
• Hebrew looks reversed in the Claude Code window. That is only the display; the Word file is laid out right to left.

Still stuck? Open an issue at github.com/yodem/academic-writer/issues and include the output of /academic-writer:health.

Updating

In a terminal (or through /plugin in Claude Code), then restart Claude Code:

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

Refreshing the marketplace alone does not update an installed plugin; run both lines. Updating keeps your profile, drafts and voice data. See CHANGELOG.md for what changed.

For contributors

Source lives in src/. Never edit plugins/ directly: npm run build generates it from src/ and manifests/, and the output is committed.

npm run build                           # assemble plugins/academic-writer/ from src/
npm run build:hooks                     # rebuild only the TypeScript hooks
npm run typecheck                       # str