Hello

This guide is for you if you use the Claude app and have never opened a terminal. Each step is one small action, and each one shows roughly what you should see.

A terminal is a window where you give your computer instructions by typing short lines called commands instead of clicking. Step 1 shows you how to open it.

What you will end up with: Claude Code, set up with ai-architecture, a free add-on for it. ai-architecture adds commands that turn a bigger job into a written plan, carry it out and review the result. Researchers can add a second add-on afterwards, Provenote, which helps turn papers into notes and checks every quote in your notes against the page you cite.

The guide has three parts:

  1. The basics (steps 1 to 4): the terminal, Git, Python and Claude Code itself.
  2. ai-architecture (steps 5 to 8): the main setup.
  3. Provenote (steps 9 to 13): an optional chapter for research work.

Before you start, you need:

  • A paid Claude plan that includes Claude Code: Pro, Max, Team or Enterprise (or an Anthropic Console account). The free claude.ai plan does not include Claude Code. Plans and prices change, so this guide quotes none. The official page: https://docs.claude.com/en/docs/claude-code/setup
  • A Mac, a Windows PC or a Linux PC with an internet connection, on which you are allowed to install programs.
  • On Windows, a choice between two routes, explained in step 1. ai-architecture's own page says it was built and used on one Linux machine, that other operating systems are untested, and that its tools need bash and Python 3. WSL (a small Linux system inside Windows) is the closest to that, so this guide's own advice is to use WSL for the ai-architecture part. The optional Provenote part (Part 3) is written for PowerShell instead, not for WSL.

Part 1 · The basics

Steps 1 to 4 get a terminal, Git, Python and Claude Code onto your computer, and sign you in. Everything after them builds on this.

Step 1: Open the terminal

Why: everything else in this guide happens in the terminal window.

Pick your computer:

I have a Mac

  1. Press Command + Space. A search bar appears.
  2. Type Terminal and press Return.
Open the terminal on a MacPress Command and Space, type Terminal, press Return. A white window opens with a line that ends in a percent sign.Open the terminal on a Mac1Press Command + SpaceCommand+Space2Type Terminal, press ReturnTerminal3A small window opensyou@Mac ~ %Yours shows your own name.The line ends with %Illustration, not a screenshot

I have a Windows PC

You have two routes. Pick one now; later steps tell you what changes. Open the route you chose:

Route A: WSL (click or tap to open)

This is the route the ai-architecture part of this guide is written for. WSL is a small Linux system that runs inside Windows. ai-architecture's own page says it was built and used on one Linux machine and that other operating systems are untested. WSL is the closest to that, which is this guide's own advice, not a promise from ai-architecture. So this route is not tested either. It needs Windows 10 version 2004 (build 19041) or later, or Windows 11.

  1. Click the Start button and type PowerShell. Right-click Windows PowerShell and choose Run as administrator. This opens PowerShell with administrator rights. If Windows asks "Do you want to allow this app to make changes?", choose Yes.
  2. Paste this line (Ctrl + V or a right-click) and press Enter. It installs WSL and the Ubuntu distribution of Linux.
In the terminal
wsl --install
  1. Then restart your computer.
  2. Click Start, type Ubuntu and open it. This window, called the Ubuntu window, is the terminal you use from now on. You can close the administrator PowerShell window: you only needed it for wsl --install. The first time, the Ubuntu window asks you to wait while files unpack. Then it asks you to create a user name and a password for this Linux system. When you type the password, usually nothing appears on the screen; type it and press Enter.

If you see help text after wsl --install instead, run wsl --list --online to see the list of distributions, then wsl --install -d <DistroName> with a name from that list.

From here on, Route A means: the Ubuntu window is your terminal. In steps 2 to 8 follow the parts of the Windows boxes marked Route A; they are the Linux instructions, repeated for you. Do not type them into PowerShell. Part 3 (Provenote) is not written for WSL; see the note at its start.

Route B: PowerShell only (click or tap to open)

This route skips ai-architecture. Skip WSL. You do steps 1 to 4 in PowerShell, skip steps 5 to 8 (ai-architecture) and go straight to step 9, Provenote after step 4. Read the box at the end of step 4 first: it explains a question Claude asks you in later steps.

  1. Click the Start button.
  2. Type PowerShell and press Enter.
Open the terminal on WindowsClick Start, type PowerShell, press Enter. A dark window opens with a line that starts with PS and ends in a greater-than sign.Open the terminal on Windows1Click the Start buttonThe Start button, at the bottom2Type PowerShell, press EnterPowerShell3A small window opensPS C:\Users\you>Yours shows your own name.The line ends with >Illustration, not a screenshot

I have a Linux PC

  1. Press Ctrl + Alt + T, or search for Terminal in your application menu.
  2. A terminal window opens.
Open the terminal on LinuxPress Control, Alt and T, or search for Terminal in your application menu. A terminal window opens with a line where you type.Open the terminal on Linux1Press Ctrl + Alt + TCtrl+Alt+T2Or search for TerminalTerminal3A small window opensyou@computerYours shows your own name.A cursor blinks where you typeIllustration, not a screenshot

You will use this window for the rest of the guide. The line where you type is called the prompt. It shows your own name, so it will not match the picture exactly.

Typing and pasting. In the normal terminal you type or paste one line at a time, then press Return (Mac) or Enter (Windows and Linux). Later, inside Claude Code, some boxes hold a longer message. Each of those boxes is one message: copy all of it, paste it once, press Enter once. To paste: Cmd + V on a Mac; Ctrl + V or a right-click in Windows PowerShell; Ctrl + Shift + V on Linux and in the Ubuntu window. To copy something out of the terminal, such as an error message, select it with the mouse and copy as usual (Cmd + C on a Mac, Ctrl + C on Windows, Ctrl + Shift + C on Linux). On Linux, plain Ctrl + C does not copy in the terminal.

Done when a window is open, its last line ends with % (Mac) or starts with PS (Windows, Route B), and a cursor blinks after it. On Linux and in the Ubuntu window (Windows, Route A) the line looks different on each computer; a blinking cursor is enough.

Stuck? → Ask for help

Step 2: Check your computer

Why: add-ons for Claude Code are downloaded from GitHub (a website where programs are shared), and that needs a small tool called Git. The add-ons' helper programs also run on Python. You may need to install them. Two quick checks, in the terminal window from step 1.

2a. Is Git there?

In the terminal
git --version
Example output of git --versionA terminal printing a Git version number.After you type git --version you see:git version 2.43.0Any version number means Git is there.Example: yours will differ a little

Done when a version number is printed (any number is fine).

Stuck? An error instead of a number: open No Git? below.

No Git? (click or tap to open)

I have a Mac

Install Git from https://git-scm.com/downloads. Then close the terminal window, open a new one (as in step 1), and run git --version again.

I have a Windows PC

Route A (WSL): in the Ubuntu window, install Git with this line, then run git --version again. sudo runs a line with administrator rights, so the first time you use it, it asks for the password you made in step 1. If it asks whether to continue, type y and press Enter.

In the terminal
sudo apt-get install git

Route B (PowerShell only): install Git from https://git-scm.com/downloads. The installer asks a lot of questions: keep the defaults and click Next each time. Then close the terminal window, open a new one (as in step 1), and run git --version again.

I have a Linux PC

On Linux, install Git from the terminal. Use the line for your system, then run git --version again. sudo runs a line with administrator rights, so the first time you use it, it asks for your own computer password. While you type it, usually nothing appears on the screen; type it and press Enter. If a line asks whether to continue, type y and press Enter.

Debian or Ubuntu:

In the terminal
sudo apt-get install git

Fedora:

In the terminal
sudo dnf install git

Arch:

In the terminal
sudo pacman -S git

Still no version number in the new window? Copy the exact text and ask for help.

2b. Is Python there? The helper programs run on Python, a free tool. You need version 3.11 or newer.

I have a Mac or a Linux PC

In the terminal
python3 --version

I have a Windows PC

Route A (WSL): in the Ubuntu window, run the Mac and Linux line instead:

In the terminal
python3 --version

Microsoft's page does not say which Ubuntu version wsl --install gives you, so check the number. If it is below 3.11, open Python missing or too old? below.

Route B (PowerShell only):

In the terminal
py -3 --version

If py -3 is not recognised, try python --version. On Windows the program is usually called py -3 or python; this guide does not use python3 there.

Example output of the Python version checkA terminal printing a Python version number.After you type the Python check you see:Python 3.12.3Python 3.11 or newer is needed.Mac or Linux: python3 --versionWindows: py -3 --versionExample: yours will differ a little

Done when the number is 3.11 or higher.

Stuck? No number, or a number below 3.11: open Python missing or too old? below.

Python missing or too old? (click or tap to open)

I have a Mac

Install Python from the official page: macOS. Then close the terminal window, open a new one, and check again.

I have a Windows PC

Route A (WSL): do not use the Windows installer. In the Ubuntu window, use this line instead (the same Debian or Ubuntu line as in the Linux box), then check again. If sudo asks for a password, it is the one you made in step 1; usually nothing appears on the screen while you type it. sudo runs the line with administrator rights. If it asks whether to continue, type y and press Enter.

In the terminal
sudo apt update && sudo apt install python3

Ubuntu 22.04 keeps Python 3.10, which is below 3.11, and cannot reach 3.11 this way. If python3 --version still shows 3.10 after this line, skip the health check in step 7.

Route B (PowerShell only): python.org now leads with the Python install manager. On the Windows page download the Python install manager, open the file and click Install. Then close the PowerShell window, open a new one, and install Python with this line (the first time you run python or py, it also offers to install the latest version):

In the terminal
py install 3.11

Python may prompt you to add a folder to your PATH (the list of places the terminal looks for programs). The Python documentation calls this optional. Then check:

In the terminal
python --version

If python is not found, open Windows Settings, search for Manage app execution aliases and check the Python entries there. Still not found: ask for help.

I have a Linux PC

Install Python 3 from the terminal. Fedora already has Python 3, so run python3 --version first. Use the line for your system, then check again. sudo runs a line with administrator rights. If it asks for your own computer password, usually nothing appears on the screen while you type it; type it and press Enter. If a line asks whether to continue, type y and press Enter.

Debian or Ubuntu:

In the terminal
sudo apt update && sudo apt install python3

Ubuntu 22.04 keeps Python 3.10, which is below 3.11, and cannot reach 3.11 this way. If python3 --version still shows 3.10 after this line, skip the health check in step 7.

Fedora:

In the terminal
sudo dnf install python3

Arch:

In the terminal
sudo pacman -S python

Step 3: Install Claude Code

Why: Claude Code is the program that runs the add-ons. It comes from the same company as the Claude app, and you sign in with the same account.

The official install page is the authority: https://docs.claude.com/en/docs/claude-code/setup. If a line below differs from it, follow the official page.

The install lines that end in | bash download the installer and run it. Only use lines like this from an official page.

I have a Mac

Paste this line into Terminal and press Return. The installer shows no progress while it downloads, so leave the window open and wait until you can type again. It may end with a message like "Claude Code successfully installed!".

From the official setup page: https://docs.claude.com/en/docs/claude-code/setup

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

If the installer's last lines mention PATH and show a line to run, copy that exact line, paste it, and press Return.

Now close the Terminal window completely and open a new one (as in step 1), so your computer notices the new program. Then check that it is there:

In the terminal
claude --version

I have a Windows PC

Route A (WSL): use the Ubuntu window from step 1, not PowerShell. The official page says to install and launch claude inside the WSL terminal. Paste this line and press Enter. The installer shows no progress while it downloads, so leave the window open and wait until you can type again. WSL does not need Git for Windows.

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

If you see curl: command not found, run sudo apt install curl and then paste the line again.

If the installer's last lines mention PATH and show a line to run, copy that exact line, paste it, and press Enter. Then close the Ubuntu window, open it again from the Start menu, and check that it is there:

In the terminal
claude --version

Route B (PowerShell only):

  1. Open the official page above and choose its Windows instructions for PowerShell. This guide does not repeat the Windows install line; use the one on that page.
  2. In the PowerShell window from step 1, paste that line and press Enter. The installer shows no progress while it downloads, so leave the window open and wait until you can type again.
  3. Close every PowerShell window and open a new one (as in step 1). Then check that it is there:
In the terminal
claude --version

I have a Linux PC

Paste this line into the terminal (Ctrl + Shift + V) and press Enter. The installer shows no progress while it downloads, so leave the window open and wait until you can type again. It may end with a message like "Claude Code successfully installed!".

The official page lists Ubuntu 20.04 or newer and Debian 10 or newer. Fedora and Arch are not on its list.

From the official setup page: https://docs.claude.com/en/docs/claude-code/setup

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

On Debian or Ubuntu, if you see curl: command not found, run sudo apt install curl and then paste the line again.

If the installer's last lines mention PATH and show a line to run, copy that exact line, paste it, and press Enter.

Now close the terminal window completely and open a new one (as in step 1), so your computer notices the new program. Then check that it is there:

In the terminal
claude --version

You should see: a version number, like this.

Example output of claude --versionA terminal printing the Claude Code version number.After you type claude --version you see:2.1.314 (Claude Code)A version number means it worked.Example: yours will differ a little

Done when a version number is printed. Yours may differ, and that is fine.

Stuck? "command not found" or any other error → Ask for help. Do not run the installer again and again.

Step 4: Sign in

Why: Claude Code needs to know which Claude account to use. On Windows, Route A, do this in the Ubuntu window.

Claude Code works in the folder you start it in. So first make an empty folder for it and go into that folder. Type these lines one at a time, pressing Return/Enter after each:

In the terminal
mkdir claude-start
In the terminal
cd claude-start

Now start Claude Code:

In the terminal
claude

You are now inside Claude Code. It runs in the same window, but it is a different place from the normal terminal. The picture shows the difference; keep it in mind for the rest of the guide:

Two places you typeA normal terminal, where you type commands such as cd and claude, and the inside of Claude Code, where you type messages and slash commands. Type claude to go in and /exit to come out.Two places you typeKnow which one you are in.A Normal terminalyou@Mac ~ %Windows shows PS C:\Users\you>Here you type commands, like cd and claude.type claude/exitB Inside Claude Code>Here you type messages to Claude,and /commands. cd does not work here.Illustration, not a screenshot

The first time, Claude Code asks a few setup questions. Use the arrow keys to move and Enter to choose; the mouse does nothing here. In the order they appear:

  • Setup questions, for example a colour style. Any choice is fine; if you are unsure, press Enter on the first one.
  • Login. Choose the option for a Claude account with a subscription (Pro, Max, Team or Enterprise). A web browser may open: sign in there with your Claude account, then come back to the terminal window.
  • Trust this folder? The question names the empty folder you just made, claude-start: choose Yes. Claude Code reads files in that folder without asking, and asks before it changes files or runs most commands (see the box below).

You should see: a box where you can type a message to Claude.

Ready for your messageClaude Code with a box at the bottom marked with a greater-than sign, where you can type a message.Ready for your message>↑ the box where you type a messageIllustration, not a screenshot

Done when Claude Code shows a box where you can type a message.

Stuck? A sign-in loop or a message about your plan → Ask for help

Windows, Route B: steps 5 to 8 are not for you. Go on at step 9, after the box below, which explains a question Claude asks in later steps.

Part 2 · ai-architecture

This is the main setup. ai-architecture is an add-on for Claude Code, kept on GitHub. It adds commands that start with /ai-architecture:, for example one that writes a plan for a bigger job and one that checks your setup.

  • Written for: ai-architecture v0.4.2-preview, read but not run by this guide's author (on GitHub). Its own page says it was built and used on one Linux machine and that other operating systems are untested. This guide's own advice on Windows is WSL, the closest to that. So this part is untested as a fresh install on any system. The line in step 5 installs the newest version, which may be newer than v0.4.2-preview.
  • Only here for Provenote? Skip to Part 3, step 9.
  • Windows, Route B (PowerShell only): skip to step 9.

Step 5: Add ai-architecture

Why: Claude Code does not come with ai-architecture. You add it once, like installing an app. A plugin is an add-on for Claude Code. Here the "marketplace" is just a list of add-ons kept on GitHub; nothing is bought.

You are still inside Claude Code from step 4. You enter two lines, one at a time.

5a. Tell Claude Code where ai-architecture lives. Paste this line and press Return/Enter.

Inside Claude Code
/plugin marketplace add nik110403/ai-architecture

5b. Install it. Wait until you can type again, then paste this line and press Return/Enter.

Inside Claude Code
/plugin install ai-architecture@ai-architecture

5c. Restart Claude Code. Leave it first: type /exit and press Enter. You are back in the normal terminal. Then type claude and press Enter again.

This step does not show yet whether ai-architecture was added, and it does not need to: step 6 is the real test. If a message after 5a or 5b says that something failed or was not found, copy it and ask for help.

Done when you have entered both lines (5a and 5b) and restarted Claude Code.

Stuck? An error after 5a or 5b → Ask for help

Step 6: Check Claude sees it

Why: to make sure ai-architecture was really added, before you rely on it. This check is this guide's own; ai-architecture does not document one.

Inside Claude Code, type this message and press Return/Enter. The message asks for no tool, so no permission box should appear. If one does (the box from step 4), press Esc, not Yes.

Inside Claude Code
List the ai-architecture commands you can see. Do not run any tool yet.

You should see: a list of commands that start with /ai-architecture:.

Done when the list includes /ai-architecture:plan, /ai-architecture:execute, /ai-architecture:review, /ai-architecture:checkpoint, /ai-architecture:research and /ai-architecture:health.

Stuck? Nothing listed → type /exit, then claude again (as in step 5c). Still nothing → Ask for help

Step 7: Run the health check

Why: ai-architecture has a built-in health check. It runs the collection's own offline checks and reports exact results. It needs Python 3.11 or newer, which is what step 2 asked for.

Type this line and press Return/Enter.

Inside Claude Code
/ai-architecture:health

Claude asks for permission to run two Python commands. A box appears with the question "Do you want to proceed?". Read it, as in step 4: if it shows the Python commands for this check, press Enter on Yes; if it shows something else, press Esc. These checks look at ai-architecture itself, not at your own files.

You should see: a line that starts with PASS: and no line that starts with FAIL:.

Done when a line that starts with PASS: appears and no line says FAIL or FAILED.

Stuck? A line that starts with FAIL:, or FAILED in the test output → do not install anything. Copy the whole output and ask for help. An error that mentions Python or its version, or no PASS: line → your Python may be too old. Open Python missing or too old? in step 2, install a newer Python there, close the terminal window, open a new one, go into your folder (cd claude-start), start claude again and repeat this check. Still failing → Ask for help

On Ubuntu 22.04 (Python 3.10) you cannot reach 3.11 that way. If python3 --version still shows 3.10 after the install line, skip this check; the list in step 6 still shows whether Claude sees ai-architecture.

This check does not show that Claude finds ai-architecture by itself; the list in step 6 does that.

Step 8: Make your first plan

Why: to use ai-architecture once, so you can see what it gives you.

Type this line and press Return/Enter.

Inside Claude Code
/ai-architecture:plan

If Claude asks what to plan, answer in your own words. If it starts on something else, press Esc and type the example below instead. Here is one example. It is this guide's own sentence, not one from ai-architecture:

Inside Claude Code
I want to organise the notes for a small research project into folders by topic. Make a plan only. Do not create or move any files.

You should see: a plan. ai-architecture's own page says a plan has an outcome, non-goals, acceptance criteria, items, checks, blockers and a next step you can act on. Claude's wording and layout will differ.

Done when Claude shows a written plan with those parts. You do not have to carry the plan out.

Stuck? No plan, or an error → Ask for help

Good to know

  • More commands. The other commands are /ai-architecture:execute, /ai-architecture:review, /ai-architecture:checkpoint and /ai-architecture:research. Using them does not give Claude any extra permissions.
  • Settings. Do not replace your own settings or rules with anything from this collection. If you want one of its rules, copy just that rule in yourself, next to what you already have.
  • Blocking hooks. A second, optional plugin, ai-architecture-gates, adds checks that can stop Claude from acting, for example from running a command. Skip it for now.
How do I remove ai-architecture? (click or tap to open)

Enter these two lines inside Claude Code, one at a time.

Inside Claude Code
/plugin uninstall ai-architecture@ai-architecture
Inside Claude Code
/plugin marketplace remove ai-architecture

You are done with the main setup. The rest is for research work. If that is not you, you can stop here.

Part 3 · Provenote (optional, for research work)

You only need this part if you work with papers and notes. It does not depend on Part 2, so you can do it without ai-architecture. After steps 1 to 4, Windows Route B readers continue here.

Windows with WSL (Route A): Part 3 is not written for WSL yet. Its folder steps use File Explorer and dragging folders into the terminal, and this guide has no WSL version of them. You have two choices: stop after Part 2, or do Part 3 from Windows itself. For the second, do steps 1 to 4 the Route B way (PowerShell, Git, Python and Claude Code installed in Windows, as Route B describes), then follow Part 3 in PowerShell. You can always ask for help.

What you will end up with: Provenote, a free add-on for Claude Code. It helps you turn papers into notes, and it checks every quote in your notes against the page you cite.

What Provenote doesA PDF becomes a text copy. Your notes quote that text copy. Each quote is then checked against the page it cites, using the text copy.What Provenote doesIt checks your quotes against the source.Your PDFThe paper you are readingA text copyPlain text,page by page“Your notesThe quotes youwant to useEach quote is checkedAre these words on that page?It checks that the words are on the page.You still judge what they mean.Both arrows meet: the check comparesyour notes with the text copy.

Step 9: Add Provenote

Why: Claude Code does not come with Provenote. You add it once, like installing an app: two lines, then a restart. A plugin is an add-on for Claude Code; the "marketplace" is just a list of add-ons kept on GitHub, and nothing is bought.

You are inside Claude Code, from step 4 (or from step 8 if you did Part 2). If you closed the window since, open the terminal as in step 1, go into your folder (cd claude-start) and type claude. You enter two lines, one at a time.

9a. Tell Claude Code where Provenote lives. Paste this line and press Return/Enter.

Inside Claude Code
/plugin marketplace add nik110403/provenote

9b. Install it. Wait until you can type again, then paste this line and press Return/Enter.

Inside Claude Code
/plugin install provenote@provenote

9c. Restart Claude Code. Leave it first: type /exit and press Enter. You are back in the normal terminal, where the line ends in % (Mac) or starts with PS (Windows, Route B), or looks as it did in step 1 (Linux or Ubuntu). Then type claude and press Enter again.

This step does not show yet whether Provenote was added, and it does not need to: step 10 is the real test. If a message after 9a or 9b says that something failed or was not found, copy it and ask for help.

Done when you have entered both lines (9a and 9b) and restarted Claude Code.

Stuck? An error after 9a or 9b → Ask for help

Step 10: Check Claude sees Provenote

Why: to make sure Provenote was really added, before you rely on it.

Inside Claude Code, type this message and press Return/Enter. The message asks for no tool, so no permission box should appear. If one does (the box from step 4), press Esc, not Yes.

Inside Claude Code
List the Provenote skills you can see. Do not run any tool yet.

You should see: a list of Provenote skills. A skill is a set of instructions Claude follows for one kind of job.

Claude lists the Provenote skillsA short reply from Claude: a list of skill names such as new-research-project, literature-search and pdf-to-markdown.Claude lists the Provenote skillsyouSkills such as:new-research-projectliterature-searchpdf-to-markdownliterature-notesreview-against-notes… and moreIllustration: your list may be worded differently

Done when the list includes names like new-research-project, literature-search, pdf-to-markdown, literature-notes, review-against-notes, paper-build, analysis-pipeline and tribunal.

Stuck? No Provenote skills listed → type /exit, then claude again (as in step 9c). Still nothing → Ask for help

This only shows that Claude can see Provenote. The next steps show that its tools run.

Step 11: Get the example folder

Why: to watch Provenote catch a fake quote, you need the example folder. It holds two real papers and two sets of notes, and one note has a quote made up on purpose.

First leave Claude Code if you are inside it: type /exit and press Enter.

11a. Download it. In your web browser, open the Provenote GitHub page. Click the green Code button, then Download ZIP. A ZIP file is a folder packed into one file; unzipping unpacks it. The file is called provenote-main.zip and usually lands in your Downloads folder.

11b. Unzip it. You do this in your file window: it is called Finder on a Mac and File Explorer on Windows. On Linux, use your file manager.

I have a Mac

  1. Open Finder and click Downloads in the left-hand list.
  2. Double-click provenote-main.zip. A folder called provenote-main appears next to it. (Some browsers have already unzipped it for you; then you only need to find the folder.)

I have a Windows PC

  1. Open File Explorer and click Downloads in the left-hand list.
  2. Do not just double-click the ZIP: that only lets you peek inside. Right-click provenote-main.zip and choose Extract All…, then click Extract.
  3. A folder opens. Windows may have made a provenote-main folder inside another provenote-main folder. Open them until you see the folders docs and examples directly inside. That is the folder this guide calls provenote-main.

I have a Linux PC

  1. Open your file manager and click Downloads.
  2. Double-click provenote-main.zip, or right-click it and choose Extract. A folder called provenote-main appears. (Some browsers have already unzipped it for you; then you only need to find the folder.)

Inside it, the folder examples/basic is the one you need.

Download the ZIP, then find the example folderOn the GitHub page the green Code button opens a menu with Download ZIP. After unzipping you have a folder provenote-main that contains examples, which contains basic.Download, unzip, find the folder1On GitHub: Code, then Download ZIP<> Code ▾Download ZIP← the green Code button2Unzip it. You get these folders:provenote-mainexamplesbasicused in step 8On Windows there may be a secondprovenote-main inside the first.Illustration, not a screenshot

Done when you can open provenote-main, then examples, then basic, and you see folders such as 00_admin and 01_notes.

Stuck? → Ask for help

Step 12: Run the quote checker

Why: to watch Provenote catch a fake quote.

12a. Go to the example folder in the terminal. You need the normal terminal for this, where the line ends in % (Mac) or starts with PS (Windows, Route B), or looks as it did in step 1 (Linux or Ubuntu). If you are still inside Claude Code, type /exit first, or the cd ends up in the chat. Type cd (the letters c, d and a space). In your file window, open provenote-main, then examples, and drag the basic folder icon into the terminal window. This writes out the folder's path, its address on your computer. Press Return/Enter.

Done when the line you can type on now mentions basic.

12b. Start Claude Code in that folder.

In the terminal
claude

If it asks whether you trust this folder, choose Yes.

12c. Ask Claude to run the checker. The message below is long on purpose: it tells Claude to use the checker installed in step 9 and to leave the copy in the download alone. The box is one message: copy all of it, paste it once, and press Enter once. Claude Code may show the paste shortened, as something like [Pasted text]; that is fine. Claude will probably ask "Do you want to proceed?" before running things. Read it, as in step 4: it should show the installed helper running --strict on the notes folders. If it does, press Enter on Yes; if not, press Esc.

Inside Claude Code
Use the installed Provenote plugin's verify-quotes helper, not any copy inside the downloaded
Provenote folder (neither examples/basic nor ../../plugins/provenote/bin). The helper path
must be under Claude Code's plugin install location. If it is inside the downloaded folder, stop
and tell me instead of running it.
First show me the full path of the helper you are using. Then run it with --strict on the
files in 01_notes/lit/. Then run it with --strict on the files in 01_notes/negative/.
Show me the complete output of both runs and each exit code.

You should see, in two parts. First, 14 lines that start with PASS: every quote was found. The exit code Claude shows is 0, which means "no problems".

Example output: quote check passesLines starting with PASS, one for each quote that was found. Three of the 14 are shown.Part of Claude’s answer, shortened:PASS kireyev2026pricebench.md:  quote 1 (p. 1)PASS kireyev2026pricebench.md:  quote 3 (p. 4)…PASS lei2023financial.md:  quote 6 (p. 11)Run 1 of 2: every line starts with PASS.You will see 14 PASS lines in all.Example: what yours should roughly look like

Second, exactly one line that starts with FAIL, and an exit code of 1. That failure is expected. One note contains an invented quote on purpose, and the check is there to catch it.

Example output: one expected FAIL lineOne line starting with FAIL: a quote that was not found in the source. This is expected.Part of Claude’s answer, shortened:FAIL lei2023financial.md:  quote 1 (p. 1): text not found  in sourceRun 2 of 2: one FAIL line. It is expected.The note holds an invented quote on purpose.Example: what yours should roughly look like

Also look at the helper path Claude shows first. If it contains provenote-main, stop: that is the downloaded copy, not the one you installed, so do not trust the result.

Done when you see 14 PASS lines, then the one expected FAIL.

Stuck? A different number of lines, no FAIL, a Python error, or a helper path that contains provenote-main → do not trust the result. Paste this message into Claude Code, then repeat 12c:

Inside Claude Code
The checker did not give the expected result. Please find where the Provenote plugin is installed, show me that path, and tell me what is wrong. Do not reinstall anything yet.

Still wrong after that: Ask for help

Want to run the checker yourself, without Claude? See the details at the end.

Step 13: Your first research task

Why: to save a real result, so you can see how Provenote works in everyday use.

Still in examples/basic, with Claude Code open, paste this box as one message and press Enter once. Claude will probably ask "Do you want to proceed?" before it creates the file. Read it, as in step 4: if it only writes 00_admin/first-check.md, press Enter on Yes; if not, press Esc.

Inside Claude Code
Using Provenote, verify the quotes in the notes in 01_notes/lit/ with the installed
verify-quotes helper. Save the full output, the date, and the helper path you used to
00_admin/first-check.md. Do not change any other file. Then tell me, in two sentences, what
this result does and does not show.

You should see: a new file in your folder.

A new file appears in your folderInside examples/basic, the folder 00_admin now contains a new file called first-check.md.A new file appears in your folderexamples/basic00_adminfirst-check.mdnew fileInside: the PASS lines, the date,and the helper path.Illustration, not a screenshot

To read it, ask Claude "Show me 00_admin/first-check.md", or open it yourself: right-click the file in your file window and choose Open With → TextEdit (Mac), Open with → Notepad (Windows) or Open With and a text editor (Linux).

Done when the file 00_admin/first-check.md exists and contains the 14 PASS lines. Claude's two sentences should say the quotes were found on the stated pages of the text copies, and that this does not show your claims are supported or true.

Stuck? The file is missing or empty → copy what Claude said and ask for help

You did it. From here, start your own project: ask Claude to start a research project, search the literature, or verify notes. The workflow lists the stages. Searching needs internet access, and converting PDFs or building papers have extra requirements listed in INSTALL.md. Install those only when you reach that stage.

Using the app afterwards

This is a side route for after the steps above. This guide has not tried the app; everything here comes from Anthropic's own pages, so your screen may differ.

  • Download the Claude desktop app for Mac or Windows (Linux is in beta) and sign in with your Claude account. Claude Code is in the Code tab at the top of the sidebar.
  • The app includes Claude Code, so you do not need the terminal install to use the Code tab. It runs its own copy of Claude Code, whose version can differ from the claude you installed in step 3.
  • Under the message box, click the first control, choose the top entry in the Local group, then use the folder control beside it: Open folder…, and pick your project's folder.
  • The app reads the same CLAUDE.md files, hooks, skills and settings as the terminal. Each keeps its own list of sessions.
  • Plugins. The marketplace-add and install lines (step 5, and step 9 for Provenote) stay in the terminal, as in this guide. Then, in the app, check that the commands appear under + → Slash commands, or after typing /. This guide has not confirmed that they do.
  • Asking before it acts. In Manual mode (the mode control is in the row under the message box) the app shows a diff and buttons to approve or decline each change. The rule from step 4 is the same: read what it wants to do, and approve it only if it matches what you asked for.

On Windows, by default the app runs your session on Windows itself, not inside WSL. If you followed Route A, do not expect the setup you made inside Ubuntu in the app. Plugins are not available in app sessions that run in WSL. Hooks written for bash may also fail on Windows if Git for Windows is missing; this guide has not checked that in the app.

Stuck? Ask for help

Do not reinstall again and again, and do not change settings to "fix" a message. Copy the help message below into a chat with Claude, or into a new GitHub issue (that needs a free GitHub account). Fill in the blanks with the exact error text, never a summary, and leave blank whatever you do not know. Before you send it, remove your name, your email address, and anything that looks like a key or token:

Text
I am following the Claude Code setup guide for ai-architecture (v0.4.2-preview) and Provenote (0.2.1, commit 373ca03).
Step: <step number and name>
Exact error text (copy and paste, unedited): <paste here>
My system: <macOS, Windows or Linux, and the version; on Windows, PowerShell or WSL>
Versions: claude --version = <...>; git --version = <...>; Python version = <...>
What I expected: <the "Done when" line from the guide>
Please tell me the smallest next thing to check. Do not install or change anything yet.

Report problems, and what worked, under Issues on the ai-architecture GitHub page or the Provenote GitHub page. Reports from real Mac, Windows and Linux machines are what this guide needs most.

More detail (optional)

You do not need any of this for your first run. Open what you need.

What Provenote does NOT do

Provenote gives you a set of skills and helper programs that turn a reading list into source-grounded notes, and check each quotation in your notes against a text copy of the source, on the page you cite.

It does not tell you a quote is accurate to the original PDF, that it supports your claim, or that your claim is true. A passing quote check means only: "these words are on this page of this text copy of the source." Whether they mean what you say they mean is still your judgment (and a model's reading of it needs your review). See what is verified.

Costs and plans

Plans and prices change, so this guide quotes none. Read the official page before you start: https://docs.claude.com/en/docs/claude-code/setup. Claude Code needs a Pro, Max, Team or Enterprise plan (or a Console account); the free claude.ai plan does not include it. If you cannot tell whether your plan includes Claude Code, stop and read the page again, or ask in the issue tracker. Do not guess.

What steps 5 and 9 change on your computer

Adding ai-architecture or Provenote installs its packaged skills and roles. It does not install Python, Poppler, pandoc or R. Do not replace your existing settings, CLAUDE.md or permissions with anything from this collection. The step 5 lines are copied from the ai-architecture README.md and INSTALL.md; the step 9 lines from the Provenote README.md and INSTALL.md.

Which version of Provenote does "Download ZIP" give me?

"Download ZIP" gives you the latest version of the branch, which may be newer than the commit this guide was tested with (373ca03, Provenote 0.2.1; see About this guide). The example folder examples/basic holds two open-access papers, their text copies, two notes, and one note with a planted fake quote.

Why the checker must come from the installed plugin (step 12c)

The helper path shown in step 12c must be under Claude Code's plugin install location, and must NOT be anywhere inside your downloaded (unzipped) Provenote folder, for example examples/basic or plugins/provenote/bin there. The point of this check is to prove that the plugin you installed works. A path into the download (the quick test: it contains provenote-main) proves nothing about the installed plugin, so do not trust the result.

Run the checker yourself, without Claude (optional)

Ask Claude: "Print the absolute folder of the installed Provenote plugin." Use that folder as KIT below, then run from examples/basic. Commands follow INSTALL.md and codex/SKILL.md.

Set the folder first. On a Mac or Linux PC, set KIT to the folder Claude printed, as an absolute path in quotes, in the form KIT="/absolute/path/to/plugins/provenote". On Windows the variable is called $provenoteKit; set it to the folder Claude printed, in the form $provenoteKit = "C:\absolute\path\to\plugins\provenote".

In the terminal
python3 "$KIT/bin/verify-quotes" --help
python3 "$KIT/bin/verify-quotes" --strict 01_notes/lit/*.md
python3 "$KIT/bin/verify-quotes" --strict 01_notes/negative/*.md

Windows, in the terminal: PowerShell does not expand *.md; pass the note paths explicitly.

In the terminal
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/lit/lei2023financial.md
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/lit/kireyev2026pricebench.md
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/negative/lei2023financial.md

All 14 lines start with PASS, and the last command prints the one expected FAIL. On Mac or Linux the second command prints all 14. On Windows the first two commands print 6 and then 8 of them. On Windows, if py -3 was the one that worked in step 2, use & py -3 instead of & python.

How these pictures were made

The terminal pictures marked "Example" use text from a real run on Linux (Provenote 0.2.1, Claude Code 2.1.314, Python 3.12.3, Git 2.43.0), trimmed to fit; the prompt line is left out because it differs on every computer. Your colours and version numbers will differ. Pictures marked "Illustration" are drawings of the idea, not screenshots or real output.

About this guide

Written with Claude; reviewed by the Provenote author (review pending)

  • Date: 2026-10-27
  • Written for: ai-architecture v0.4.2-preview (read, not run, by this guide's author). Tested with: Provenote 0.2.1 at commit 373ca03; Claude Code 2.1.314 (observed on Linux)
  • Status: untested on real Mac/Windows/Linux desktops. Nobody has followed this guide from start to finish on a real Mac, Windows or Linux PC yet. The steps are copied from the projects' own documents, and the quote check was run on Linux only. ai-architecture's own page says it was built and used on one Linux machine and that other operating systems are untested; this guide's own advice on Windows is WSL, the closest to that, which is untested too. If something looks different on your screen, that is useful news: see Stuck? Ask for help and tell us.

Later