{"id":47727361,"url":"https://github.com/truecourse-ai/truecourse","last_synced_at":"2026-06-06T00:02:27.178Z","repository":{"id":344291798,"uuid":"1180451756","full_name":"truecourse-ai/truecourse","owner":"truecourse-ai","description":"AI-powered architecture analysis and code intelligence. Detects circular deps, layer violations, dead modules, and more. Web UI + CLI.","archived":false,"fork":false,"pushed_at":"2026-04-14T00:27:03.000Z","size":29670,"stargazers_count":98,"open_issues_count":4,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T01:12:58.831Z","etag":null,"topics":["ai","architecture","code-analysis","code-quality","developer-tools","linter","static-analysis","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/truecourse-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-13T03:52:40.000Z","updated_at":"2026-04-14T01:08:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/truecourse-ai/truecourse","commit_stats":null,"previous_names":["truecourse-ai/truecourse"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/truecourse-ai/truecourse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truecourse-ai%2Ftruecourse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truecourse-ai%2Ftruecourse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truecourse-ai%2Ftruecourse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truecourse-ai%2Ftruecourse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truecourse-ai","download_url":"https://codeload.github.com/truecourse-ai/truecourse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truecourse-ai%2Ftruecourse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31785682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","architecture","code-analysis","code-quality","developer-tools","linter","static-analysis","typescript"],"created_at":"2026-04-02T20:51:06.794Z","updated_at":"2026-06-06T00:02:27.162Z","avatar_url":"https://github.com/truecourse-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"TrueCourse\" width=\"300\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI Architecture \u0026 Code Intelligence Platform\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e1,200+ deterministic rules, 100 LLM rules. JavaScript, TypeScript, Python.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/truecourse-ai/truecourse/actions/workflows/test.yml\"\u003e\u003cimg src=\"https://github.com/truecourse-ai/truecourse/actions/workflows/test.yml/badge.svg\" alt=\"Tests\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/truecourse\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/truecourse\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/truecourse-ai/truecourse/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/truecourse-ai/truecourse\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/TanxB63arz\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-join-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nTrueCourse catches two classes of defect, through two independent tools — use either on its own or both together:\n\n- **Code defects** (`truecourse analyze`) — from the categories linters cover (unused code, style, missing types) through to ones they don't reach: circular dependencies, layer violations, dead modules, race conditions, security anti-patterns, performance footguns. Tree-sitter analysis combined with LLM review.\n- **Business-logic drift** (`truecourse verify`) — when the implementation no longer matches what the docs say it should do. Wrong response codes, missing entity fields, illegal state transitions, bypassed auth, silently-dropped effects, formulas that have lost an input. TrueCourse extracts a contract from your PRDs/ADRs/READMEs and checks the code against it.\n\nBoth store their results under `.truecourse/` and surface them in a shared [dashboard](#dashboard-web-ui) for human review, with plain-text CLI output an agent can read directly.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"TrueCourse Screenshot\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\nJump to: **[1. Analyze](#1-analyze--code-intelligence)** · **[2. Spec → Verify](#2-spec--verify--business-logic-drift)** · **[Dashboard](#dashboard-web-ui)**\n\nNo setup step and no database: TrueCourse creates `.truecourse/` in your repo on first use and stores everything there as plain JSON files. It uses the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) for LLM-powered work — if `claude` isn't on your PATH, deterministic analysis still runs and LLM-dependent features are skipped.\n\n---\n\n# 1. Analyze — code intelligence\n\nStatic + LLM analysis of your code: architecture, security, bugs, performance, and more.\n\n## Quick Start\n\n```bash\ncd \u003cyour-repo\u003e\nnpx truecourse analyze      # Runs the full analysis in-process\nnpx truecourse list         # Show the violations it found\n```\n\nThe first analyze creates `.truecourse/` and stores results as plain JSON. View them visually with [`truecourse dashboard`](#dashboard-web-ui).\n\n## Setup\n\nThe first `truecourse analyze` creates `.truecourse/` in your repo. Three files inside it are committable and travel with the repo:\n\n| File | Purpose |\n|---|---|\n| `LATEST.json` | Most recent analysis snapshot. Doubles as the baseline for `truecourse analyze --diff` and the pre-commit hook. |\n| `config.json` | Per-repo rule categories and LLM toggles. |\n| `hooks.yaml` | Pre-commit hook policy (created by `truecourse hooks install`). |\n\nEverything else (`analyses/`, `diff.json`, `history.json`, `ui-state.json`, `logs/`, `.analyze.lock`) is local-only and added to `.truecourse/.gitignore` automatically.\n\n**First time, on `main`:**\n\n```bash\ntruecourse analyze\ngit add .truecourse/LATEST.json .truecourse/config.json\ngit commit -m \"add truecourse baseline\"\n```\n\n**Refreshing the baseline:** re-run `truecourse analyze` after merging to `main` and commit the updated `LATEST.json`. **Don't commit `LATEST.json` from feature branches** — two PRs both updating it will conflict on a large generated JSON.\n\n### Worktrees and fresh clones\n\n`LATEST.json` is tracked, so `git worktree add ../feat-x` and fresh clones inherit the baseline through git. `truecourse analyze --diff` and the pre-commit hook both work on the first commit in a new worktree — no per-checkout cold-start. Inside a worktree, run `truecourse analyze --diff` to see what your in-flight changes introduce relative to `main`'s committed baseline; the diff result lands in `.truecourse/diff.json` (gitignored, per-checkout).\n\n## What it catches\n\n**Architecture** — Circular dependencies, layer violations, god modules, dead modules, tight coupling, cross-service imports\n\n**Code quality** — Magic numbers, empty catch, console.log, cognitive complexity, unused variables, redundant code, missing type hints\n\n**Security** — SQL injection, hardcoded secrets, eval usage, insecure random, XSS, path traversal, unsafe deserialization\n\n**Bugs** — Race conditions, type mismatches, mutable defaults, implicit optional, off-by-one, unchecked returns\n\n**Performance** — N+1 queries, O(n²) string concat, unnecessary allocations, missing pagination, sync I/O in async\n\n**Reliability** — Unhandled promises, resource leaks, missing timeouts, swallowed exceptions, unsafe error handling\n\n**Database** — Missing indexes, missing transactions, lazy loading in loops, raw SQL bypassing ORM, schema issues\n\n**Style** — Import ordering, naming conventions, docstring completeness, formatting preferences\n\n### Rule coverage\n\nTrueCourse ships with **1,200+ deterministic rules** and **100 LLM rules** across 8 categories:\n\n| Category | Deterministic | LLM | Total |\n|---|---:|---:|---:|\n| Security | 150+ | 1 | 150+ |\n| Bugs | 250+ | 4 | 250+ |\n| Architecture | 30+ | 7 | 40+ |\n| Code Quality | 500+ | 3 | 500+ |\n| Performance | 50+ | 10 | 60+ |\n| Reliability | 40+ | 10 | 50+ |\n| Database | 30+ | 5 | 35+ |\n| Style | 50+ | — | 50+ |\n\n**Deterministic rules** run via tree-sitter AST visitors — fast, zero-cost, no API calls. **LLM rules** send source code to the configured LLM for semantic analysis — deeper but requires an LLM provider.\n\n## Commands\n\n```bash\ntruecourse analyze                    # Analyze current repo (prompts before stashing dirty trees)\ntruecourse analyze --stash            # Pre-approve stashing pending changes (CI-friendly)\ntruecourse analyze --no-stash         # Analyze working tree as-is, no stash\ntruecourse analyze --diff             # New/resolved violations from your uncommitted changes\ntruecourse list                       # Show violations from latest analysis\ntruecourse list --all                 # Show all violations (no pagination)\ntruecourse list --diff                # Show diff check results\ntruecourse add                        # Register repo without analyzing\n```\n\n### Rules\n\nConfigure which rule categories and LLM-powered rules are enabled per repository:\n\n```bash\n# Categories\ntruecourse rules categories                    # Show enabled/disabled\ntruecourse rules categories --enable style     # Enable a category\ntruecourse rules categories --disable style    # Disable a category\n\n# LLM-powered rules\ntruecourse rules llm                           # Show LLM rules status\ntruecourse rules llm --enable                  # Enable LLM rules\ntruecourse rules llm --disable                 # Disable LLM rules\n\n# Individual rules\ntruecourse rules list                          # List rules with on/off status\ntruecourse rules list --disabled               # Show only disabled rules\ntruecourse rules disable \u003cruleKey\u003e             # Disable a single rule\ntruecourse rules enable \u003cruleKey\u003e              # Re-enable a single rule\ntruecourse rules reset [ruleKey]               # Clear per-rule overrides (one or all)\n```\n\nDisabled rules are skipped at analyze time (no detection cost, no LLM calls) and any existing violations from them are hidden from the dashboard and `truecourse list` until re-enabled. The list of disabled rule keys lives in `\u003crepo\u003e/.truecourse/config.json` under `disabledRules`, which is intended to be committed.\n\nIn the dashboard you can also toggle rules from the Rules panel (Shield icon in the top-right) or silence a noisy rule directly from any violation card via the **⋮** menu → **Disable rule for this repo**.\n\n### Git Hooks\n\nTrueCourse can install a pre-commit hook that blocks commits introducing new violations at or above a configured severity:\n\n```bash\ntruecourse hooks install              # Install pre-commit hook\ntruecourse hooks uninstall            # Remove pre-commit hook\ntruecourse hooks status               # Show hook status + config\n```\n\nOn every commit the hook runs `truecourse analyze --diff` against the repo's last full analysis and blocks if any newly-introduced violation matches the configured block severities. **Commits will take as long as a full diff analysis** — on large repos that can be tens of seconds per commit. `truecourse hooks install` warns you and requires confirmation before writing the hook.\n\nThe hook diffs against `.truecourse/LATEST.json`, so you need a committed baseline first — see [Setup](#setup). Without it the hook has nothing to diff against.\n\n**Bypass:** `git commit --no-verify` (standard git).\n\n**Configuration** — `hooks install` seeds `\u003crepo\u003e/.truecourse/hooks.yaml` with starter defaults; commit the file so your team shares one policy. The hook reads only from this file — if you delete it, the hook warns and passes every commit (no hidden code-level defaults). Current shape:\n\n```yaml\npre-commit:\n  block-on: [critical, high]   # severities. Valid: info|low|medium|high|critical\n  llm: false                   # run LLM rules on every commit (tokens per commit)\n```\n\n---\n\n# 2. Spec → Verify — business-logic drift\n\nTrueCourse builds a machine-readable spec from your docs and verifies the code against it — catching where the implementation has drifted from documented intent. This is a separate pipeline from `analyze`: it answers a different question, has different prerequisites (it reads your docs), and runs on a different time scale.\n\n\u003e **Prerequisite:** the contract extractor and conflict resolver shell out to the Claude Code CLI (`claude -p`). Install Claude Code and sign in once before running `spec scan` or `contracts generate`.\n\n## Quick Start\n\n```bash\ncd \u003cyour-repo\u003e\ntruecourse spec scan                    # Read docs → extract claims → surface conflicts\ntruecourse spec resolve --all-defaults  # Accept the recommended pick on each conflict\ntruecourse contracts generate           # Canonical spec → .tc contract artifacts\ntruecourse verify                       # Check code against the contracts → drifts\n```\n\nResolve conflicts and review drifts visually in the [dashboard](#dashboard-web-ui)'s BL Drift section, or drive every step from the CLI.\n\n\u003e Like `analyze`, the spec → contracts → verify track requires a **git repository** — TrueCourse's baselines are commit-anchored (committable `LATEST.json`, diff vs HEAD, stashing the committed state). On a non-git folder these commands stop with a clear message and the dashboard hides their actions.\n\n## How it works\n\nThree stages run in order, each producing artifacts the next consumes:\n\n**1. Spec consolidation** — Walks every `.md` file in the repo (PRDs, ADRs, RFCs, READMEs, design notes; `.truecourse/`, `node_modules/`, `.git/` etc. are skipped). An LLM relevance filter drops obvious non-spec material (task lists, research logs, AI agent prompts). For the docs that remain, an LLM extracts structured claims per block and groups them by `(topic, subject)`. Agreements auto-merge; genuine disagreements surface as **conflicts** in the dashboard with a plain-English explanation of what differs. Output: `.truecourse/specs/claims.json` (the structured snapshot every downstream stage consumes — modules + per-claim content + provenance) and `.truecourse/specs/decisions.json` (the user's resolutions, version chains, and overrides — committable).\n\nAuto-resolve rules cut the conflict count substantially: byte-identical content, status-tolerant duplicates, same-file consolidation, docKind-dominance pickups, and detected version chains. [Plan](docs/contracts/PLAN_CONFLICT_RESOLUTION.md).\n\n**2. Contract extraction** — Reads `claims.json` and emits `.truecourse/contracts/*.tc` files in a hand-written DSL covering 13 artifact kinds: `operation`, `entity`, `enum`, `state-machine`, `auth-requirement`, `authorization-rule`, `error-envelope`, `pagination-contract`, `idempotency-contract`, `effect-group`, `formula`, plus `unenforceable-obligation` for prose the verifier can't structurally check. A post-extraction **repair pass** validates structural completeness and re-prompts the LLM to fix deficient artifacts (missing forbids clauses, broad role selectors, unresolved cross-references). On the bundled fixture this hits **22/22 planted bugs with 0 false positives**.\n\n**3. Verification** — Parses the contracts, walks the source tree, and runs per-kind comparators (operations, entities, state machines, etc.). Drifts surface in the dashboard alongside code violations, and on the CLI through `truecourse verify`. It's its own command — not a stage of `truecourse analyze`.\n\n**4. Inference** — The mirror image of verification. `verify` asks \"the spec says X — does the code do X?\"; `truecourse infer` asks \"the code does X — does any spec mention X?\". It runs the code-side extractors *un-driven by a spec*, subtracts whatever the authored contracts already cover, and writes the remainder to `.truecourse/contracts/_inferred/` as `.tc` artifacts tagged with an `inferred-from \"\u003ccode-path\u003e\" a..b` provenance line and a `confidence` level (instead of the authored `origin SOURCE \"section\" a..b`). It covers the full artifact spread — undocumented endpoints, entities (from ORM schema), enums, named constants, query policies, emitted events, computed formulas, architecture choices, and the cross-cutting conventions (auth, pagination, idempotency, error envelope). Confidence reflects fidelity: a value read straight from code is `high`; a synthesized convention (e.g. an assumed auth scheme) is a `low`-confidence draft to confirm. Because coverage is computed from authored contracts only, a decision drops out of `_inferred/` the moment it's documented — the directory is a shrinking backlog of \"decisions your code made that your docs never recorded\". Inferred contracts are descriptive, not prescriptive, so `verify` skips `_inferred/` by default.\n\n## What it catches\n\nOperations whose responses, status codes, or headers don't match the spec. Entities with missing or mistyped fields. Immutability and lifecycle violations on state machines. Missing or forbidden side-effect emissions. Auth requirements bypassed. Pagination, idempotency, and error-envelope contracts violated. Formulas producing wrong results from drifted inputs.\n\n## Setup\n\nThe spec and a verify baseline are committable so they travel with the repo; everything else is local-only. Per-repo layout under `.truecourse/`:\n\n```\n.truecourse/\n├── specs/                  ← canonical spec (committable)\n│   ├── claims.json          ← structured snapshot: modules + claims + provenance\n│   └── decisions.json       ← user resolutions + version chains + manual includes\n├── contracts/               ← generated TC contract artifacts (gitignored by default)\n│   └── _inferred/            ← reverse-engineered, undocumented decisions (`truecourse infer`)\n├── verifier/                ← drift store (mirrors analyze; `truecourse verify`)\n│   ├── runs/                 ← per-run drift snapshots (gitignored)\n│   ├── LATEST.json           ← current drift state + diff baseline (committable)\n│   ├── history.json          ← per-run summaries (gitignored)\n│   └── diff.json             ← current-vs-baseline drift diff (gitignored)\n└── .cache/                  ← LLM + slice cache (gitignored)\n```\n\nLike analyze, `verifier/LATEST.json` is the committable baseline — commit it after merging to `main` (re-run `truecourse verify`, commit the result), not from feature branches. `truecourse verify --diff` then shows the drifts your uncommitted changes add or resolve against it.\n\n## Commands\n\n```bash\n# Spec consolidation (docs → canonical spec)\ntruecourse spec scan                              # Read docs, extract claims, surface conflicts, write claims.json\ntruecourse spec resolve --all-defaults            # Accept the engine's recommended pick on every open conflict\ntruecourse spec status                            # Summary: docs, claims, modules, pending decisions\n\n# Conflict resolution (also available in the dashboard Spec tab)\ntruecourse spec conflicts list                    # List open conflicts (add --decided / --all)\ntruecourse spec conflicts show \u003cid\u003e               # Full detail for one conflict\ntruecourse spec conflicts pick \u003cid\u003e \u003cindex\u003e       # Resolve by picking a candidate\ntruecourse spec conflicts custom \u003cid\u003e --text \"…\"  # Resolve with a custom answer\ntruecourse spec conflicts revoke \u003cid\u003e             # Re-open a decided conflict\ntruecourse spec chains add --older A --newer B    # Manually mark a version chain (escape hatch)\ntruecourse spec chains list / remove …\ntruecourse spec docs skipped                      # Docs the LLM relevance filter excluded\ntruecourse spec docs include \u003cpath\u003e               # Force-include a skipped doc\ntruecourse spec docs uninclude \u003cpath\u003e\n\n# Contract extraction (canonical spec → .tc artifacts)\ntruecourse contracts generate                     # Extract / re-extract TC contract files\ntruecourse contracts list                         # List artifacts (kind · identity · location)\ntruecourse contracts list --inferred / --authored # Only reverse-engineered (_inferred/) / only authored\ntruecourse contracts validate                     # Parse + resolve TC files; report unresolved refs\n\n# Verification (code against contracts)\ntruecourse verify                                 # Full run: stashes dirty tree (prompts), writes verifier/runs + LATEST + history\ntruecourse verify --diff                          # Git diff: working-tree drifts vs committed baseline (added/resolved/unchanged)\ntruecourse verify --stash / --no-stash            # Pre-approve / skip stashing on a full run\ntruecourse drifts list                            # List drifts from the latest verify (paginated; reads LATEST, no re-run)\ntruecourse drifts list --all                      # Show every drift (no pagination)\ntruecourse drifts list --offset 20 / --severity critical,high  # Page through / filter by severity\n\n# Inference (code → inferred contracts) — reverse-engineer undocumented decisions\ntruecourse infer                                  # Write inferred .tc files to contracts/_inferred/\ntruecourse infer --dry-run                        # Report what would be written, touch nothing\ntruecourse contracts list --inferred              # Review what infer produced (kind · confidence · code location)\n```\n\n---\n\n# Dashboard (web UI)\n\nOne web UI for both capabilities — browse code findings and business-logic drift side by side, with the architecture graph, analytics, and the spec/contracts/verify workflow.\n\n```bash\ntruecourse dashboard                  # Start + open the dashboard\ntruecourse dashboard --reconfigure    # Re-prompt for console vs background service mode\ntruecourse dashboard stop             # Stop the dashboard\ntruecourse dashboard status           # Show dashboard status\ntruecourse dashboard logs             # Tail dashboard logs (service mode only)\ntruecourse dashboard uninstall        # Remove the background service\n```\n\n- **Code Analysis** — architecture graph, violations list, severity/category analytics, code hotspots, trend over time; toggle rules and silence noisy ones inline.\n- **BL Drift** — the Spec tab walks you through resolving each conflict (pick / write custom / mark superseded / include skipped doc); Contracts shows the generated `.tc` artifacts; Verify shows the drift analytics + list, with a Runs history and a Normal / Git-Diff toggle.\n\n---\n\n# Common\n\n## Claude Code Skills\n\nTrueCourse includes [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for conversational analysis from within Claude Code.\n\nThe first `truecourse analyze` (or `truecourse add`) in a fresh repo asks whether to install skills into `.claude/skills/truecourse/`. Re-runs skip the prompt if skills are already present. Pass `--install-skills` / `--no-skills` to bypass the prompt explicitly.\n\n| Skill | What it does |\n|---|---|\n| `/truecourse-analyze` | Runs analysis or diff check, summarizes results |\n| `/truecourse-list` | Shows full violation details |\n| `/truecourse-fix` | Lists fixable violations, applies changes |\n| `/truecourse-hooks` | Installs, configures, or removes the pre-commit hook |\n\n## Language Support\n\n| Language | Status |\n|---|---|\n| JavaScript / TypeScript | Supported |\n| Python | Supported |\n| C# | Planned |\n| Go | Planned |\n| Rust | Planned |\n| PHP | Planned |\n\n## Prerequisites\n\n- Node.js \u003e= 20\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH — optional. The default `cli` transport spawns it for LLM-powered work; deterministic rules and the `agent` transport (below) don't need it.\n\n## LLM transport (`--llm-transport`)\n\nEvery LLM-powered step — `analyze`'s LLM rules, and the whole Spec → Verify pipeline (`spec scan`, `spec resolve`, `contracts generate`) — reaches the model through a pluggable **transport**, chosen with `--llm-transport`:\n\n| Mode | How it reaches the model | Needs |\n|---|---|---|\n| **`cli`** *(default)* | spawns `claude -p …` per call | the `claude` binary on PATH, signed in. No API key. |\n| **`agent`** | a **filesystem mailbox** under `--io \u003cdir\u003e` | nothing — no `claude` binary, no API key |\n\nIn **`agent`** mode the tool doesn't call the model itself: for each prompt it writes `requests/\u003cid\u003e.json` (`{ stage, system, user, schema, … }`) into the `--io` directory and waits for a matching `responses/\u003cid\u003e.json` (`{ text }`). An **orchestrating agent that is itself an LLM** — e.g. a [Claude Code routine](https://code.claude.com/docs/en/routines) — watches that directory and answers each prompt. This lets contract generation and `analyze`'s LLM rules run **inside a headless cloud session with no `claude` binary and no API key**.\n\n```bash\n# default: spawn the claude CLI\ntruecourse analyze --llm\ntruecourse contracts generate\n\n# agent transport: the tool parks prompts in ./io and an external agent answers them\ntruecourse analyze --llm --llm-transport agent --io ./io\ntruecourse spec scan          --llm-transport agent --io ./io\ntruecourse contracts generate --llm-transport agent --io ./io\n```\n\nAccepted by: `analyze`, `spec scan`, `spec resolve`, `contracts generate`. (On `analyze`, `--llm` / `--no-llm` is a *separate* flag — it decides **whether** LLM rules run; `--llm-transport` decides **how** to reach the model.) Both modes send identical prompts and parse identical schema-validated JSON — only the delivery differs.\n\n## Configuration\n\nTrueCourse talks to Claude Code via the `claude` CLI. You can tune how that interaction behaves — which binary to invoke, which model to pass, timeouts, retries, and how many `claude` processes to run in parallel — through environment variables.\n\nFor packaged installs (`npx truecourse` or `npm install -g truecourse`), the simplest place to set them is `~/.truecourse/.env`. The file is loaded automatically on every invocation:\n\n```\nCLAUDE_CODE_BINARY=claude             # override the `claude` binary on PATH\nCLAUDE_CODE_MODEL=                    # Claude Code --model flag (empty = default)\nCLAUDE_CODE_TIMEOUT_MS=120000         # per-call timeout (ms)\nCLAUDE_CODE_MAX_RETRIES=2             # retry attempts on parse/validation failure\nCLAUDE_CODE_MAX_CONCURRENCY=10        # max concurrent `claude` processes per run\n```\n\n**`CLAUDE_CODE_MAX_CONCURRENCY`** caps how many Claude CLI processes TrueCourse spawns in parallel during a single run. Default `10`. Raise it on CI runners with spare headroom; lower it on resource-constrained machines (e.g. 8 GB laptops, shared VMs) to avoid OOM on large repos. Must be a positive integer.\n\nFor a one-off override, prefix the command:\n\n```bash\nCLAUDE_CODE_MAX_CONCURRENCY=2 truecourse analyze\n```\n\n### Excluding files from analysis\n\nTrueCourse honors `.gitignore` automatically (including nested `.gitignore` files, `.git/info/exclude`, and your configured global excludes file).\n\nFor paths you want tracked in git but not analyzed — generated code, vendored snapshots, large fixtures — add a `.truecourseignore` at the repo root. Same syntax as `.gitignore`:\n\n```\n# generated\nsrc/generated/\n# vendored\nthird_party/\n# specific files\nscripts/ingest-epub.js\n```\n\nPatterns are anchored to the file's location, so `src/generated/` matches the top-level directory only; use `**/generated/` to match at any depth.\n\n## Telemetry\n\nTrueCourse collects anonymous usage data to improve the product — one event per command (`analyze`, `spec_scan`, `contracts_generate`, `verify`, `infer`), each carrying only coarse, bucketed counts (file/artifact/drift/decision *ranges*, duration range), the surface (CLI vs dashboard), OS, and tool version. No source code, file paths, identities, or violation/drift details are collected. It is automatically disabled in CI environments.\n\n```bash\ntruecourse telemetry status           # Check telemetry status\ntruecourse telemetry disable          # Opt out of anonymous telemetry\ntruecourse telemetry enable           # Opt back in\n```\n\nOr set `TRUECOURSE_TELEMETRY=0` to opt out.\n\n## Development\n\n```bash\ngit clone https://github.com/truecourse-ai/truecourse.git\ncd truecourse\npnpm install\npnpm dev                # Start dashboard at http://localhost:3000 (server on :3001, Vite on :3000)\npnpm test               # Run tests\npnpm build              # Build all packages\n```\n\n`pnpm dev` expects a `.truecourse/` folder at the repo root — created automatically on the first `truecourse analyze` against the repo (or simply `mkdir -p .truecourse`).\n\n## Community\n\nJoin the [TrueCourse Discord](https://discord.gg/TanxB63arz) to ask questions, share feedback, and follow what's shipping.\n\n## Contact\n\nQuestions, feedback, or security reports: **Mushegh Gevorgyan** — [mushegh@truecourse.dev](mailto:mushegh@truecourse.dev).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruecourse-ai%2Ftruecourse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruecourse-ai%2Ftruecourse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruecourse-ai%2Ftruecourse/lists"}