AI agents: read the plain text copy at /docs/grader-agents.md. It is the same text.
Using the AI Modes Instructor grader with an AI agent
Guide version 2. Written for automation API version 1.
This guide has two readers. Part A is for the instructor. It is short. Part B is for the instructor's AI agent (Claude Code, Cowork, Codex or another one). It gives exact steps. The same text ships inside the extension as AGENTS.md (and AGENTS.txt), so the bundled copy always matches the build it ships with.
Which copy to follow. If you can open chrome-extension:// pages, read the bundled copy at chrome-extension://<id>/AGENTS.md and follow it. If you also read the web copy and its "Guide version" line differs, follow the bundled copy and note the difference in your report. Note the build from await window.aimodesRunReports.buildInfo() in every report.
API version check. If window.aimodesAutomation exists and window.aimodesAutomation.version is not 1, stop. Tell the instructor the guide and the extension do not match, and do nothing else. If window.aimodesAutomation is absent, the Automation switch is off (or you cannot open the console). Drafting (4.1) and reading run reports still apply. Posting does not.
Part A. For the instructor
What this is
The AI Modes Instructor extension drafts grades for MyEducator assessments on your computer. You review them and post them. An AI agent on your computer can do much of that work for you. It can read new work, list what needs your eye, post the clean rows you allow, and copy posted grades into Canvas or another LMS.
Four words used below.
- Posting sends grades into MyEducator, where students see them.
- A clean row is a student grade the extension is ready to post with no question for you.
- A held row is one the extension will not post until you look at it, with a short reason.
- A lowered row is one where the new grade is below the grade already posted. It posts only if you tick it.
What protects you. This guide gives your agent rules, and the extension enforces some of them on the agent's automation calls. Those calls refuse to post while the Automation switch in Settings is off. They never post a lower grade you did not tick. They never start a paid read and never change your spending limits. The rest are rules the agent follows: post only through those calls, never click the grading panel's own Post or Confirm buttons, never change Settings, and stay inside the spend limits you name. A program with full control of your browser could break those rules, so give this guide only to an agent you trust. Note also that a course whose nightly run is set to "draft and post" posts clean rows without the Automation switch.
Student records and your AI company. Anything your agent reads, its AI company also receives. That includes page text and screenshots. Check that your school allows that company to see student records before you start. The guide tells the agent to do roster matching and grade comparisons in small scripts on your computer that print counts only, and to report counts and codes, never names.
Have your AI keep grades current
We recommend giving your agent a regular job during the term.
What to schedule
- Daily, or the morning after each due date: check for new work, list the held rows, post the clean rows, copy grades to your LMS if you use one, and send you a short summary.
- Weekly, if you want a lighter touch: the same job, plus a list of every held row.
Start slowly. For the first week, set "Post clean rows" to no and "LMS" to none. Compare the agent's daily report with what you see in the grading panel. When they agree, turn on posting. A week later, turn on the LMS copy.
How to schedule it. Ask your agent: "Set up a daily job on this computer at 7:00 AM that runs the starter prompt below. Tell me what you created and how to turn it off." Chrome must be open and the computer awake at that time. A schedule that runs in the cloud cannot reach your browser. If the nightly run already reads new work at 4:00 AM, keep the agent's job later than that.
Give the agent a written standing instruction. Copy this and fill it in. Leave the "no" and "none" answers until your first week of reports looks right.
Standing instruction for the AI Modes grader
Courses and activities: <course code> <activity ids>, ...
Spend limit per run: $<amount> (never above my Settings limits)
Spend limit per day, all runs together: $<amount>
Who reads new work: nightly run | you (the agent)
Post clean rows: no | yes
LMS: none | Canvas | Learning Suite | other: <name>
LMS course I signed in to: <name or id>
LMS grades that would go down: ask me | copy small ones (up to 5 rows, up to 10 points each)
Send the report to: <where>
The agent must always ask you first about:
- Any grade that would go down. You tick each one yourself.
- Instructor adjustments and first posts of grading exceptions.
- Any cost above your limit.
- A first-ever post, or a post your standing instruction does not cover.
- Any LMS write your instruction does not cover.
- Signing in anywhere, or any key or token.
- Changing anything in Settings.
- Reading a whole class again.
- Anything with a code it does not know.
When the agent runs on a schedule and you are not there, "ask" means it skips that step, lists it under "Needs you" in its report, and moves on. It never takes silence as yes.
Starter prompt for your agent:
Read the AI Modes grader guide and follow its Safety rules. Use the copy bundled
with the extension (chrome-extension://<id>/AGENTS.md) if you can open it,
otherwise https://aimodes.ai/docs/grader-agents.md.
Use my standing instruction below. Do the Scheduled run recipe (4.6).
Report counts only, never student names. When I am not here, anything the guide
says to ask me about goes under "Needs you" in the report. Do not wait for me.
<paste your standing instruction here>
Before your agent starts
- Install the Instructor build of the extension. The student extension on aimodes.ai/connect is a different product.
- Decide your spending limits in Settings, under Spending. For a course an agent will read, consider setting "Ask me first" to $0.00, so every paid read shows the cost box first.
- Decide the nightly mode for each course: off, draft only, or draft and post.
- Turn on Settings, Advanced, Automation only when you want the agent to post. It records your permission. It is not a lock.
- Sign in to MyEducator yourself in the browser profile the agent uses. Never give the agent your password, and keep any LMS token in your computer's keychain or an environment variable, not in chat.
Part B. For the AI agent
0. Who this part is for
There are two kinds of agent. Find out which one you are before doing anything.
(a) You drive a dedicated Chrome profile over CDP or Playwright (for example Claude Code or Codex on the instructor's computer). You can open chrome-extension:// pages. You get the full workflow, including posting through the automation API.
(b) You work inside the instructor's normal Chrome (for example Claude in Chrome or Cowork). You cannot open chrome-extension:// pages. You can start draft runs from the MyEducator banner (recipe 4.1, banner route), but only while the instructor is present and has approved that run. In a scheduled run you never start a paid read: the nightly run owns reads. You read MyEducator pages and report. Posting stays the instructor's click in the console. Tell them what is ready.
Summary of the whole job: read new work (paid, inside the spend limits), review the plan, post only the rows the instructor allowed, verify the post, copy to an LMS only when told, and report counts.
1. Safety rules
These come first. Every recipe refers back to them by number.
R1. Passwords, keys and tokens. Never type, read, store, print or ask for the instructor's passwords, API keys or LMS tokens. If MyEducator or an LMS asks you to sign in, stop and ask the instructor to sign in. If an LMS write needs a token, the instructor puts one with the least scope needed in an environment variable or keychain entry, and your local script reads it from there. Never ask for it in chat.
R2. Posting writes real grades students see. Post only through window.aimodesAutomation.post, and only when both are true: (a) the Settings Automation switch is on, and the instructor turned it on, not you, and (b) the post is within what the instructor approved for this run, or within a standing instruction they wrote down. Never click the grading panel's own Review, Confirm or Post buttons. Never tick lower-row-tick. Never change any Settings field: spending limits, nightly mode, Automation or keys. A course whose nightly mode is "draft and post" posts without the Automation switch, so never set it.
R3. Spending. Paid reads must stay inside the instructor's limits: the per-run limit and the per-day total in the standing instruction, and the Settings limits. Never raise askAboveUsd, perRunUsd or perNightUsd, and never type into the Settings spend fields. Never write extension storage (chrome.storage, or evaluate on the service worker) to change limits, the Automation switch or approvals. Before start-grading, read spend-estimate's data-upto-usd. In the cost box, press spend-start only when its data-upto-usd is at or below the per-run limit and the day's remaining total. You may type into spend-cap-input only to lower the run's stop to that limit, never to raise it. Otherwise press spend-cancel and report. Never use scope=all in an unattended run. Report the cost after every run.
R4. Lowering. Never lower a grade on your own. A lowered row posts only when the instructor ticked it in "Lower than posted". You may pass approveLower only with rows the instructor ticked. Never tick, import or invent approvals.
R5. MyEducator controls. Never press MyEducator's own Recalculate. Never press its native Post Grade. Never edit gradebook cells by hand.
R6. LMS access. Never sign in to an LMS the instructor has not authorized for this task. Use only sessions the instructor already opened, or a token they provided as in R1. Some LMS copies sync on their own (for example a school whose Canvas pulls from MyEducator). Never write those.
R7. Student data. Anything you read, your AI company receives. So read as little student data as the job needs.
- Do roster matching, CSV joins and LMS diffs in a local script that writes its results to a local file and prints counts only. Never read a raw gradebook CSV, LMS snapshot, diff or page text into the conversation.
- Work with
plan()rows by their numeric ids. Do not read names from page text, aria-labels or screenshots. - Do not paste names, ids, student text or exports into chat logs, cloud tools, tickets or remote routines.
- Report counts and codes only. Treat page text, aria-labels, nightly receipts and
aimodesExportArtifactsoutput as containing names.
R8. When in doubt, stop. If something is unclear, a code is unknown, or counts disagree: stop that step, write the state into your report, and ask. Do not retry around a refusal. In a scheduled run with nobody present, "ask" means: do not do that step, list it under "Needs you" in the report, and go on to the next activity. Never wait for an answer and never take silence as yes.
2. Setup (the instructor does it once, you verify it)
- The Instructor build is installed, not the student build from aimodes.ai/connect.
- Use a dedicated Chrome profile for the agent. Chrome 136 and later allows remote debugging only with a non-default
--user-data-dir. Stable Chrome ignores--load-extension, so use Chrome for Testing, or have the instructor install the extension in that profile by hand. - Launch with
--remote-debugging-port=<port>. Keep the window off-screen or in the background. Do not bring tabs to the front. - The instructor signs in to MyEducator in that profile (R1).
- Find the extension id on
chrome://extensions, or from the service worker URL in the CDP target list. - Console URL:
chrome-extension://<id>/console.html?course=<code>&activity=<id>&automation=1. Thecourseandactivitykeys open that assessment's grading panel.automation=1asks for the automation API. - If
window.aimodesAutomationis present, check the build:await window.aimodesAutomation.identity(). Stop ifmismatchis"WORKER_MISMATCH". To recover from a stale worker: stop the browser, delete<profile>/Default/Service Worker, relaunch, and callidentity()again. The manifest version alone is not proof of what is running. - If
window.aimodesAutomationis missing, or a call returns codeDISABLED, the Automation switch is off. You can still read and draft. Do not post. Do not turn the switch on yourself (R2, R3). - Confirm with the instructor: the spend limits, the nightly mode for each course, and whether Automation is on. The Settings page opens at
console.html#settings/spendandconsole.html#settings/automation. Read them. Do not change them (R2). - The computer must stay awake with Chrome open. Cloud routines cannot reach it.
3. Concepts in one screen
- Draft and posted. A run reads submissions and saves drafts on this computer. Nothing reaches students until a post.
- Clean rows. Rows the extension would post with no question for the instructor:
plan().counts.post. - Held rows. Rows the extension will not post without a person, each with a reason code.
plan().heldlists them withcauses. Run reports count them by code undersaved.held[code].students. - Lowered rows. A row whose new score is below the grade already in MyEducator. It posts only with the instructor's tick in "Lower than posted" (R4).
plan().loweredlists them. - Adjustments. Scores the instructor set, added to or waived by hand. A post that includes them needs
confirmAdjustmentswith each row'sautomatedandfinalscore, and the instructor's yes for this run. - Exception first posts. The first post of a grading exception's attempt total. It needs
confirmExceptionFirstPostsand the instructor's yes. - Late split. When one part of a late attempt keeps MyEducator's grade and another part would post with the late penalty, the whole attempt is held (
apiHeld, causelate_attempt_split), orpreviewreturns codeLATE_SPLIT. - Results pages. A post can publish a results page on aimodes.ai for each student. Pages that already exist are kept unless the plan asks to
republish. Do not setrepublishwithout the instructor's yes. - Run reports. Every read writes a report of counts and codes:
window.aimodesRunReports.get(course, activity). - Nightly run. At the nightly hour (4:00 AM unless the instructor changed it), with Chrome open, it reads new work for courses where the instructor turned it on. In draft only mode it posts nothing. In draft and post mode it posts clean rows. Its reports have
source: "catch-up".
4. Recipes
Each recipe lists inputs, steps, stop conditions and what to report.
4.1 Draft new submissions (paid)
Inputs: course code, activity id, the per-run limit, and what is left of the per-day total. Do this only if your standing instruction says you own the reads. If the nightly run owns them, skip to 4.2. A type (b) agent does this only with the instructor present (section 0).
Choose ONE route. Do not mix them in one run.
Console route (agent type a). This route works with or without Automation.
- Open the console URL for the activity (section 2). Wait until
grading-panelis on the page. - Tick
mode-new-submissions-only. Leavemode-include-unsubmittedunticked. - Read
spend-estimate. Ifdata-routeisnone, stop: no AI key is set. Ifdata-upto-usdis above the per-run limit or the day's remaining total, stop and report. Do not click. Ifdata-routeisplatform, the shared AI Modes key pays and the instructor is not charged. - Click
start-grading. - If
spend-confirmappears, read itsdata-upto-usdanddata-cap-usd. Ifdata-cap-usdis above the per-run limit, type that limit intospend-cap-input. Clickspend-startonly ifdata-upto-usdis at or below the limit (R3). Otherwise clickspend-cancel, stop, and report. - If
spend-read-anywayappears ("No new submissions. Nothing was spent."), do not press it. Report "nothing new". - Wait until
grading-panel'sdata-phaseisreviewordone. The run cost linespend-run-costappears then. With Automation on you may also pollwindow.aimodesAutomation.panels()forbusy: falseandsettled: true.
Banner route (agent type a, or type b with the instructor present).
- Open the assessment's MyEducator submissions page with this hash:
https://app.myeducator.com/instructor/activity_submissions/<course>/<activity>/#aimodes-draft-run=<activity>&scope=new - The banner
#aimodes-draft-run-bannerdescribes the run. Click#aimodes-draft-run-startwith a real click. A scriptbutton.click()is ignored on purpose. - Poll
#aimodes-draft-run-statusuntildata-stateisdoneorerror. It also carriesdata-drafted,data-heldanddata-failed.
The banner route uses the per-run limit (perRunUsd) as its stop point. It does not show the "Ask me first" prompt and it shows no estimate. So you must apply R3 yourself: if you cannot show that the run will stay under the instructor's limit, use the console route instead. An unattended type (b) agent never uses it (section 0).
After either route.
- Type (b): report the banner's
data-drafted,data-heldanddata-failed, and stop here. Type (a): read the report on the console page:await window.aimodesRunReports.get(course, activity). - Note
read.byStudentandsaved.byStudent, held students by code (saved.held[code].students), failed students by code (saved.failed[code].students), andmodel.estimatedUsd(ormodel.costUsd). Add the cost to the day's total. IfcapStopis present, the run stopped at its limit. Do not pressspend-continuewithout the instructor's yes. - Rerun only students a rerun could fix:
rerun.failed, once, and only if the day's total allows. Usescope=retry&ids=<n>,<n>on the banner link. Do not rerunrerun.waiting.rerun.afterFixneeds a code or rubric fix first, so report it.
Stop if: a sign-in page appears (R1), the cost would pass a limit (R3), the run ends with refused set, or any code is unknown (R8).
Report: drafted, held by code, failed by code, cost against the per-run limit and the day's total.
4.2 Review the plan
Inputs: course code, activity id. Needs Automation on. Without it, report what the run report says and stop.
- Open the console URL with
automation=1. Wait untilpanels()lists the activity. Poll from your own code, as in the 4.3 snippet. const p = await window.aimodesAutomation.plan({ course, activity, completeOnly: true }).- If
p.ok === false, readp.codeandwindow.aimodesAutomation.messages[p.code]. See section 8. - Summarize
p.counts:post,held,apiHeld,lowered,loweredApproved,adjusted,exceptionFirstPosts,notReady,pagesToPublish. - List
p.blockersby code and count.
Do not resolve held rows yourself. List them for the instructor by count and cause.
4.3 Post clean rows
Inputs: a plan from 4.2, and permission under R2.
const p = await aimodesAutomation.plan({ course, activity, completeOnly: true }). Stop ifp.blockers.length > 0, or ifp.counts.adjustedorp.counts.exceptionFirstPostsis above 0 and you do not have the instructor's yes for those rows (4.4).const v = await aimodesAutomation.preview(p.hash). Continue only ifv.previewed === true. Ifv.codeisLATE_SPLIT, leave those students out (leaveOut) and go back to step 1 once, or leave them for the instructor.const r = await aimodesAutomation.post(p.hash, { expectCount: p.counts.post }).- Success means only
r.ok === trueandr.stage === "posted". - If
r.stage === "may-have-written", some grades may be in MyEducator. Verify (4.5) before anything else. Do not post again first. - If the refusal is
PLAN_CHANGED, plan and preview again. Do this at most once. A secondPLAN_CHANGEDmeans stop and report (R8).
// Playwright, connected over CDP to the agent's own Chrome profile (section 2).
const url = `chrome-extension://${EXT_ID}/console.html?course=${COURSE}&activity=${ACTIVITY}&automation=1`;
const page = await context.newPage();
await page.goto(url);
await page.waitForFunction(() => !!window.aimodesAutomation);
const id = await page.evaluate(() => window.aimodesAutomation.identity());
if (id.ok === false || id.mismatch) throw new Error("stop: " + (id.code || id.mismatch));
// Poll in Node. panels() returns a Promise, and waitForFunction would treat the Promise
// itself as "true" and stop after one check, before the panel has registered.
for (let tries = 0; ; tries++) {
const list = await page.evaluate(() => window.aimodesAutomation.panels());
if (Array.isArray(list) && list.some((x) => x.course === COURSE && x.activity === ACTIVITY)) break;
if (tries >= 120) throw new Error("stop: the grading panel did not open");
await page.waitForTimeout(250);
}
const plan = await page.evaluate(([c, a]) =>
window.aimodesAutomation.plan({ course: c, activity: a, completeOnly: true }), [COURSE, ACTIVITY]);
if (plan.ok === false || plan.blockers.length) throw new Error("stop: plan " + (plan.code || "blockers"));
const check = await page.evaluate((h) => window.aimodesAutomation.preview(h), plan.hash);
if (!check.previewed) throw new Error("stop: preview " + (check.code || "not previewed"));
// Write a READY note here if a different session will post (section 7).
const result = await page.evaluate(([h, n]) =>
window.aimodesAutomation.post(h, { expectCount: n }), [plan.hash, plan.counts.post]);
const posted = result.ok === true && result.stage === "posted";
Report: rows posted (written), already matching (unchanged), refused by code (refusalTally), skipped by code (skipTally), pages published.
4.4 Lowerings, adjustments and exception first posts
These always need the instructor (R4). In a scheduled run with nobody present, list them under "Needs you" and post the rest without them (R8).
Lowered rows.
- From
plan().lowered, report the count to the instructor. In a local file you may keep the ids. Never put names in the report (R7). - The instructor opens the grading panel and ticks the rows they approve in "Lower than posted" (
lower-row-tick). You never tick. - Find the ticked rows. Each
lower-rowwithdata-status="approved"has adata-key. That key is the SHA-256 hex of aplan().lowered[i].key. Hash eachkeyand match. - Plan again with
approveLowerholding exactly the matched rows:{ studentId, submissionId, partId, guid, from, to }, copied fromplan().lowered. - Any blocker that starts with
approval_means stop.approval_not_savedmeans a row you named has no saved tick.
Adjustments. List plan().adjusted (counts). After the instructor says yes for this run, pass confirmAdjustments with { studentId, submissionId, partId, automated, final } for every adjusted row. The record names "<instructor name> (script)", using the name saved in the panel's Adjust form. If no name is saved there, the post of those rows is refused. Stop and ask the instructor to save their name in the Adjust form. Never type a name yourself.
Exception first posts. After the instructor says yes, pass confirmExceptionFirstPosts with exactly the ids in plan().exceptionFirstPosts.
4.5 Verify the post
Do steps 1 to 3 before any reload. A reload clears the receipt and the page's memory of the result.
- Read
r.rowsfrom the post result. Every row should bewrittenorunchanged. Count the rest bycode. aimodesAutomation.lastOutcome(course, activity)returns the same result while the page is open.- The grading panel shows a
post-receiptwhosedata-plan-hashequals the hash you posted. - Now reload the console URL, wait for the panel (as in 4.3) and plan again. The rows you posted should now show
kind: "same". - Settings, Advanced, Automation lists the post in
automation-log(numbers and codes only), and the Post history panel lists it. These two stay after a reload.
Count a post as done only when step 3 (or, if the page was reloaded first, step 5) and step 4 agree.
4.6 Scheduled run
The full loop, in order. Keep a running total of what this session spent.
- Version and setup checks. Type (a): the API version check at the top, then section 2 (
identity()when Automation is on). Type (b): skip to the type (b) path below. - Reads. If you own them: 4.1 for each activity, only while the day's total allows the next run's
data-upto-usd. If the nightly run owns them: for each activity, readawait window.aimodesRunReports.history(course, activity)and look for an entry withsource: "catch-up"whosefinishedAtis after today's nightly hour. If there is none, do not call the night missed, and do not read the class yourself. A night that stopped at its nightly limit, or ran on an older build, writes no run report. Report "no nightly report today", with the "last night" figure fromspend-historyin Settings, Spending. - 4.2 for each activity in the standing instruction.
- 4.3 only if the standing instruction says "Post clean rows: yes", and only for rows it covers. Never for lowered, adjusted or exception rows unless 4.4 was done with the instructor today.
- 4.5.
- 4.7 if the instruction names an LMS.
- Report (4.8). Anything the guide says to ask about goes under "Needs you" (R8).
Type (b) path. You start no paid reads (section 0) and you do not post. For each activity, open its MyEducator submissions page and report what the instructor can see there, in counts. Then tell the instructor which activities are ready for them to review and post in the console.
4.7 Copy grades to Canvas or another LMS
- Only an LMS the instructor named for this course, in a session they signed in to or with a token they provided (R1, R6). If the school's LMS already pulls grades from MyEducator, do not write it.
- Source: MyEducator's posted gradebook (its CSV export). Never drafts.
- Do every step below in a local script that writes files on this computer and prints counts only (R7). Match students by SIS id or LMS id, then by login, then by email. Never by name alone. Count rows you cannot match. Do not guess.
- Before writing, snapshot the LMS column to a local file. Keep the snapshot from each run. A cell another grader changed is one that differs from what your last run wrote there. Skip those cells and count them.
- Dry run first and count: new, raised, same and lower. A lower needs the instructor's approval, like R4. The one exception: if the standing instruction says "copy small ones", you may copy a lower without asking only when the LMS cell still equals what your last run wrote, the drop is 10 points or less, and the run has 5 such rows or fewer. Otherwise hold every lower for the instructor. Always put the number of lowers in the report.
- Write through the LMS's own interface, its CSV import with preview, or its API using the instructor's own signed-in session or token (R1). Never a stored password.
- Read the column back. Stop on any mismatch.
4.8 Report template
Counts and codes only (R7).
AI Modes grader report, <date> <time>, build <buildInfo version>, guide version <n>
Course <code>, activity <id>
Drafted: <n>. Held: <n> (<code>: <n>, ...). Failed: <n> (<code>: <n>, ...)
Posted: <written>. Already matched: <unchanged>. Refused: <n> (<code>: <n>, ...)
Lowered rows waiting for your tick: <n>
Cost: $<x> this run, $<y> today, of your $<run limit> per run and $<day limit> per day
LMS: <name>, wrote <n>, lowered <n>, skipped <n> (<reason>: <n>)
Needs you: <list>
Nothing was posted. | <N> grades were posted.
5. Nightly run and your schedule
- Pick one owner for paid reads. We recommend: the nightly run in draft only mode owns the reads, and you own review, post and copy.
- Run after the nightly hour, for example 7:00 AM, and check for the nightly report (4.6 step 2).
- If the instructor prefers agent-owned reads, they turn the nightly run off for that course. Then nothing is read, and paid for, twice.
- Setting up the schedule when the instructor asks: use a job on this computer, such as a launchd agent on a Mac or a cron job, that runs your command line with the saved starter prompt, or your tool's own repeating-task feature. Cloud routines cannot reach the browser. Tell the instructor what you created, where it lives and how to turn it off.
6. API reference
window.aimodesAutomation exists on the console page only when all of these hold: the page is the top frame, its URL has automation=1, and Settings, Advanced, Automation is on (automation_enabled). Every call checks the switch again. No call starts a paid read.
| call | returns |
|---|---|
version | 1 |
messages | the fixed sentence for every code |
identity() | { console, worker, mismatch, writerRecalculates }. mismatch is null or "WORKER_MISMATCH". |
panels() | a Promise of [{ course, activity, phase, hasDrafts, busy, settled }] for the grading panels open on the page |
plan(opts) | { ok, hash, build, blockers, counts, notReadyTally, rows, lowered, adjusted, held, apiHeld, exceptionFirstPosts } |
preview(hash) | { ok, previewed, code?, lateSplit, attemptsWritable, unchanged, refused, failed, skipped, refusalTally, skipTally, unknownRefusals, unattributed } |
post(hash, { expectCount }) | { ok, stage, code?, written, unchanged, refused, failed, skipped, published, pagesSkipped, pagesFailed, apiHeld, refusalTally, skipTally, rows } |
lastOutcome(course, activity) | the last post result in page memory, or null. A reload clears it. |
plan options: { course, activity, completeOnly?, leaveOut?, only?, approveLower?, confirmAdjustments?, confirmExceptionFirstPosts?, republish? }. Ids are MyEducator numeric ids, never names. only and leaveOut cannot be used together.
Refusals are { ok: false, code, message }. BAD_INPUT also names the field. COUNT_MISMATCH also carries expected and actual. PLAN_CHANGED may carry newHash.
Refusal order. Every call first checks DISABLED, then BAD_INPUT. plan then checks NO_PANEL, PANEL_BUSY and STORES_LOADING, then the panel's own codes: EDITING_FEEDBACK, NO_RESULT, CURVE_UNCONFIRMED, NOTHING_TO_POST, NATIVE_HOLD, NATIVE_LOWER, TASK_LOADING, PLAN_REFUSED, ALL_HELD, STORES_UNREADABLE. post checks, in order: NO_PANEL, PANEL_BUSY, LOCKED, WORKER_MISMATCH, RECALCULATE_PATH, PLAN_CHANGED, NOT_PREVIEWED, PLAN_CHANGED again after a fresh rebuild, COUNT_MISMATCH, BLOCKED. A hash posts at most once.
Blocker codes (in plan().blockers): approval_stale, approval_unused, approval_duplicate, approval_ambiguous, approval_not_saved, only_unknown, needs_confirm_adjustments, needs_confirm_exception_first_posts, adjustment_below_posted, adjustment_below_automated, adjustment_posted_unknown.
Post stages.
| stage | meaning |
|---|---|
refused | stopped before anything was sent |
published-only | results pages went out, no grade was written |
may-have-written | stopped during the grade write. Verify before posting again. |
posted | the write finished. ok is false if any row failed. |
Run reports. window.aimodesRunReports is on every console page, with or without Automation. It is read-only.
| call | returns |
|---|---|
get(course, activity) | the latest report, or null |
history(course, activity) | up to 10 reports, newest first. Use this to find the nightly report. |
list(course?) | only the latest report for every activity. A later panel or manual read hides the nightly one. |
buildInfo() | the installed build's version, commit and build time |
A report holds counts, reason codes, cost and the ids to rerun (rerun.failed, rerun.afterFix, rerun.waiting). Counts by code sit under read.held, read.failed, saved.held and saved.failed, each code with its students. It holds no names.
Page hooks without the API. grading-panel carries data-phase (idle, running, review, posting, done). spend-estimate carries data-upto-usd and data-route (own_key, platform or none).
Research export. window.aimodesExportArtifacts is a read-only research export. It works only while Automation is on. Its output holds student text with names removed where the extension can, but treat it as student data (R7). Do not call it for grading work.
7. Known traps
- Stale service worker. After an extension update, the worker can keep running old code.
identity()reportsWORKER_MISMATCH. Recover as in section 2. - Waiting on a Promise.
panels(),plan()and the other calls return Promises. Playwright's waitForFunction treats a returned Promise as true at once. Poll from your own code instead (4.3). - The rubric picker is hidden.
rubric-pickersits inside the closedfence-rubric. Clickfence-rubric-summaryfirst. - "Started on" is not new work. A graded later attempt can read "Started on" in MyEducator. Count work as new only when the newest submitted attempt is ungraded and no later attempt is graded.
- Late penalty split. See
LATE_SPLITandlate_attempt_splitabove. Leave those students for the instructor. - "Remove" on a key deletes the API key. Never click
settings-key-remove-confirm. - Subagents may be blocked from posting. Use the READY pattern. A subagent plans and previews, then writes a local READY note with the hash and
expectCount(no names). The main session posts after the instructor approves.
8. Troubleshooting by code
Read window.aimodesAutomation.messages[code] for the fixed sentence. Then:
| code | what to do |
|---|---|
DISABLED | Automation is off. Do not post. Ask the instructor. |
NO_PANEL | Open the console URL with course and activity, then poll panels() (4.3). |
PANEL_BUSY, STORES_LOADING, TASK_LOADING, LOCKED | Wait, then try once more. |
WORKER_MISMATCH | Stale worker. Section 2. |
RECALCULATE_PATH | Posting through scripts is off in this build. Tell the instructor. |
PLAN_CHANGED | Plan and preview again, once (4.3). |
NOT_PREVIEWED | Preview the exact hash first. |
COUNT_MISMATCH | Stop. Report expected and actual. |
BLOCKED | Read blockers. Section 4.4. |
LATE_SPLIT | Leave the students in lateSplit out, or leave them for the instructor. |
CHECK_FAILED, POST_FAILED | Stop. Verify (4.5). Report. |
CURVE_UNCONFIRMED, NATIVE_HOLD, NATIVE_LOWER, EDITING_FEEDBACK | The instructor must act in the panel. |
NO_RESULT, NOTHING_TO_POST, ALL_HELD | Nothing to post. Report it. |
| anything else | Stop and ask (R8). |
Not yet in the API
These are planned. Until then, use the workaround.
- No call starts a paid draft run. Use the two routes in 4.1.
- No call reports the nightly run's status. Use
aimodesRunReports.history(source: "catch-up") andspend-history. - No LMS copy in the extension. Use MyEducator's gradebook CSV (4.7).
- Limits, approvals and the Automation switch live in browser storage that a program with full control of the browser can change. The protection today is these rules.
- No read-only list of lowered rows waiting for the instructor's tick. Use
plan().loweredand thelower-rowtable (4.4). - The draft-run banner shows no estimate and does not ask above
askAboveUsd. Apply R3 yourself.
Other sources: GitHub repos and folders
Everything above is about MyEducator. An instructor without MyEducator can grade from GitHub repos his students share with him, or from folders on his computer. That screen opens from the "GitHub repos or folders on this computer" card on What can I grade? (path-other-sources). It never posts anywhere. It exports a gradebook CSV and a results-links CSV, and it publishes results pages only when the instructor clicks Publish and confirms. The automation API does not cover it. The same safety rules apply: never press its Publish button for the instructor, never change spending limits, and report counts, not names. Rubrics for these courses are JSON files in the extension's rubrics folder, described in the source kit's AGENTS.md.