truecourse · truecourse-ai/truecourse GitHub

Turns the documentation you already write into tests that run. A failing test means your product and your docs disagree, and names the section.

Tests that prove your product does what your documentation promises.

[!WARNING] The truecourse npm package (the CLI) is deprecated and no longer maintained. TrueCourse is becoming an IDE for Product Owners, and the first step is letting them turn their documentation into end-to-end tests. This README describes the product as it is now.

TrueCourse reads the documentation a team already writes (PRDs, ADRs, READMEs, a documentation site) and turns it into tests that run.

It curates those documents into a corpus of claims, works out the flows a user takes through the product, writes a test for each one against the real interfaces, and runs them. A failing test means the product and the documentation disagree, and it names which claim.

For more details, check our documentation at docs.truecourse.dev.

Run it locally

Setup

cp .env.example .env
echo "TRUECOURSE_MODE=local" >> .env
echo "TRUECOURSE_LLM_TRANSPORT=claude-code" >> .env
docker compose up -d    # starts Postgres; skip if you already run one, and set DATABASE_URL in .env to it
pnpm install

In .env, set TRUECOURSE_SECRET_KEY to a random string of 32 or more characters, such as the output of openssl rand -base64 32. Everything else in it already works as is.

Run

pnpm dev    # http://localhost:3000

TrueCourse runs on your Claude Code login, so it needs the claude binary on your PATH and signed in. Everything runs on claude-opus-5-5; set TRUECOURSE_MODEL in .env to use another model.

On Claude Code, a repository's product is brought up by a session that has a shell in the clone: it installs and builds the repository, starts its servers and containers on this machine, and leaves three scripts that do it again. The product comes up empty. Tests are then written as Playwright specs against the running product, each with a seed of its own that creates the accounts and data its flow starts from, so no two tests share any. That needs @playwright/test and its browser:

pnpm --filter @truecourse/guard-runner exec playwright install chromium

Every generate also runs the tests the repository already has against the commit it cloned. A test that no longer ends the way it was accepted is opened again: repaired when the product only changed how a step is reached, kept as a finding when the product stopped doing what the document says. Before any test is kept, a reviewer with a fresh context reads it against the documents it was written from. Pull request checks are not wired on this path yet.

TRUECOURSE_MODE=local runs without sign-in, and folders on this machine can be connected as repositories.

First stop is Settings › Workspace: say what your product is, in one sentence. Documentation is kept or dropped by whether it describes that product, so nothing connects (no repository, no documentation source, no scan) until the workspace has said it.

Pull request checks

TrueCourse checks pull requests for documentation conflicts and test failures, then reports the results in GitHub. Connect your repository through the GitHub App, then turn on Check pull requests in the repository's Settings. It is off by default.

GitHub App needs Pull requests: read and Checks: read and write permissions, plus subscriptions to the Pull request, Check run and Check suite events.

Connect Claude Code

The server has an MCP endpoint, /mcp, that lets Claude Code read the workspace (documents, conflicts, flows, runs, failures, coverage, dependencies, sources) and make the decisions the dashboard offers.

claude mcp add --transport http truecourse http://localhost:3001/mcp

Telemetry

TrueCourse sends usage analytics to PostHog: which actions are taken and pageviews, never your documents, keys or tokens. To turn it off, add this to .env:

POSTHOG_DISABLED=1

Contributing

CONTRIBUTING.md has the development setup, the project structure and what makes a good pull request.

Community

Join the TrueCourse Discord to ask questions, share feedback, and follow what's shipping.

Contact

Questions, feedback, or security reports: Mushegh Gevorgyan, mushegh@truecourse.dev.

License

MIT for everything outside ee/. See LICENSE.

Enterprise for ee/, which holds the document Connections, the extra repository providers and multiple workspaces. Free to read and modify for development; production use needs a subscription. See ee/LICENSE.