Passive Capture

contxt scan

Extract @decision, @pattern, and @context annotations from code comments across your codebase.

Comment Syntax

Contxt recognizes three annotation tags anywhere inside a code comment. An optional [category] bracket and a | key: value metadata trailer are both optional but encouraged for richer indexing.

// @decision Use Prisma over Drizzle | rationale: better TS support
// @decision [infrastructure] JWT in httpOnly cookies | rationale: stateless, refresh rotation
// @pattern API route: Zod schema → validate → handler → typed response
// @pattern [api] Error handler | when: transient failures
// @context Currently building user onboarding flow

Multi-line Support

An annotation can span multiple lines. Any immediately following comment line that starts with two slashes and at least two spaces (not a new tag) is treated as a continuation of the previous annotation.

// @decision Use server-side rendering for all marketing pages
//   rationale: SEO is critical; hydration cost on static pages
//   is unjustified. RSC removes the client bundle entirely.

// @pattern Wrap every fetch in a try/catch and log with context
//   Include: requestId, userId, endpoint, durationMs

Supported Languages

Language(s)Comment styleExample
JavaScript / TypeScript//// @decision ...
Python / Ruby / Shell## @pattern ...
SQL---- @context ...
CSS / C / C++ / Java/* ... *//* @decision ... */
HTML / JSX / Svelte<!-- ... --><!-- @pattern ... -->

CLI Flags

FlagDefaultDescription
contxt scan—Scan the current directory recursively. Respects .contxtignore and .gitignore.
--path <dir>./Limit the scan to a specific directory or file.
--dry-runfalsePrint discovered annotations to stdout without writing any drafts. Useful for verifying syntax.
--auto-confirmfalseSkip the draft review queue and immediately confirm all discovered annotations as active entries.

Deduplication

Every annotation is content-hashed on first scan. On subsequent runs, Contxt compares the current hash against the stored value and assigns one of four statuses:

Scan complete — 47 files, 12 annotations

  NEW       src/lib/auth.ts:14     @decision JWT in httpOnly cookies
  NEW       src/api/users.ts:3     @pattern  API route handler
  UPDATED   src/lib/db.ts:1        @decision Use Prisma for database
  UNCHANGED src/components/Button.tsx:22  @pattern  Button variants
  STALE     src/lib/old-cache.ts   @decision Redis caching strategy

3 drafts queued — run contxt review to confirm

.contxtignore

Place a .contxtignore file in your project root to exclude paths from scanning. Syntax is identical to .gitignore — glob patterns, one per line. Contxt also respects your existing .gitignore automatically.

# .contxtignore
*.generated.ts
src/vendor/**
**/__tests__/**
**/fixtures/**
src/lib/legacy-migrations.ts