0. Quick start

The whole thing once, from nothing to a dry run with yourself as the only student. About twenty minutes. Each step points to the chapter that says more.

1. Install (chapter 2). Open a terminal, paste the one-line uv installer for your computer, then uv tool install the Mosscap file you were sent. Type mosscap: the app opens in your browser.
2. Log in (chapter 3) with the email and password the administrator gave you. Under Settings, press Make a desktop shortcut so you never need the terminal again.
3. Create a class (chapter 4): a name, and a folder to keep it in. Import a roster: a spreadsheet saved as CSV with a column called email. For the dry run, a roster with only your own email is enough.
4. Send yourself your link (chapter 4): type your name in the lookup box, press email link.
5. Write a session (chapter 5): under New session, one question and its rubric in the form, or paste a session file. Press Validate and save.
6. Run it (chapter 6): open the session, press Deploy, open your student link on your phone, press Start. Answer on the phone. Watch the feedback arrive, the histogram fill, and the class summary appear. Press End session, then Write the files.
7. Look at the files (chapter 8) in the class folder: results.csv opens in Excel.

If anything on the way does not do what this says, chapter 7 is the troubleshooting table.

1. What Mosscap is, and is not

You want students to think during class, and you want to know what they thought. Mosscap lets you pose an open-ended question, have every student write an answer on their own device, and within seconds give each of them brief individual feedback and a score against your rubric, while you see a summary of what the class understood and where it struggled. Then you teach to that.

What students see. A page with the question, a box to type in, and, after they submit, feedback and a score. Their draft is saved as they type, so a phone that falls asleep loses nothing.

What the AI sees. The question, your rubric, and the student's text. Not the student's name, email, or anything else about them: students are known to the server and to the AI only by an anonymous link. The AI is asked to treat the student's text as an answer to grade, never as instructions, and it flags attempts to talk it into a score.

What the scores are for. Learning, not grades. They are formative: a fast reading of an answer by a machine, good enough to steer a discussion and to tell a student what they missed, not a substitute for your judgement. Mosscap is not a homework or exam system.

Beta software, use at your own risk. Mosscap is under active development at the University of Kansas and in use with a small number of instructors. It will have rough edges. Keep your own records; the files it writes are yours, on your computer.

Who to contact. Daniel Reuman, University of Kansas. Chapter 7 says what to include in a message when something goes wrong.

2. Installing on your computer

You want the app on your laptop, started from an icon. It runs on Mac, Windows, and Linux. It is installed as a Python program with uv, a small tool that fetches Python for you if you do not have it, so there is nothing to download by hand and no warning from your operating system about an unknown developer.

1. Install uv (once)

Open a terminal (Mac: Terminal, in Applications → Utilities; Windows: PowerShell, from the Start menu; Linux: your terminal) and paste one line.

Mac and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close the terminal and open a new one, so that it knows about uv.

2. Install Mosscap (once per version)

You were sent a file named like mosscap-0.1.0-py3-none-any.whl. Save it somewhere (Downloads is fine), then in the terminal:

uv tool install ~/Downloads/mosscap-0.1.0-py3-none-any.whl

On Windows the path looks like C:\Users\you\Downloads\mosscap-0.1.0-py3-none-any.whl. Drag the file into the terminal window to have its path typed for you.

3. Start it

mosscap

Your browser opens on the app. The terminal window stays open while the app runs; closing it stops the app. The first time, log in (chapter 3), open Settings, and press Make a desktop shortcut: from then on you start the app from the icon on your Desktop and never need the terminal. The line beside the button names the files it made.

• Windows gets two shortcuts: one on the Desktop and one in the Start menu, so pressing the Windows key and typing moss finds Mosscap, and a right-click there pins it to the taskbar. If OneDrive backs up your Desktop, "the Desktop" is the OneDrive one and the Desktop shortcut lands there; the Start menu one is never synced. Double-clicking opens a console window beside the browser; it stays open while the app runs.
• Mac: Mosscap.command on the Desktop; double-clicking opens a Terminal window that stays open while the app runs.
• Linux (GNOME): right-click the new icon once and choose Allow Launching. The app is also in the applications menu.

Updating

When you are sent a new file, install it the same way with --force, which replaces the old version:

uv tool install --force ~/Downloads/mosscap-0.2.0-py3-none-any.whl

Your settings, your classes, and your shortcut are untouched by an update.

Uninstalling

uv tool uninstall mosscap

Your class folders are not touched: they are ordinary folders that you chose. The app's own two files (settings and the list of classes) stay in your application-data folder and can be deleted by hand; chapter 3 says where they are.

If your computer warns you about an unknown developer

It will not, with the install above: nothing in it is a downloaded program, so neither macOS Gatekeeper nor Windows SmartScreen has anything to say. This section is for a future version that may ship as a single downloadable program. If that version shows "unidentified developer" (Mac) or "Windows protected your PC", it is because the program is not signed with a paid certificate, not because it is unsafe. On a Mac, right-click the program and choose Open, then Open again. On Windows, press More info, then Run anyway. You only do this once.

Where the app keeps its own files

Two small text files, your settings and the list of your classes, in the folder your operating system provides for such things: ~/Library/Application Support/Mosscap on a Mac, %APPDATA%\Mosscap on Windows, ~/.config/mosscap on Linux. Everything else, rosters, sessions, and results, is in the class folders you choose (chapter 4). Your own API key, if you use one, is in your computer's keyring, not in a file.

3. Your account and settings

You want to log in and set the defaults once, then forget them.

Logging in

The administrator creates your account and gives you an email and a password. The app remembers the email; the password is asked for each time the app starts. A login lasts twelve hours; if it runs out mid-session, the app shows the login screen, you log in again, and the running session continues with nothing lost.

The settings screen

Every one of these except the first two can be overridden for one session, and most for one question, in the session file (chapter 5). The settings screen sets the defaults.

Whose API key pays for the grading

Every grade and every summary is a call to the AI provider, Anthropic, and is paid for through an API key. There are two arrangements.

The shared key, on trial. A new instructor grades on the administrator's key and credit, if the administrator has allowed it for your account. Nothing to set up: leave the API key field blank. This is for trying Mosscap and for the first few sessions.

Your own key, once you use Mosscap regularly. Then the grading is billed to you (or to your department's account), and the administrator is not paying for your classes. To set it up:

1. Make a Claude Console account at platform.claude.com. It is separate from a claude.ai subscription and can use any email.
2. Add prepaid credit (Settings → Billing) and set a monthly spend limit there, so a mistake cannot cost more than you chose.
3. Create an API key (Settings → API keys) and name it mosscap, so it can be revoked on its own later.
4. Paste it into the API key field in Settings and press Save. It is stored in your computer's keyring, never in a file, and sent to the server only when you deploy a session.

From then on every session you run is billed to your key; tokens.json in each session's folder says which key was used. What it costs: with the default model, a class of 100 students answering five questions is about $2.50, summaries included; Haiku about $1.75; Opus about $6. A small class is proportionally less.

If your key is lost or leaked: delete it in the Console (Settings → API keys), make a new one, paste the new one into Settings. Nothing else needs to change.

4. Before the semester: classes and rosters

You want each student to have a link that works all semester, so that on the day you can say "open your Mosscap link" and start.

Creating a class

On the Classes screen, Create a class asks for a name and a folder. Everything about the class, the roster, the sessions, and the results, is kept in that folder and nowhere else, so put it where you keep the course: Choose a folder… opens a window; pick an empty folder (make one first in the file manager if the window has no button for it), or type the full path. If you pick a folder that already has files in it, a new folder inside it is proposed instead, so Mosscap's files are never mixed into something else.

A class folder can be moved, backed up, or copied to a co-instructor like any folder. If you move it, the class shows as missing with a Locate… button; nothing is lost. Add an existing class folder is for a folder you received or restored. Remove from list takes a class off the list and deletes nothing.

The roster

A CSV file with a column called email. That is the only requirement; every other column (name, section, student number) is kept and carried into the results files so you can sort by it. Most learning-management systems export such a file; a spreadsheet saved as CSV works too. Emails are lower-cased and must be unique.

Under Roster, Load a roster file… opens a window in the class folder, or paste the text into the box, then Import. Problems are reported with the row number. Nothing is written until the whole roster is good.

What a student link is

Importing gives each student a link, https://app.mosscap-classroom.com/s/ followed by 32 random characters. It is theirs for this class for the whole semester, whatever sessions you run; it opens their page, and only theirs. It is not guessable. It does carry the student's own answers and feedback, so students should not share it, as they would not share a login.

Re-importing the roster keeps every existing student's link. A student who leaves the roster loses theirs; a student added mid-semester gets a new one. So to add a student, add them to the CSV and import again.

Sending the links

Deploying a session does not send anything to students; the links exist from the moment the roster is imported, and sending them is yours to do, once, at the start of the semester. Three ways:

• One student: type part of their name or email in the lookup box; press email link beside them. Your own mail program opens with the address, subject, and link filled in; you press Send.
• The whole class: Download links CSV gives the roster with a link column, for a mail merge from your mail program or the learning-management system. Sending from the app itself is planned.
• Copy beside a student, for pasting anywhere.

A suggested subject line, which the email button uses: Your access link to the Mosscap system for BIOL 414, bookmark this link.

The first-day routine that works: a line in the syllabus that students bring a phone or laptop to class; and five minutes on the first day in which everyone opens their link and bookmarks it, with you watching the joined count on a dry-run session. A student who has lost their link, later, is found in seconds with the lookup box.

5. Writing a session

You want the questions and rubrics for one class meeting ready before class, checked, and saved where you will find them next semester.

Two ways to write one

The form, under New session on the class page: a title, then for each question a label, the question text, and the rubric. Check and preview turns the form into a session file and shows it; Validate and save saves it into the class folder as <session name>/session.md.

A file, written in any text editor, or drafted by an AI from your course materials using the format below, then loaded with Load a session file… (the window opens in the class folder) or pasted. Both ways go through the same checks, so anything that saves will run.

The format, on one page

# Session: Week 3 — Diffusion
model: claude-sonnet-5
summary_threshold: 70

## Q1
Explain in words why diffusion is fast over short distances and slow over long ones.

### Rubric
Max score: 10.
(a) Says that displacement grows with the square root of time: 4 pts.
(b) Applies it to a cell versus a room: 4 pts.
(c) Clear and concise: 2 pts.

## Q2
model: claude-opus-5
effort: medium
Using $\langle x^2 \rangle = 2Dt$, estimate how long a small molecule takes to cross a cell.

### Rubric
Max score: 15.
...

• # Session: and the title start the file. Lines key: value under it are settings for the whole session.
• ## Q1 starts a question; the label after ## is anything, unique within the file. Lines key: value directly under it are settings for that question. Then the question text.
• ### Rubric follows every question, and must contain a line Max score: N.
• ### Model guidance, optional, may follow the rubric: your word to the AI about how to apply the rubric to this question. Students never see it (below).
• Question, rubric, and feedback can use Markdown and math: $...$ inline, $$...$$ on its own line. Students see the math typeset. A dollar sign that is money must be written \$, as in \$3, or the rest of the sentence becomes math.

The settings and what they may override are in chapter 10.

Writing rubrics that grade well

Everything here was learned by running rubrics through the grader on sample answers and looking at the scores.

1. The rubric and the question must agree about what earns credit. A question that promises credit for the right method with an arithmetic slip, and a rubric that says "one point per correct answer", contradict each other, and each model resolves the contradiction differently. Say the rule once, in the rubric.
2. Say what earns no credit when you know the misconception. A rubric that awards a point for "an example of selection" gave a Lamarckian answer anything from 1 to 3 out of 4. One sentence excluding the misconception removes the discretion.
3. A worked full-credit answer helps. A rubric with a complete example answer made all three models agree on every good answer, including ones using different examples.
4. For calculations, say whether errors carried forward get credit. If part (c) is computed correctly from a wrong part (b), does (c) earn its point? Either answer is fine; the rubric should choose.
5. Itemize the points. With items and point values the model reports one entry per item and the score is checked to add up. "Up to 10 points for a good explanation" gives it, and you, nothing to check against.
6. You need not write anything about students trying to game the grader. The grading instructions already tell the model to treat the answer as data, score only genuine content, and flag manipulation; in testing no attempt gained a point.
7. When the AI is consistently stricter or more lenient than you would be, write model guidance rather than bending the rubric. The rubric is what students see; model guidance is read only by the AI. Example: a food-web question asks for "a sentence" on where 90% of the energy goes, the rubric lists several loss pathways, and students answer "respiration and waste" in one sentence. The AI marks that down against the list; you would not. Under the rubric add:

markdown ### Model guidance The question asks for one sentence, so grade that part as a sentence, not a list. Give full credit for one or two real loss pathways; do not require the word "heat".

Guidance goes to the AI with the rubric, for grading and for the class summary. It cannot change the maximum score. It is not on the student page, not in the per-student messages, and not in the mail-merge file; it is in summary.md and results.json, which are yours. In the form it is the third box under each question, left empty when you have nothing to say.

Test a rubric on yourself: deploy the session to a dry-run class with only your link in it, answer well, answer badly, and read the feedback.

Settings per session and per question

A line model: claude-opus-5 under # Session: uses Opus for the whole session; the same line under ## Q2 uses it for that question only. Use it when one question is quick and factual (Haiku is fine) and another needs judgement (Opus). Likewise effort, show_rubric, max_response_chars (raise it for an essay question), and feedback_deadline_s. summary_threshold, final_summary_rerun, and auto_stop describe the whole session and go under the title only.

Reusing a session

A session is a folder in the class folder with a session.md in it. Copy the folder into next semester's class folder; it appears in the list. A session that has results files in it can be deployed again, and the new results replace the old, which the app warns about; copy the folder first if you want both.

6. Running a session in class

This page is the cheat sheet: what to press, in order, and what you will see.

Before class

1. Start the app (the Desktop icon), log in.
2. Open the class, open the session, press Deploy. The run screen appears. Deploy a few minutes before class; it sends nothing to students.
3. Project the run screen if you want the class to see the histogram and the summary; otherwise keep it on your own screen.

For each question

Students open their links. The run screen counts them: submitted: 0 of 23 joined (35 on roster). Wait until the joined count matches the room, because a student whose page is not open yet does not count towards "everyone has submitted".

Start. The question appears on every student's page at once; a timer counts up on yours. Tell the class how long they have.

While it runs. The counter shows who has submitted. As answers come in they are graded within a few seconds each, and the histogram of scores fills in to the right of the question. Once about 70% of the joined students are graded, the class summary appears below: what the class understood, common difficulties, what went well. Read it while the last students finish.

Stop, or not. When every student whose page is open has submitted, the question closes by itself and the screen says so. Otherwise press Stop when most have submitted: students still typing get five seconds' grace, then whatever is in their box is submitted for them (a blank box scores 0); their pages say the question is closed. The rest of the grades arrive within about 20 seconds in a large class.

Refresh summary re-runs the summary on all the grades in so far. The button greys out the moment it is pressed and "Updating the summary…" appears beside it until the new summary lands, a few seconds later. It stays greyed out when the summary on the screen already covers every grade; "based on 23 of 23 graded" beside it says how complete it is.

Lead the discussion from the summary and the histogram. Then Next question, and again.

Ending

End session, then Write the files: the app waits for any grades still in progress, writes the results into the session's folder (chapter 8), and only then tells the server to delete its copy. The box under the buttons lists the files written. Untick Include the rubric in the per-student messages first if you would rather students did not get the rubric.

If you press something twice or out of order

Nothing breaks. Buttons that make no sense in the current state are not shown: Start only before the first question, Stop only while a question is open, Next only after a Stop. Pressing Stop as the question closes by itself does nothing. Deploying a session that is already running on the server offers to resume it. End can be pressed at any point, even mid-question: the open question is closed, drafts are submitted at once, and the files are written when the grades are in.

Using the summary

The summary is a reading of the graded answers against your rubric: overall, common difficulties, what went well; the last two are boxed so the eye finds them. It is best used as the starting point of the next few minutes of teaching: put a common difficulty to the room, ask someone who got it right to explain. The provisional summary is based on the answers in so far; the files get a complete one at End.

7. When something goes wrong

What to include in a message when reporting a problem: the date and time, the class and session name, what you pressed, what the screen said (a photo of the projector is fine), and, after class, the results.json from the session folder if the problem was about grading. Never send tokens.json from a class folder or a student link.

8. After class: the files

You want to see who wrote what, what the AI said, and what it cost, in something that opens in Excel or R. Everything is in the session's folder inside the class folder, written when you pressed Write the files.

results.csv

One row per student on the roster, absent ones included. First the roster's own columns (email and whatever else the roster had), then joined (yes, or absent if the student's page never opened), then for each question, prefixed q1_, q2_, and so on:

So the three cases are: absent (joined is absent, everything else empty), blank (response is empty and score is 0, with force_submitted saying whether Stop did it), and answered. Opens directly in Excel; in R, read.csv("results.csv").

summary.md

For each question: the question text, the rubric, your model guidance if you wrote any (this file is yours; the per-student messages never carry it), the class summary (the complete one, made at End, or the last one shown in class), and the score distribution. Readable as it is; paste it into your notes.

results.json

Everything the server exported, joined with emails: every draft-turned-submission, every grade with its itemized points, every summary including the provisional ones shown in class, the settings each question ran with. For when results.csv is not enough.

tokens.json

How many tokens each model used, per question and in total, and which key paid (shared or own). No dollar figure: the exact cost is derived on the server from Anthropic's billing data overnight, and the administrator's report is the record. For a rough figure, a graded response on the default model costs about half a cent.

students/ and mail_merge.csv

One message per student, in students/<email>.md, with each question, their response, score, and feedback, and the rubric if you left that ticked at End. mail_merge.csv has the same messages in two columns, email and message, for a mail merge from your mail program or the learning-management system. Sending many messages from a personal account can trip the university mail system's rate limits; a mail merge through the LMS does not.

Suggested uses

• Sort results.csv by q2_score to find who is struggling before the exam.
• Search q1_feedback for a phrase to count a misconception.
• joined is a participation record with no effort on your part.
• Return the feedback to students through the messages, with the rubric, as the written record of the day.

9. Privacy and data

This page is written to be handed to a department chair or a student who asks.

What identifies a student. Nothing on the server. A student is known there, and to the AI provider, by a link containing 32 random characters, made on the instructor's computer when the roster is imported. The list that connects links to names and emails (tokens.json) is in the class folder on the instructor's computer and is never sent anywhere.

What is on the server, and for how long. While a session runs: the questions and rubrics, each student's draft and submitted answer, and the AI's feedback and scores, keyed by link only. This is kept in memory and in a working file so that a restart loses nothing, and it is deleted when the instructor's app has received the results at the end of the session, or, if the app never comes back, within 24 hours. Permanently: instructors' logins (email and a hashed password), and a usage log of token counts per session with no student text in it.

What is sent to the AI provider, and under what terms. For each answer: the question, the rubric, any model guidance the instructor wrote for the question, the instructions for grading, and the student's text, with no identifier. The provider is Anthropic, reached through its commercial API, under its commercial terms of service, which govern how long it retains inputs and outputs and forbid their use for training its models; the current terms are at anthropic.com.

What is on the instructor's computer. The roster, the link list, and the results files described in chapter 8, in a folder the instructor chose. They contain student names, emails, answers, scores, and feedback, and should be kept where other grade-related files are kept, with the same care. A class folder inside a synced folder (Dropbox, OneDrive, iCloud) is copied to that service, which may or may not be permitted for student records where you work.

What students are told. Their page carries a short notice that their answers are graded by an AI system against the instructor's rubric, that the system does not know who they are, and that the scores are for learning, not for grades. While they are answering, the line above the box reminds them not to put personal or identifying information into Mosscap, so that none reaches the AI provider or the results files in the first place.

Who can see what. A student sees only their own page. The instructor sees every answer and grade for their own classes. The administrator can see token counts and, on the server during a session, the answers keyed by link, but not who wrote them.

Connection. Everything travels over HTTPS. The server accepts connections only through Cloudflare; it has no open ports of its own.

10. Reference

Settings

A question's value overrides the session's, which overrides the app's. Values are case-insensitive except model names. A key given twice in one header, or a session-only key under a question, is reported as an error when the file is saved.

The session file

# Session: <title>
<key>: <value>            (settings for the whole session, optional)

## <question label>
<key>: <value>            (settings for this question, optional)
<question text: Markdown and $math$>

### Rubric
Max score: <number>
<rubric text>

### Model guidance
<optional: how the AI should apply the rubric; never shown to students>

Exactly one # Session: line; at least one question; every question followed by its ### Rubric with a Max score: line, then optionally its ### Model guidance. Labels are unique within a file. Questions are numbered in file order. Up to 50 questions.

Limits

Up to 500 students in a session. A response of at most max_response_chars, and never more than 100,000 characters. A session's grading stops, with the remaining answers marked ungraded, after 20 million tokens, which a class never approaches.

Glossary

• Token: the unit in which AI models measure text, about three quarters of a word. Costs are per token.
• Effort: how long the model thinks before it writes; more effort is slower and costs more.
• Rubric visibility (show_rubric): whether students see the rubric on their page after their feedback.
• Summary threshold: the share of the joined students that must be graded before the class summary appears by itself.
• Joined: a student whose page has opened during this session.
• Provisional / complete summary: a summary based on the grades in so far / on every grade.
• Flagged: an answer the model judged to be an attempt to manipulate the grading.
• Ungraded: an answer the AI service could not grade in time; it can be regraded.
• Forced submission: a draft that Stop submitted for a student.
• Shared key / own key: whose Anthropic account pays for the grading.

Version history

• 0.1.1 (October 2026): the Windows shortcut finds the Desktop wherever Windows keeps it (OneDrive included) and is also put in the Start menu; error messages appear beside the button or box that produced them.
• 0.1.0 (October 2026): the pilot release.