Groundwork

by jonathana-harris
5
4
3
2
1
Score: 32/100

Description

A test learning workflow

Reviews

No reviews yet.

Stats

1
stars
276
downloads
0
forks
46
days
6
days
6
days
139
total PRs
6
open PRs
0
closed PRs
133
merged PRs
1
total issues
1
open issues
0
closed issues
353
commits

Latest Version

7 days ago

Changelog

Obsidian community plugin release. After the plugin is listed, the website’s Add to Obsidian button opens it. The release assets are main.js, manifest.json, and styles.css.

README file from

Github

Groundwork

Groundwork is a tutor inside Obsidian. It maps the concepts you're learning, marks how well you know each one, and plans the next step toward a goal.

Install it from Obsidian's community plugins. Sign in at groundworklearn.com. A free plan is included. Paid plans are optional.

Install

You need Obsidian on a desktop computer.

  1. Download Obsidian for your computer from Get started, install it, and create a vault.
  2. In Obsidian, open Settings → Community plugins. Turn community plugins on if they are off, and trust the vault once. Choose Browse, search for Groundwork, then Install and Enable. You can also install from the community plugin page.
  3. Sign in with Google at groundworklearn.com. Free is ready. On your account page, choose Connect Groundwork. That opens Obsidian with a one-time code. If the link doesn’t open, paste the code into Groundwork.

Groundwork does not run on a phone. You can sign up on your phone, then copy the setup link or scan the QR code and finish on a computer.

Plans

A free plan is included. Paid plans ($6 and $20 per month) unlock a model you already pay for, or models Groundwork runs.

  • Free stays on Light, with a monthly limit. Your account shows the share of that month you've used. Decks you already have stay available to review. Heavy and new flashcards are on the paid plans.
  • Bring your own model is $6 per month. It uses the Claude subscription on your computer, or a key from OpenRouter, Anthropic, Google, xAI, or OpenAI. That is also what Heavy means on this plan. Model use on that subscription or key is billed by that provider. The $6 covers Groundwork. Flashcards are included.
  • Groundwork is $20 per month. Groundwork runs the models. Light or Heavy, switched in the plugin. Flashcards are included.

Paid plans are billed on the Groundwork website through Stripe. You can change or cancel a paid plan from Manage billing on your account page.

What you can do

  • Set a goal with a due date. If you don't name a date, a new goal is due in 14 days. The plan starts from the foundations and works up.
  • See a concept map. Each concept is marked solid, shaky, learning, rusty, or not started. The goal sits in red at the top.
  • Take diagnostic quiz cards at levels 1 to 5. A careless slip isn't counted as a gap.
  • Study a flashcard deck in one sitting. Again shows the card next, Hard brings it back later in that sitting, and Good or Easy sets it aside. Those ratings do not set the marks on the concept map.
  • Drop in lecture slides, homework, a study guide, or a practice exam. Groundwork turns that into an exam goal.
  • Chat with the tutor in Obsidian. Math renders in LaTeX. You can attach slides, PDFs, or images from folders you allow.

Progress stays on your account and syncs across computers. Your vault stays on your computer. The tutor reads only the vault folders you allow in settings.

Payment, account, and network

A free plan is included. Paid plans ($6 and $20 per month) unlock Bring your own model, or Groundwork running the models. Paid plans are billed on the Groundwork website through Stripe.

An account is required before the tutor will run. Sign in with Google on that website. Tutor memory — concept notes, goals, quiz evidence, chats, and the learner profile — is stored on the account.

The plugin uses the network for these services:

  • Groundwork (https://groundwork-6f9ca.web.app in production builds) stores the account, tutor memory, plan routing, and grades written answers. Sign-in happens in the browser on the Groundwork website. Connect Groundwork opens Obsidian with a one-time code. The plugin exchanges that code for a session. Privacy: groundworklearn.com/privacy.
  • Google (https://securetoken.googleapis.com) refreshes the website sign-in into an ID token the plugin sends to Groundwork. A one-time code is exchanged at https://identitytoolkit.googleapis.com for that same kind of session.
  • Google Fonts (https://fonts.googleapis.com) loads Jost for the Groundwork panel stylesheet.
  • Stripe — billing for the $6 and $20 plans happens on the website, not inside the plugin.
  • Anthropic, through Claude Code on this computer, runs the tutor when you use your own Claude subscription. Claude Code may reach Anthropic's API and related sign-in endpoints. On hosted Groundwork plans, model calls go through your account API instead. Bring-your-own-model keys saved on the account are used only on the Groundwork server (OpenRouter, Anthropic, Google, xAI, or OpenAI), not sent from the plugin.

The first time the plugin runs, it sends a random install id to Groundwork so the site can count installs. That request does not include notes, chats, or anything from the vault. The privacy page describes it. On the desktop the plugin uses the filesystem (node:fs) to see whether the Claude Code executable is installed, and it starts that program with child_process (through the bundled Agent SDK) so the tutor can run under your Claude subscription. Claude Code's working directory is the vault. Those reads and that process run only when the account is on the Claude subscription on this computer. The plugin reads PATH (and, on Windows, APPDATA) only to find that executable when Obsidian was not launched from a shell. It does not read the hostname or network interfaces. On that same local-model path, the bundled Agent SDK may read the OS account name (os.userInfo) as a fallback label for Claude Code's files, and it reads Claude Code's own environment variables (such as CLAUDE_CONFIG_DIR). That name is not sent to Groundwork. Device labels default to Obsidian until you set one in the panel.

Reading a PDF uses pdf.js. That library includes qcms, a color-management routine compiled to WebAssembly, for ICC color profiles. The plugin does not set a wasm URL, so qcms is not downloaded or run. The code is in the plugin bundle. PDF text stays on this computer.

The separate groundwork CLI (not the plugin) reads and writes ~/.config/groundwork/config.json and can run git to sync the vault. It does not read other files outside the vault. The only notes the tutor opens as extra context are in vault folders you pick in settings. Python figures that need a local runtime stay in the Obsidian window; the plugin does not download a Python package with a dynamic import().

The plugin is desktop-only.

Obsidian community plugin

The section above — payment, a required account, network services, and files outside the vault — is what the Obsidian community plugin directory asks this README to state. Groundwork is MIT licensed.

The plugin is laid out so it can be submitted:

Requirement Where
manifest.json with id, name, version, minAppVersion, description, author, authorUrl, isDesktopOnly repository root, identical to packages/obsidian-plugin/manifest.json. The community directory reads the root file.
versions.json at the repo root, mapping each version to its minAppVersion versions.json
An open-source license LICENSE
Release assets main.js, manifest.json, styles.css a tag equal to the manifest version (0.2.0, no v prefix) runs .github/workflows/release-plugin.yml

node scripts/check-community-plugin.mjs checks that list. The plugin id is groundwork, which is also the community install folder.

From the website, Connect Groundwork opens Obsidian and connects this device with a one-time code. Manual install: community plugin page.

The plugin is desktop-only because it bundles Node-based tooling (Claude Code / Agent SDK) and does not run on mobile Obsidian. Publishing the map is off until you sign in and turn it on. That request goes to the Groundwork account API (https://groundwork-6f9ca.web.app in production builds).

The Groundwork panel uses the website's dark look: Jost, and the red, amber, blue, and green status dots. Learn, Concept map, and Goals are three views of the same memory. A goal has a due date and a weight for each concept. The concept map is Groundwork's own map of that goal, not Obsidian's graph view. The rest of Obsidian keeps its theme.

The manifest, release checklist, and node scripts/check-community-plugin.mjs are described in docs/development.md.

For developers

Clone, setup, the CLI, and how the repo is laid out: docs/development.md.