ez-context Documentation

Everything you need to generate, inspect, and maintain AI context files that stay in sync with your codebase.

What is ez-context?

ez-context analyzes your codebase to extract real coding conventions -- naming patterns, import styles, test setup, error handling, stack configuration -- and generates AI context files that accurately reflect how your project works.

Context files like CLAUDE.md and AGENTS.md are written once and then forgotten. As your codebase evolves, these files drift -- they describe conventions you abandoned months ago, reference patterns you never actually use, and silently mislead the AI tools that depend on them.

ez-context solves this by detecting semantic drift: it compares each claim in your context files against actual evidence in your code, scores every claim as confirmed or contradicted, and can automatically rewrite stale sections while preserving your manual edits.

It supports 7 output formats -- from Claude Code to Cursor rules to GitHub Copilot instructions -- so one tool covers every AI assistant in your workflow.

Installation

Install ez-context globally using your preferred package manager. Requires Node.js ≥ 20.19.0.

npm

npm install -g @ez-corp/ez-context

pnpm

pnpm add -g @ez-corp/ez-context

bun

bun add -g @ez-corp/ez-context

yarn

yarn global add @ez-corp/ez-context

After install, run ez-context --version to confirm.

Quick Start

Three commands cover the complete workflow. Run them from your project root.

1
Analyze and generate context files
```
ez-context generate
```
Scans your project and writes CLAUDE.md and AGENTS.md by default.
2
Check for drift
```
ez-context drift
```
Compares your context files against the codebase. Reports a health score and lists outdated claims.
3
Fix stale sections
```
ez-context update
```
Rewrites the ez-context-managed block in each file. Manual content outside the markers is untouched.

CLI Commands

generate

Extract conventions and generate context files.

ez-context generate [path]

--dry-run: Preview output without writing any files
-y, --yes: Non-interactive mode (skip confirmation prompts)
--output <dir>: Directory to write generated files into (default: .)
--threshold <n>: Confidence threshold 0–1 for including a convention (default: 0.7)
--format <formats>: Comma-separated list of output formats to generate (default: claude,agents)

Valid format values: claude agents cursor copilot skills rulesync ruler

Examples

# Generate all 7 formats
ez-context generate --format claude,agents,cursor,copilot,skills,rulesync,ruler

# Preview what would be written
ez-context generate --dry-run

# Analyze a subdirectory at lower confidence
ez-context generate ./packages/api --threshold 0.6 --output ./packages/api

inspect

Display all detected conventions grouped by category with confidence scores.

ez-context inspect [path]

--threshold <n>: Minimum confidence to include a convention in output (default: 0.7)

Use inspect to understand what ez-context detected before committing to generated files. Useful for tuning --threshold.

drift

Check context files against your codebase for semantic drift.

ez-context drift [path]

--file <contextFile>: Check a specific file instead of all managed files

Examples

# Check all context files
ez-context drift

# Check a single file
ez-context drift --file CLAUDE.md

# Check a project in another directory
ez-context drift ./packages/api

update

Rewrite drifted sections in context files while preserving manual edits outside the markers.

ez-context update [path]

--file <contextFile>: Update a specific file instead of all managed files
--dry-run: Preview what would change without writing files
-y, --yes: Non-interactive mode (skip confirmation prompts)

Output Formats

Pass any combination to --format as a comma-separated list. Omit the flag to get claude,agents by default.

claude

CLAUDE.md CLAUDE.md

Anthropic Claude Code context file. Used by claude-code and MCP-compatible tools.

agents

AGENTS.md AGENTS.md

Linux Foundation agent standard. Cross-platform context for any agent runtime.

cursor

Cursor Rules .cursor/rules/*.mdc

Cursor IDE rules in MDC format with glob-scoped context per rule.

copilot

Copilot .github/copilot-instructions.md

GitHub Copilot workspace instructions. Injected into every Copilot interaction.

skills

SKILL.md SKILL.md

Skill modules with progressive disclosure. Structured for agent skill registries.

rulesync

Rulesync .rulesync/rules/ez-context.md

Rulesync format for cross-editor rule synchronization and sharing.

ruler

Ruler .ruler/*.md

Ruler format for opinionated context organization with tagging support.

Tip: Generate all formats at once with --format claude,agents,cursor,copilot,skills,rulesync,ruler. Each format is written to its conventional location -- no extra configuration needed.

How Drift Detection Works

Drift detection uses semantic search to verify every claim in your context files against the actual code in your project.

1
Claim extraction

ez-context parses your context file and extracts discrete claims -- statements like "uses camelCase naming", "TypeScript strict mode enabled", or "tests live in a test/ directory".
2
Semantic search

Each claim is embedded and checked against your codebase using local embeddings -- no data ever leaves your machine. The search finds supporting or contradicting evidence in your actual source files.
3
Scoring

Each claim is scored as one of three states:

GREEN Confirmed -- code evidence supports the claim

YELLOW Uncertain -- insufficient evidence found

RED Contradicted -- code evidence conflicts with the claim
4
Health score

The results are aggregated into a health score from 0 to 100. A score of 100 means all claims are confirmed. Lower scores indicate drift that should be addressed with ez-context update.

Markers

All ez-context-generated content is wrapped in HTML comment markers. The markers make it possible to update the generated section without touching anything you've written by hand.

<!-- ez-context:start -->
# Project Context

## Stack
- Language: TypeScript
- Build: tsdown

## Conventions
- **naming**: functions use camelCase naming
<!-- ez-context:end -->

# My Custom Notes

These lines are outside the markers and will NEVER be overwritten
by ez-context update. Add anything you want here.

Managed content (inside markers)

Everything between  and  is owned by ez-context. Running ez-context update rewrites this block with fresh analysis results.

Manual content (outside markers)

Any content above or below the marker block is yours. Add project-specific guidance, agent instructions, team norms, or anything that shouldn't be auto-generated. ez-context will never touch it.

No markers yet?

Running ez-context generate on an existing file will append the marker block at the end, preserving all existing content above it.

Next steps

GitHub repository → Source code, issues, and contribution guide. npm package → Version history and install stats.