ctx-audit

ctx-audit is a repository memory governance tool for engineering teams working with AI coding agents.

It verifies that project context files (AGENTS.md, memory.md, .agent/graph.md) exist, stay aligned with the codebase, and remain a trustworthy source of truth — so agents can rely on curated knowledge instead of re-discovering architecture, conventions, and decisions from raw source on every session.

Zero dependencies, single script, three install paths.

Why ctx-audit?

• Decisions live in heads, not files. Architectural choices, past experiments, and settled debates are invisible to agents unless they're written down and kept current.
• Conventions are scattered. Build rules, lint constraints, and naming patterns are buried in commits, PRs, and Slack threads — not in a place agents can read.
• Agents re-scan everything. Without fresh context files, every session starts from zero: the agent reads hundreds of source files to reconstruct what your team already knows.
• Stale docs are worse than none. An agent that trusts an outdated AGENTS.md will make wrong assumptions with false confidence.

Before / After

| Without context files | With fresh context files | |---|---| | Agent reads hundreds of source files to understand structure | Agent reads curated AGENTS.md in seconds | | Conventions must be re-derived from code patterns | Hard constraints and conventions are explicit and verified | | Every session starts from zero | Decisions and rationale persist across sessions | | Agent may contradict past decisions | memory.md provides a trusted decision log |

What ctx-audit checks

Repository Memory Health

Verifies required context files exist and follow the last_synced_commit frontmatter convention that pins each file to the commit it was last verified against.

Context Freshness

Counts source commits since each file was last synced. Reports graduated staleness levels (FRESH, STALE?, STALE!, STALE) so you know exactly how much to trust each file before handing it to an agent.

Also detects stale-bump: a SHA update with no real content change — and dead references: paths mentioned in context files that no longer exist in the repo.

Context Efficiency

Estimates how compact your curated context is compared to an agent reading raw source. Uses a ~3.5 chars/token heuristic — fast, dependency-free, and directionally useful, but not exact. All token counts in the output are labeled est. to make this clear. The "baseline" estimate sums tracked source files up to a cap, which is a proxy for "an agent reading everything," not a guarantee of what any particular agent would actually do.

The savings ratio (e.g., 12.0x smaller) shows how much more compact the curated context is compared to reading raw source.

Supported Agent Ecosystem

| Agent | How to integrate | |---|---| | Claude Code | npx ctx-audit install — registers /ctx-audit skill and session trigger | | OpenAI Codex | Add npx ctx-audit --strict to your CI workflow | | Cursor | Add ctx-audit to your .cursorrules session preamble | | Gemini CLI | Reference AGENTS.md in your system prompt | | Windsurf | Add ctx-audit to Windsurf's pre-session hooks | | Aider | Pass --read AGENTS.md after verifying freshness |

Philosophy

• Context files should be explicit — written down, not inferred from code patterns.
• Context files should be version-controlled — treated as first-class engineering artifacts alongside source.
• Context files should be reviewable — changes go through the same PR process as code.
• Context files should be auditable — every file carries the commit it was last verified against.
• Context files should be trustworthy — agents that trust their context are faster, more accurate, and less likely to contradict past decisions.

Getting started in 60 seconds

# 1. Install skill into Claude Code + register trigger
npx ctx-audit install

# 2. Wire up a git pre-push guard
npx ctx-audit hook install

# 3. Tell agents in this repo to run it at session start
npx ctx-audit claude install

# 4. Scaffold AGENTS.md + memory.md (interactive — writes files directly)
npx ctx-audit --init

# 5. Run your first audit
npx ctx-audit

Install

npx (no install)

npx ctx-audit

Global install

npm i -g ctx-audit
ctx-audit

Agent skill (skills.sh)

npx skills add aryashreep/ctx-audit --skill ctx-audit

CI gate (GitHub Action)

# .github/workflows/ctx-audit.yml
- uses: aryashreep/ctx-audit@v1
  with:
    strict: "true"   # exit 1 on failure (default)
    json: "false"     # JSON output (default: false)

Or copy action/ctx-audit.yml into .github/workflows/ for the standalone workflow approach.

Subcommands

| Command | What it does | |---|---| | ctx-audit install | Copy skill to ~/.claude/skills/ctx-audit/, register /ctx-audit trigger in ~/.claude/CLAUDE.md | | ctx-audit hook install | Append npx ctx-audit --strict to .git/hooks/pre-push (idempotent) | | ctx-audit hook uninstall | Remove ctx-audit lines from pre-push hook | | ctx-audit hook status | Check whether the hook is installed | | ctx-audit claude install | Append a ## ctx-audit section to project CLAUDE.md (idempotent) | | ctx-audit claude uninstall | Remove the ctx-audit section from project CLAUDE.md | | ctx-audit benchmark | Print token savings in a focused, shareable format |

Flags

npx ctx-audit              # human-readable report (colored in TTY)
npx ctx-audit --json       # machine-readable JSON
npx ctx-audit --strict     # exit 1 on any failure (for CI)
npx ctx-audit --ci         # alias for --strict --json
npx ctx-audit --init       # write AGENTS.md + memory.md to disk (interactive TTY)
                           # or print templates to stdout when piped
npx ctx-audit --help       # show usage and exit

Layout

ctx-audit/
├── package.json
├── action.yml              composite GitHub Action
├── scripts/audit.mjs       core logic (no dependencies, plain Node >=18)
├── skill/SKILL.md          agent-invoked path (30+ trigger phrases)
├── action/ctx-audit.yml     CI workflow template (copy into target repo)
└── README.md

Prompting (as a Claude Code skill)

Once installed as a skill (ctx-audit install), you can trigger ctx-audit with natural language:

| Prompt | What happens | |---|---| | "audit my context files" | Runs the audit, reports freshness | | "check context" / "is this repo set up for agents?" | Same — triggers the skill | | "get me up to speed on this repo" | Runs audit first, then reads the fresh files | | "is my memory.md stale?" | Runs audit, focuses on staleness | | "scaffold context files" / "init context" | Runs --init to write templates | | "benchmark token savings" | Runs benchmark subcommand | | "add ctx-audit to CI" | Suggests hook install + CI workflow |

When should an agent run it? At the start of any non-trivial session — before trusting claims in AGENTS.md or memory.md (a stale file is worse than none), before doing a broad exploratory pass reading many files to understand structure, and before re-deriving project conventions from scratch.

Interpreting results

| Result | Meaning | Action | |---|---|---| | MISSING (required) | File doesn't exist | Run npx ctx-audit --init to scaffold, then fill in TODOs | | FRESH | Up to date | Trust the file, read it instead of scanning raw source | | STALE? | Approaching threshold | Mild caution — spot-check critical claims | | STALE! | Past threshold | Treat claims as unverified; update the file after your session | | STALE | Significantly behind | Same as STALE! but more urgent | | Dead references | Paths in context files point to deleted files | Update the references | | Over budget | File token count exceeds maxTokens | Trim the file down | | SHA bumped but content unchanged | Commit SHA updated without real edits | Review whether the file actually reflects recent changes |

The convention

Three files, each opening with frontmatter pinning the commit it was last verified against:

---
last_synced_commit: <git sha>
---

• AGENTS.md — stable conventions: build/test/lint commands, layout rules, hard constraints. Changes rarely.
• memory.md — a decision log: what was tried, what was decided, why. Append-only in spirit; not a restatement of current code.
• .agent/graph.md (optional) — one paragraph per module: what it does, what it talks to. Not file contents, not a full tree.

Whenever you touch what one of these files claims, update its content and its last_synced_commit to current HEAD.

Configuration

Place .ctx-audit.json in the repo root. All fields are optional:

{
  "files": [
    { "id": "agents", "file": "AGENTS.md", "label": "Agent instructions", "maxTokens": 1500, "required": true },
    { "id": "memory", "file": "memory.md", "label": "Decision log", "maxTokens": 2500, "required": true }
  ],
  "sourceDirs": ["src", "packages/core"],
  "staleThreshold": 10,
  "baselineFileCap": 300
}

• files — replaces the default file list entirely (not merge). If you customize this, list all files you want audited.
• sourceDirs — directories treated as "real source" for staleness and baseline. When omitted, auto-detected from git tracked files (top 5 dirs by file count), falling back to ["src", "lib", "app"].
• staleThreshold — number of source commits before a file is considered stale. Default: 5.
• baselineFileCap — max source files to tokenize for baseline estimate. Default: 200.

watches: frontmatter field

Scope staleness checks to specific paths instead of all source directories:

---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---

Comma-separated git pathspecs. When present, only commits touching those paths count toward staleness, making the check more precise for files that document a specific subsystem.

Graduated staleness

Instead of binary stale/fresh, ctx-audit reports 4 levels:

| Level | Commits since sync | Display | Counts as failure? | |---|---|---|---| | fresh | 0 to threshold×0.5 | [FRESH] | No | | possibly-stale | threshold×0.5 to threshold | [STALE?] | No | | likely-stale | threshold to threshold×2 | [STALE!] | Yes | | stale | >threshold×2 | [STALE] | Yes |

The JSON report includes both stalenessLevel (string) and stale (boolean) for backward compatibility.

Additional checks

• Stale-bump detection: If a file's body is identical at last_synced_commit vs. current HEAD but source commits exist, a warning is emitted: "SHA bumped but content unchanged." This catches mechanical SHA updates without real review. Warning only, not a failure.
• Dead reference detection: Backtick-quoted paths and bare dir/file.ext patterns in context files are checked against the filesystem. Missing paths are reported as warnings.

--init scaffolding

npx ctx-audit --init         # interactive: writes AGENTS.md + memory.md to disk
npx ctx-audit --init | cat   # piped: prints templates to stdout

Detects project info from package.json, pyproject.toml, Cargo.toml, or Makefile and fills in build/test/lint commands. In an interactive terminal it writes files directly and asks before overwriting existing ones. When piped or redirected it prints to stdout for backward compatibility.

Companion tools

Graphify (/graphify in Claude Code, or npx graphifyy standalone) can auto-generate the .agent/graph.md architecture map by building a knowledge graph from your codebase. When ctx-audit reports high baseline token costs or a missing graph file, running Graphify is the fastest way to close the gap.