cubewhy/skid-homework: an AI homework solver that runs in the browser

What Skid-Homework solves, and for whom

The README frames the problem plainly: homework takes time, and the author lists sleep and mental health among the costs. Skid-Homework is the workaround. You photograph or upload a problem, the app hands it to a large language model, and the answer comes back in the browser with optional diagrams.

The target user is not a student looking for a polished mobile app. It is someone who wants a self-hosted interface, is comfortable generating an API key, and cares about input ergonomics more than about a curated answer database. The README's own comparison section is blunt about the trade-off: against traditional question-bank software it lists computer availability, keyboard shortcuts designed for homework, drawing support, and the absence of ads and tracking. It does not claim better answer accuracy.

There is also an explicit stance on academic integrity. The disclaimer says the project encourages compliance with academic honesty and asks users not to use it in exams, while noting that under GPLv3 the developer cannot control redistribution. That framing matters for anyone evaluating whether to deploy it inside a school network.

How the request actually flows: browser, model, tool calls

There is no backend inference service. The README states that everything runs inside the browser, and that the project will never ask you to download desktop software. That single design decision explains most of the app's behaviour, including its failure modes.

Uploaded images and PDFs are sent to the AI provider directly from the page, with no server-side OCR step. The README is explicit that the site currently sends the image straight to the model and invites better proposals. So the pipeline is: file input, prompt assembly, provider call, streamed answer, optional tool calls for diagrams.

Those diagram tools are where the architecture gets interesting. The app supports JSXGraph (marked unstable), Mermaid, function-plot (marked as being phased out in favour of JSXGraph), and raw SVG. The model decides which one to invoke, which means rendering quality depends on the model's tool-calling behaviour, not on a deterministic template. The README warns that some models emit incorrect tool calls.

Because the provider is called from the client, CORS is a first-class constraint. The FAQ lists CORS as the likely cause of request failures when the key and endpoint are correct, and suggests a reverse proxy. That is the cost of having no server: the browser's security model becomes part of your deployment.

Installing Skid-Homework and solving your first problem

The README gives three routes: the official instance, a Vercel deploy button, and Docker. For local development it lists three commands. Clone the repository, install dependencies with pnpm, then start the dev server:

pnpm i
pnpm run dev

The README does not state a default port for `pnpm run dev`, but the Docker instructions say the container exposes port 3000, so expect the dev server on the usual Next.js port. Once the page loads, open settings with Ctrl+5 and enter your Gemini API key or an OpenAI-compatible endpoint. The README points to Google AI Studio for obtaining a Gemini key and notes that the Gemini key is free to apply for.

If you prefer a container, the README publishes images to GitHub Container Registry and asks you to substitute a real commit hash:

docker run -p 3000:3000 ghcr.io/cubewhy/skid-homework:sha-<commit_hash>

Or as a Compose service, with the same substitution:

services:
  skidhw:
    image: ghcr.io/cubewhy/skid-homework:sha-<commit_hash>
    ports:
      - 3000:3000

Building the image yourself is also documented, and the container opens port 3000:

docker build -t skid-homework .

With the app running, the workflow is keyboard-only. Ctrl+1 uploads a file, Ctrl+2 takes a photo, Ctrl+3 submits to the AI, and Ctrl+4 clears all files. Space moves to the next question and Shift+Space goes back. Ctrl+X opens the global prompt editor, which is where you set the answer style, since the README states the site ships no default style. Pressing `/` asks the AI to improve the current answer.

The latency, the CORS wall, and the missing default prompt

Three limitations are stated by the project itself, and they are the ones that decide whether this tool fits you.

First, speed. The FAQ answers the question of why it is so slow by pointing out that the software uses an LLM rather than a question bank, that LLM responses take longer, and that there is no good optimization available. The suggested mitigations are reducing the thinking budget, with the caveat that too small a value can make the AI produce wrong results, and trimming the prompt so the model skips explanations. That is a real trade-off between latency and answer quality, and the project does not pretend otherwise.

Second, CORS. If your API endpoint does not send permissive CORS headers, the browser call fails. The README's troubleshooting list for repeated failures is: check whether the API allows CORS, check whether your IP is blocked by the provider, check whether the key is valid, and check the DevTools console. The suggested fix is a local reverse proxy, which means you are running infrastructure anyway. A self-hosted deployment does not remove this constraint, because the request still originates in the browser.

Third, no default answer style. The README says the site deliberately ships without one, which makes it less ready out of the box than a question-bank app but more customizable. If you want a tool where you type a question and get a conventionally formatted answer with no configuration, this is the wrong tool. You will be writing a prompt before the first useful answer.

There is also a persistence caveat: local persistence of parsed results is described as experimental, and the README tells users to clear site data if problems appear.

How it differs from a question-bank app such as 作业帮

The README addresses this comparison directly. Traditional Chinese homework apps such as 作业帮 are built on indexed question banks: a photo is matched against stored problems and the stored solution is returned. That gives fast, consistent answers for problems already in the bank, and nothing useful for problems that are not.

Skid-Homework takes the opposite approach. Every submission is a fresh generation, so a novel problem is handled as well as the model handles it, and the same problem may produce differently worded answers on two runs. The README's own framing is that this makes it slower and less consistent, but also that the answer is not confined to a standard solution, and that you can set the style yourself.

The practical difference is where the failure lives. A question-bank app fails by finding no match. Skid-Homework fails by generating something plausible but wrong, or by emitting a broken diagram tool call. The README's answer to the second case is the `/` shortcut for improving an answer, and the global prompt editor for systemic adjustments. There is no correctness guarantee in either direction, and the project does not offer one.

Maintenance, deployment cost, and the GPL-3.0 terms

The repository is not archived, and the last push was on 2026-09-14. The README carries a warning about a breaking change: the service was migrated to Next.js, and deployments must account for the configuration differences. Anyone upgrading from an older checkout should read that as the first item, not the last.

The stack is heavier than the feature list suggests. package.json shows a Next.js app with Radix UI primitives, Tailwind, Emotion, Shiki, React Spring, gesture libraries, and the ADB packages that back the experimental WebUSB screenshot feature. The build script chains `next build` with `serwist build`, and there are separate scripts for Cloudflare via OpenNext and Wrangler, plus a flake.nix for Nix users. That is a lot of surface area for a tool whose core job is sending an image to a model.

Upgrade cost concentrates in two places. The Next.js migration warning means config drift between versions is expected. And the i18n types are generated: the README says to run a command after editing i18n files to update types.

pnpx i18next-cli types

On licensing, the project is GPL-3.0, and the README states you are allowed to use, share and modify it. The disclaimer adds that under GPLv3 the developer has no power to control distribution of the software. If you plan to run a modified version as a network service, the copyleft obligations are a question for your own legal review, not something this article can settle. Note also that the Docker images are tagged by commit hash, so pinning a version means tracking hashes rather than semver tags.

Editorial conclusion

Adopt it if you already hold a Gemini or OpenAI-compatible API key, want a keyboard-first solver you host yourself, and accept that answers come from a model rather than a question bank. Skip it if you need a built-in default answer style, a question bank, or a guarantee that a drawing tool call will render. Verify first that your API endpoint sends CORS headers the browser accepts, and that the model you point it at can emit the tool calls the diagram renderers expect.

Frequently asked questions

Official sources

1. cubewhy/skid-homework on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README