Search code, repositories, users, issues, pull requests...

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

[Sign up](https://github.com/signup?refcta=Sign+up&refloc=header+logged+out&refpage=%2F%3Cuser-name%3E%2F%3Crepo-name%3E&source=header-repo&sourcerepo=ravikiranyalamanchili%2Fcontext-debt)

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert

ravikiranyalamanchili/ [context-debt](https://github.com/ravikiranyalamanchili/context-debt) Public

Notifications You must be signed in to change notification settings
[Fork\\

0](https://github.com/login?return_to=%2Fravikiranyalamanchili%2Fcontext-debt)

[Star\\

3](https://github.com/login?return_to=%2Fravikiranyalamanchili%2Fcontext-debt)

Additional navigation options

ravikiranyalamanchili/context-debt

main

[1 Branch](https://github.com/ravikiranyalamanchili/context-debt/branches) [3 Tags](https://github.com/ravikiranyalamanchili/context-debt/tags)

Go to Branches page Go to Tags page

Go to file

Code

Open more actions menu

Folders and files

| ## Latest commit ![ravikiranyalamanchili](https://github.com/ravikiranyalamanchili)ravikiranyalamanchili 0.1.3 3 weeks agoMar 26, 2026 6650913 · 3 weeks agoMar 26, 2026 ## History 13 Commits Open commit details View commit history for this file. 13 Commits |

| src | src | Remove unimplemented 'context-debt fix' suggestion from report footer | 3 weeks agoMar 26, 2026 |

| View all files |

Repository files navigation

Context Debt

Permalink: Context Debt

Early alpha — expect rough edges. Stars and issues welcome.

![npm version](https://www.npmjs.com/package/@context-debt/core)![license](https://github.com/ravikiranyalamanchili/context-debt/blob/main/LICENSE)![node](https://github.com/ravikiranyalamanchili/context-debt/blob/main/package.json)

Your AI agents are working from a lie. Every time you rename a function, refactor a class, or add a new module — your CLAUDE.md, .cursorrules, or Copilot instructions fall further out of sync with reality. The AI keeps confidently using the old names. This is context drift, and it gets worse every day you don't fix it.

Context Debt parses your TypeScript AST and compares it against your AI config files. It produces a drift score (0–100%) and a precise list of what's stale, what's changed signature, and what the AI is missing entirely — so you can fix it before it costs you.

![Context Debt audit on tRPC](https://github.com/ravikiranyalamanchili/context-debt/blob/main/assets/demo.png)

Installation

Permalink: Installation

Requires Node.js 18+.

Plain Text

npm install @context-debt/core

Or run directly without installing:

Plain Text

npx @context-debt/core audit /path/to/your/repo

Usage

Permalink: Usage

CLI

Permalink: CLI

Plain Text

# Audit the current directory
npx context-debt audit .

# Audit a specific repo
npx context-debt audit /path/to/typescript-repo

# Write a JSON report to disk (for history tracking)
npx context-debt audit . --output .context-debt/report.json

# Fail with exit code 1 if drift exceeds a threshold (for CI)
npx context-debt audit . --max-drift 25

# Both together
npx context-debt audit . --output .context-debt/report.json --max-drift 25

Tracking drift over time

Permalink: Tracking drift over time

Commit .context-debt/report.json alongside your code. Each run overwrites it with the latest report, so you can diff it in PRs to see exactly what drifted:

Plain Text

# In your git diff you'll see:
-  "driftScore": 12,
+  "driftScore": 34,

Add .context-debt/report.json to version control but add the directory to .gitignore exceptions:

Plain Text

# Track the drift report in git
!.context-debt/report.json

CI — fail PRs above a drift threshold

Permalink: CI — fail PRs above a drift threshold

Create .github/workflows/context-debt.yml in your repo:

Plain Text

name: Context Debt

on:
  push:
    branches: [main]
  pull_request:

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run drift audit
        run: npx @context-debt/core audit . --output .context-debt/report.json --max-drift 25

      - name: Upload drift report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: drift-report
          path: .context-debt/report.json

This will:

Run on every push to main and every PR
Write the JSON report as a CI artifact (downloadable from the Actions tab)
Exit non-zero and fail the PR if drift exceeds 25%

SDK

Permalink: SDK

Plain Text

const { RepoIndex } = require('@context-debt/core');

const index = new RepoIndex({ repoPath: '/path/to/repo' });

// Run a full drift audit
const report = await index.audit();
console.log(report.driftScore);   // e.g. 34
console.log(report.severity);     // 'clean' | 'low' | 'degraded' | 'high' | 'critical'
console.log(report.findings.stale);    // symbols that no longer exist
console.log(report.findings.drifted);  // symbols whose signatures changed
console.log(report.findings.missing);  // exported symbols absent from your AI config

// Get a compressed, freshness-guaranteed context slice for a specific task
const context = await index.getContext({ task: 'Refactor the auth module' });
console.log(context.skeleton);         // TypeScript skeleton ready to inject into an agent
console.log(context.tokenEstimate);    // Rough token count

// Get all symbols from a specific file
const symbols = await index.getFileSymbols('./src/auth.ts');
console.log(symbols.functions);
console.log(symbols.classes);

// Force a re-scan (clears in-memory cache)
await index.refresh();

How it works

Permalink: How it works

Plain Text

cli.js
  └── config-parser.js   reads .cursorrules / CLAUDE.md / copilot-instructions.md
  └── scanner.js         walks the repo, finds all .ts/.tsx files
        └── extractor.js  parses each file with tree-sitter, extracts symbols
  └── scorer.js          compares claimed vs actual → DriftReport

index.js                 public SDK wrapper (RepoIndex class)

Data flow:

config-parser.js reads your AI config files and extracts every symbol reference — function calls, class names, type annotations, backtick spans
scanner.js walks the repo and calls extractor.js per file to get the live AST snapshot
scorer.jscompares the two and assigns each claimed symbol a state:

FRESH — symbol exists with a matching signature
DRIFTED — symbol exists but its signature changed
STALE — symbol not found anywhere in the codebase
MISSING — exported symbol exists in the codebase but is absent from all AI configs

A drift score (0–100%) is computed as (stale + drifted) / total claimed

Drift score severity bands

Permalink: Drift score severity bands

| Score | Severity | Meaning |

| 0% | clean | All claimed symbols are fresh |

| 1–15% | low | Minor drift — acceptable |

| 16–35% | degraded | Noticeable drift — worth fixing |

| 36–60% | high | Significant drift — agents will make mistakes |

| 61–100% | critical | Severe drift — AI context is unreliable |

Supported AI config files

Permalink: Supported AI config files

| File | Tool |

| CLAUDE.md | Claude Code |

| .cursorrules | Cursor |

| .github/copilot-instructions.md | GitHub Copilot |

| copilot-instructions.md | GitHub Copilot |

| AGENTS.md | General |

| AI_CONTEXT.md | General |

| .ai-context | General |

DriftReport shape

Permalink: DriftReport shape

Plain Text

interface DriftReport {
  driftScore: number;          // 0–100
  severity: 'clean' | 'low' | 'degraded' | 'high' | 'critical';
  summary: {
    totalClaimed: number;
    fresh: number;
    stale: number;
    drifted: number;
    missing: number;
    filesScanned: number;
    totalSymbolsFound: number;
  };
  findings: {
    stale:   Finding[];
    drifted: Finding[];
    missing: Finding[];
    fresh:   Finding[];
  };
  generatedAt: string;
}

ContextSlice shape (from getContext())

Permalink: ContextSlice shape (from getContext())

Plain Text

interface ContextSlice {
  task: string;
  symbolCount: number;
  skeleton: string;        // TypeScript skeleton to inject into your agent
  symbols: Symbol[];       // Structured symbol data
  freshAt: string;
  tokenEstimate: number;   // Rough token count (skeleton.length / 4)
}

Design principles

Permalink: Design principles

Deterministic, not probabilistic. Drift detection uses AST parsing — if UserService.createUser was renamed to AuthService.registerUser, the AST knows this with certainty. There are no LLMs in the core pipeline.

Local-first. All parsing happens on your machine. No source code is sent to any external API.

Precision over recall. A false positive destroys trust immediately. The config parser errs toward precision (~90%) over recall (~80%). Each finding carries a confidence field (high / medium / low) — the CLI shows only high and medium by default.

Current limitations

Permalink: Current limitations

TypeScript only. Python and Go support is planned (tree-sitter grammars exist for both).
No disk caching. AST results are cached in memory per RepoIndex instance. Large repos (2000+ files) re-scan on every run.
Monorepo path aliases not resolved.tsconfig.json path aliases (e.g. @/components/...) are not yet resolved. Barrel re-exports may cause symbol duplication.
Config parser is heuristic. Regex on free-form text — treat it as ~80% recall, ~90% precision.
Relevance scoring is keyword overlap.getContext() scores relevance by matching task description tokens against symbol names. Works well for explicit task descriptions; naive for vague ones. Embeddings in v2.

Roadmap

Permalink: Roadmap

Test on large public repos (tRPC, Prisma, create-t3-app)
Monorepo path alias resolution (parse tsconfig.jsonpaths)
Barrel file re-export deduplication
Disk caching (write to .context-debt/cache/)
Python support
MCP server wrapper (`auditdrift` and `getrepo_context` as MCP tools)

Dependencies

Permalink: Dependencies

[tree-sitter](https://github.com/tree-sitter/tree-sitter) — C-based parser framework with Node.js bindings
[tree-sitter-typescript](https://github.com/tree-sitter/tree-sitter-typescript) — TypeScript grammar for tree-sitter

No other runtime dependencies.