Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt

Use this file to discover all available pages before exploring further.

The Driftless loop has five phases. Every command, every event, every scan fits into one of them.

​
Phase 1: Scan

The scanner extracts components from your TypeScript codebase. It reads the AST and identifies:
  • NestJS: endpoints, guards, services, modules, DTOs, interceptors, pipes
  • Next.js: pages, layouts, route handlers, server actions, middleware
  • React: components and hooks
Scans happen in two ways:
  • On demand: driftless init or driftless scan
  • On push: The GitHub App triggers a scan when code is pushed to tracked branches
The scanner uses a two-pass streaming pipeline that keeps memory at O(largest file), so it scales to large repos without OOMing. 
driftless init              # full baseline scan, uploads to Cloud
driftless scan --diff       # diff scan: what changed since last baseline

​
Phase 2: Observe

The GitHub App watches pushes and PRs. On every push to a tracked branch, it matches changed files against team topics. On PRs, it posts sticky context comments listing the relevant topics for the changed files. 
# PR comment example (auto-posted by GitHub App):
# "Driftless: 3 topics cover files in this PR:
#  - auth-flow [code-context]: JWT validation and role-based access
#  - user-service [code-context]: User CRUD and profile management
#  - api-guards [domain-map]: Global and route-level guard architecture"
Pushes to tracked branches can mark topics as stale. PRs themselves do not trigger staleness; they trigger observation only.

​
Phase 3: Contextualize

The API stores extracted facts and the team writes context on top of them. Topics are created with what/how/decisions/gotchas, anchored to files via patterns or explicit paths. Typed relations connect topics into a knowledge graph. 
driftless context add "auth-flow" \
  --what "JWT validation and role-based access control" \
  --how "RS256 asymmetric keys, guard decodes, role decorator checks" \
  --pattern "src/auth/**" \
  --tags auth,security \
  --kind code-context

driftless context update auth-flow \
  --decision "Chose RS256 over HS256 so services can verify without shared secret" \
  --gotcha "Token refresh is NOT handled by this guard; see [[token-refresh]]" \
  --rel depends_on:token-refresh
Wiki-links ([[slug]]) inside any free-text field are auto-parsed into forward and backward references in the graph.

​
Phase 4: Deliver

Context reaches agents and humans through CLI commands: 
driftless sync                              # what drifted since you last looked
driftless context get auth-flow             # full context for one topic
driftless context get --diff                # context for your current local changes
driftless context load --files "a.ts,b.ts"  # topics + coverage for specific files
driftless graph file src/auth/guard.ts      # entrypoints, upstream, downstream, contracts
driftless graph impact --files "a.ts,b.ts"  # what these changes can break

​
Phase 5: Check

When code changes on tracked branches, topics whose anchored files overlap get marked stale. The staleness reason lists the specific files and commit that triggered it. 
driftless sync                    # shows stale topics alongside other changes
driftless context doctor          # full health audit: staleness, coverage, orphaned topics
driftless context get --diff      # staleness status for your current local changes
Structural staleness goes beyond file matching. It detects deleted endpoint files, removed guards, and services that no longer exist in the codebase. Coverage reports show what is documented vs. what is not, with risk-based prioritization.

​
System Architecture

Driftless is built as six components that compose into a single knowledge layer. Each component has one responsibility; the API orchestrates them. Scanner (@driftless/scanner): Static AST analysis that extracts components from TypeScript codebases. Identifies endpoints, guards, services, modules, and DTOs from NestJS; pages, layouts, route handlers, and server actions from Next.js; components and hooks from React. Uses a two-pass streaming pipeline with O(largest file) memory. Zero dependencies besides TypeScript and ts-morph. API (NestJS, Render): REST API hosted at api.driftless.icu. Authenticates via API keys (x-api-key) and Clerk. A global WorkspaceGuard enforces workspace-level authorization across all endpoints. Exposes 45 endpoints for scans, context CRUD, graph queries, sync, and dashboard data. CLI (@driftless-sh/cli, npm): 24 commands including init, sync, context CRUD, graph, install-skill, doctor, and branches. Bundled with esbuild for fast startup. The primary interface agents and developers use to interact with Driftless. GitHub App: Posts context comments on PRs to surface relevant topics for changed files. Marks topics as stale when code is pushed to tracked branches, keeping the knowledge graph honest about drift. Agent Skill (SKILL.md): Instructions for coding agents (Claude Code, Cursor). Teaches the sync to load to edit to persist workflow so agents automatically check and contribute context during coding sessions. Dashboard (React + Vite, Vercel): Visual interface for workspace health, context browsing, architecture maps, and topic coverage. Companion to the CLI for team-level visibility. 
CLI ──► API (NestJS) ──► Supabase (Postgres)
         ▲
         │
Scanner ─┤  GitHub App ─┤  Dashboard
Tech stack: NestJS, TypeScript, Turborepo, Supabase, Clerk, Render, and Vercel.