https://github.com/truecourse-ai/truecourse
AI-powered architecture analysis and code intelligence. Detects circular deps, layer violations, dead modules, and more. Web UI + CLI.
https://github.com/truecourse-ai/truecourse
ai architecture code-analysis code-quality developer-tools linter static-analysis typescript
Last synced: about 1 month ago
JSON representation
AI-powered architecture analysis and code intelligence. Detects circular deps, layer violations, dead modules, and more. Web UI + CLI.
- Host: GitHub
- URL: https://github.com/truecourse-ai/truecourse
- Owner: truecourse-ai
- License: mit
- Created: 2026-03-13T03:52:40.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T00:27:03.000Z (about 1 month ago)
- Last Synced: 2026-04-14T01:12:58.831Z (about 1 month ago)
- Topics: ai, architecture, code-analysis, code-quality, developer-tools, linter, static-analysis, typescript
- Language: TypeScript
- Size: 28.3 MB
- Stars: 98
- Watchers: 0
- Forks: 11
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
AI Architecture & Code Intelligence Platform
1,200+ deterministic rules, 100 LLM rules. JavaScript, TypeScript, Python.
TrueCourse analyzes your codebase architecture and code to detect violations that traditional linters miss — circular dependencies, layer violations, dead modules, race conditions, security anti-patterns, and more. It combines tree-sitter static analysis with LLM-powered review to surface findings with fix suggestions.
## What it catches
**Architecture** — Circular dependencies, layer violations, god modules, dead modules, tight coupling, cross-service imports
**Code quality** — Magic numbers, empty catch, console.log, cognitive complexity, unused variables, redundant code, missing type hints
**Security** — SQL injection, hardcoded secrets, eval usage, insecure random, XSS, path traversal, unsafe deserialization
**Bugs** — Race conditions, type mismatches, mutable defaults, implicit optional, off-by-one, unchecked returns
**Performance** — N+1 queries, O(n²) string concat, unnecessary allocations, missing pagination, sync I/O in async
**Reliability** — Unhandled promises, resource leaks, missing timeouts, swallowed exceptions, unsafe error handling
**Database** — Missing indexes, missing transactions, lazy loading in loops, raw SQL bypassing ORM, schema issues
**Style** — Import ordering, naming conventions, docstring completeness, formatting preferences
## Quick Start
```bash
cd
npx truecourse analyze # Runs the full analysis in-process
npx truecourse dashboard # Opens the web UI in your browser
```
No setup step. TrueCourse creates `.truecourse/` in your repo on first analyze and stores everything there as plain JSON files — no database, no daemon.
TrueCourse uses the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) for LLM-powered rules. If `claude` isn't on your PATH, deterministic rules still run and LLM rules are skipped.
## CLI Commands
```bash
# Analysis
truecourse analyze # Analyze current repo
truecourse analyze --diff # New/resolved violations from your uncommitted changes
truecourse list # Show violations from latest analysis
truecourse list --all # Show all violations (no pagination)
truecourse list --diff # Show diff check results
truecourse add # Register repo without analyzing
# Dashboard (web UI)
truecourse dashboard # Start + open the dashboard
truecourse dashboard stop # Stop the dashboard
truecourse dashboard status # Show dashboard status
truecourse dashboard logs # Tail dashboard logs (service mode only)
truecourse dashboard uninstall # Remove the background service
```
### Rules
Configure which rule categories and LLM-powered rules are enabled per repository:
```bash
# Categories
truecourse rules categories # Show enabled/disabled
truecourse rules categories --enable style # Enable a category
truecourse rules categories --disable style # Disable a category
# LLM-powered rules
truecourse rules llm # Show LLM rules status
truecourse rules llm --enable # Enable LLM rules
truecourse rules llm --disable # Disable LLM rules
```
### Git Hooks
TrueCourse can install a pre-commit hook that blocks commits with critical violations:
```bash
truecourse hooks install # Install pre-commit hook
truecourse hooks uninstall # Remove pre-commit hook
truecourse hooks status # Show hook installation status
```
### Telemetry
TrueCourse collects anonymous usage data to improve the product. It is automatically disabled in CI environments.
```bash
truecourse telemetry status # Check telemetry status
truecourse telemetry disable # Opt out of anonymous telemetry
truecourse telemetry enable # Opt back in
```
## Analysis Rules
TrueCourse ships with **1,200+ deterministic rules** and **100 LLM rules** across 8 categories:
| Category | Deterministic | LLM | Total |
|---|---:|---:|---:|
| Security | 150+ | 1 | 150+ |
| Bugs | 250+ | 4 | 250+ |
| Architecture | 30+ | 7 | 40+ |
| Code Quality | 500+ | 3 | 500+ |
| Performance | 50+ | 10 | 60+ |
| Reliability | 40+ | 10 | 50+ |
| Database | 30+ | 5 | 35+ |
| Style | 50+ | — | 50+ |
**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.
## Claude Code Skills
TrueCourse includes [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for conversational analysis from within Claude Code.
Run `truecourse add` to install skills to `.claude/skills/truecourse/` in your project.
| Skill | What it does |
|---|---|
| `/truecourse-analyze` | Runs analysis or diff check, summarizes results |
| `/truecourse-list` | Shows full violation details |
| `/truecourse-fix` | Lists fixable violations, applies changes |
## Language Support
| Language | Status |
|---|---|
| JavaScript / TypeScript | Supported |
| Python | Supported |
| C# | Planned |
| Go | Planned |
| Rust | Planned |
| PHP | Planned |
## Prerequisites
- Node.js >= 20
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH. Deterministic rules run without it, LLM-powered rules need it.
## Development
```bash
git clone https://github.com/truecourse-ai/truecourse.git
cd truecourse
pnpm install
pnpm dev # Start dashboard at http://localhost:3000 (server on :3001, Vite on :3000)
pnpm test # Run tests
pnpm build # Build all packages
```
`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`).
## Telemetry
TrueCourse collects anonymous usage data (event type, language, file count range, OS). No source code, file paths, or violation details are collected. Opt out with `truecourse telemetry disable` or `TRUECOURSE_TELEMETRY=0`.
## License
MIT