schoolsoft-agent

SchoolSoft for AI agents. Lets an agent (Claude, OpenCode, OpenClaw, Hermes, Pi, …) read a guardian's SchoolSoft data: schedule, lunch menu, assignments, news and the message inbox. Login is BankID in your own browser; nothing is automated around it, and the session is stored encrypted on your machine.

Two surfaces, one core. Pick the one your host supports or you prefer:

Both are the same npm package and behave identically, because every capability is defined once as an operation and both surfaces are generated from that list. See docs/architecture.md.

Independent project. SchoolSoft is a trademark of SchoolSoft AB. This is an independent, MIT-licensed community project: it is not affiliated with, endorsed by, or supported by SchoolSoft AB, and SchoolSoft has no involvement in it. It talks to SchoolSoft through the same unofficial APIs the SchoolSoft app uses; read Trademark and independence and Privacy before installing.

Start here: which AI app do you use?

You do not need to be technical. Pick your app; each guide is a few steps with copy-paste commands, written for parents.

Not sure? Start with the getting-started overview: what you need, the three things that happen on first use, and the words you will meet. When something does not work, Troubleshooting explains every message in plain language.

Related MCP server: ecole-directe-mcp

Try it in a terminal first (optional)

Prerequisite: Node.js 22 or newer.

npx -y schoolsoft-agent configure --query "Rösjöskolan"   # finds your school
npx -y schoolsoft-agent login                              # BankID in your browser
npx -y schoolsoft-agent get-schedule --pretty              # this week's schedule

Every command is in the command reference; every crucial one is also a make target in a checkout (make help). Messages come in Swedish when your system language is Swedish (or with SCHOOLSOFT_LANG=sv), always as "what went wrong" plus "Next: what to do".

What you can ask

• "Vad har Ella på schemat på fredag?"

• "Vad är det till lunch i veckan?"

• "Har vi fått några meddelanden från skolan?"

• "Vilka läxor finns den här veckan?"

The agent picks the child (list_children), the week, and the right operation. Contact lists, bookings and shared files have no data feed at SchoolSoft; those are read through an optional hidden browser (npx -y schoolsoft-agent browser install, once). Grades, student documents, absence reports and assessment criteria additionally sit behind SchoolSoft's "log in again" gate and need npx -y schoolsoft-agent login --web once, a normal web login in a browser window. Both extras are explained step by step in Get started. Full list of what an agent can ask for: MCP tools · CLI commands.

How login works

1. The agent calls login. Your browser opens SchoolSoft's real login page for guardians.

2. You authenticate with BankID (or whatever your municipality offers). The integration never sees credentials.

3. SchoolSoft redirects to http://127.0.0.1:43117/callback with a one-time code; the integration exchanges it for tokens and session cookies.

4. Tokens are stored encrypted (AES-256-GCM, key file 0600) and refreshed silently. You log in again only when the refresh token expires.

Login problems are covered in Troubleshooting. Details and diagrams: docs/architecture.md. What SchoolSoft actually exposes: docs/schoolsoft-api.md.

Privacy

• Your children's data is only ever sent to SchoolSoft and to the AI model you are talking to, in the conversation you started. No telemetry, no third party.

• The only thing stored on disk is the encrypted session (tokens, cookies, the list of your children with names and class) under your platform's config directory (schoolsoft-agent doctor shows where). schoolsoft-agent logout deletes it.

• Nothing is written to log files. Diagnostics on stderr never include personal data.

• This is unofficial automated access. Check SchoolSoft's terms of service for your municipality before relying on it.

• Nothing is ever written to SchoolSoft: every tool is read-only, and the hidden browser blocks any request that could change something.

Development

git clone https://github.com/grimen/schoolsoft-agent && cd schoolsoft-agent
make setup          # node check + npm ci + git hooks
make check          # lint, typecheck, format, boundaries, manifests, tests with coverage
make e2e-artifact   # shipped-artifact + host E2E in a sandbox (what CI runs)
make e2e            # live suite against SchoolSoft (needs configure + one login)
make help           # everything else

Layout, boundaries, design principles and the test pyramid are in docs/architecture.md; conventions, hooks and the CI stages in CONTRIBUTING.md; how versions ship in docs/releasing.md; the rules every coding agent follows in AGENTS.md. What we know about SchoolSoft's unofficial APIs and web pages, page by page, is in docs/schoolsoft-api.md. Adding an operation touches one file under src/core/operations/ plus the registry; both surfaces and the docs follow.

Roadmap

• Write operations: report absence, send message (separate spec; confirmation-gated).

• Remote transport (streamable HTTP with per-user storage) so ChatGPT and hosted agents can use it.

• Claude Desktop extension directory listing.

• Other school portals: everything vendor-specific sits behind one SchoolProvider seam (src/providers/), so a second Swedish portal is a new provider directory, not a rewrite. All of them end their login in BankID, which the core already handles two ways.

Trademark and independence

SchoolSoft is a trademark of SchoolSoft AB. This is an independent, MIT-licensed community project: it is not affiliated with, endorsed by, or supported by SchoolSoft AB, and SchoolSoft has no involvement in it. The name is used only to describe what the software connects to. BankID is a trademark of Finansiell ID-Teknik BID AB; Claude, ChatGPT, OpenCode, OpenClaw, Hermes and Pi are trademarks of their respective owners. All are named descriptively, and none of these organisations is involved in or endorses this project. No logos or brand assets are used. If any rights holder objects to a use of their name, open an issue and it will be addressed.

License

MIT © Jonas Grimfelt. Runtime dependency on elias4044/ssp-node (MIT) for HTTP helpers. The unofficial API knowledge and its sources are documented in docs/schoolsoft-api.md.