README.md
May 6, 2026 · View on GitHub
Your AI agent maintains its own context files — a Claude Code plugin with an AGENTS-first model that covers Codex, Copilot, Cursor, Gemini, and 3 more tools.
Give your AI one canonical `AGENTS.md` plus thin bridge files for every major AI coding tool — `CLAUDE.md`, `.cursor/rules/agents.mdc` (modern Cursor), `.clinerules/agents.md` (modern Cline directory mode), `.windsurfrules`, `GEMINI.md`, and an optional `.github/copilot-instructions.md` (Copilot loads AGENTS.md natively) — from a single codebase scan. Signal Gate filtering strips out what agents already discover on their own. Context Guard hooks enforce freshness. Health scoring catches drift before it costs you tokens. 100% Markdown, zero runtime dependencies.
Get Started · Features · How It Compares · Commands · Other AI Tools · Contributing
⚡ Get Started
Get your first AI context files generated in under 60 seconds.
Prerequisites
- Claude Code or OpenCode installed
Using a different AI tool? ContextDocs generates plain Markdown files that work with Codex CLI, GitHub Copilot, Cursor, Windsurf, Cline, and Gemini CLI automatically.
Install
# 1. Add the LBA plugin marketplace (once)
/plugin marketplace add littlebearapps/lba-plugins
# 2. Install ContextDocs
/plugin install contextdocs@lba-plugins
# 3. Bootstrap AI context for your project
/contextdocs:ai-context init
Optional — install Context Guard hooks (Claude Code only):
# 4. Keep context files in sync as your project evolves
/contextdocs:context-guard install # Tier 1 (Nudge) — reminds at session end
/contextdocs:context-guard install --tier enforce # Tier 2 (Enforce) — also blocks commits
Optional — public-facing documentation:
For README, CHANGELOG, ROADMAP, user guides, and launch artifacts, install PitchDocs separately. Both plugins work independently and complement each other.
🚀 What ContextDocs Does
Your AI coding assistant works better when it understands your project's conventions — but overstuffed context files actually make things worse. Research shows bloated context reduces AI task success by ~3% and increases token costs by 20% (ETH Zurich, 2026). Most teams either write too much, write the wrong things, or let context files go stale within a week.
ContextDocs solves the full lifecycle. It scans your codebase, generates AGENTS.md as the canonical shared context, then creates thin bridge files that cover 8 AI tools using the Signal Gate principle — only what agents cannot discover by reading source code on their own. No directory listings, no file trees, no architecture overviews that agents find themselves. Just the conventions, gotchas, and decisions that actually help.
For Claude Code users: Claude Code auto-loads CLAUDE.md every session. The generated CLAUDE.md starts with @AGENTS.md, which imports the canonical shared context directly — so you get the full conventions plus Claude-specific additions without duplication. Other tools (Codex CLI, Gemini CLI, Copilot, Cursor) load their own bridge files or AGENTS.md directly.
Then it keeps them fresh: update patches drift incrementally, promote moves Claude's auto-learned MEMORY.md patterns into CLAUDE.md, context-verify scores health 0–100 across 6 dimensions with 13 checks, and Context Guard hooks enforce freshness at session start, session end, and commit time — with the context-updater agent applying fixes automatically.
🎯 Features
ContextDocs generates AGENTS-first context for 8 AI coding tools from a single codebase scan, applies Signal Gate filtering to strip discoverable content, enforces line budgets (AGENTS.md <120, CLAUDE.md <80, other bridges <60), and scores health 0–100 across 6 dimensions with 13 verification checks. Context Guard hooks catch drift at session start, session end, and commit time.
- 🧠 Signal Gate filtering — strips out discoverable content (directory listings, file trees, architecture overviews) so your context files contain only what actually helps AI tools, keeping them lean and under budget
- 📋 AGENTS-first generation + thin bridges — shared conventions live once in
AGENTS.md, whileCLAUDE.md,.cursor/rules/*.mdc,.clinerules/, optional Copilot instructions, and compatibility bridges stay minimal and tool-specific - 🔄 Full lifecycle, not just generation —
initbootstraps,updatepatches only what drifted,promotegraduates MEMORY.md patterns to CLAUDE.md,auditflags staleness — so context files stay accurate as your project evolves - ✅ Health scoring (0–100) — grades context files across line budget, signal quality, path accuracy, AGENTS-to-bridge consistency, freshness, aggregate context load, and modern Cursor/Cline/Copilot layouts (16 checks total) — export to CI with
--min-scoreso drift never reaches your team - 🔒 Context Guard enforcement — SessionStart health check validates on entry, Tier 1 nudges at session end, Tier 2 blocks commits when context files are stale, so drift gets caught at every stage (Claude Code only)
- 🤖 Autonomous context updates — the context-updater agent is launched automatically by hooks to update stale files without user intervention, closing the loop from detection to action (Claude Code only)
- 🛡️ Content filter protection — guards against Claude Code's API filter (HTTP 400) for CODE_OF_CONDUCT, LICENSE, and SECURITY files, so hook installation never gets blocked (Claude Code only)
- 📏 Line budgets that work — CLAUDE.md <80, AGENTS.md <120, all others <60 — backed by the ETH Zurich finding that shorter, focused context outperforms longer files
- 🗂️ Path-scoped context rules — apply different conventions to different directories using glob patterns, so monorepos and multi-platform projects get targeted context per area (Claude Code only)
- 📡 Upstream compatibility tracking — weekly Claude Code release monitoring and settings schema diffing detect breaking changes before they affect your context files
- 🔌 Works with 8 AI tools — Claude Code and OpenCode natively; generated files also work with Codex CLI, GitHub Copilot, Cursor, Windsurf, Cline, and Gemini CLI automatically
⚖️ How ContextDocs Compares
ContextDocs automates what most teams do manually — writing and maintaining AI context files. Compared to hand-writing context files or asking a generic AI prompt, ContextDocs applies Signal Gate filtering, generates canonical AGENTS.md plus bridges for 8 tools, enforces line budgets, and keeps files in sync with Context Guard hooks.
| Capability | ContextDocs | Writing Context Files Manually | Generic AI Prompt |
|---|---|---|---|
| Filters out discoverable content | Signal Gate principle — only undiscoverable signals | Requires discipline and AI knowledge | No filtering — dumps everything |
| Generates for multiple AI tools | Canonical AGENTS.md + thin bridges from one scan | Write each file separately | One file at a time |
| Keeps files in sync over time | update, audit, Context Guard hooks + autonomous agent | Manual review after every change | Start from scratch each time |
| Enforces quality standards | 0–100 health score, CI integration, line budgets | No enforcement | No enforcement |
| Handles line budgets | Automatic per-file limits | Easy to exceed without noticing | No awareness of budgets |
🤖 Commands
ContextDocs provides 3 slash commands covering the full context file lifecycle — generation, freshness enforcement, and quality verification. All commands use the contextdocs: prefix when installed as a plugin.
| Command | What It Does | Why It Matters |
|---|---|---|
/contextdocs:ai-context | Generate AGENTS-first AI context using Signal Gate — init, update, promote, audit, or per-tool (claude, agents, cursor, etc.) | Every AI tool gets lean, accurate project context |
/contextdocs:context-guard | Install, uninstall, or check status of Context Guard hooks (Claude Code only) | Stale context files get caught before they waste tokens |
/contextdocs:context-verify | Score context file health 0–100 — line budgets, stale paths, bridge consistency, signal quality | Drift never reaches your team — enforce in CI or check locally |
Quick Examples
/contextdocs:ai-context init # Bootstrap context for a new project
/contextdocs:ai-context update # Patch only what drifted
/contextdocs:ai-context promote # Move MEMORY.md patterns to CLAUDE.md
/contextdocs:ai-context audit # Check for staleness and drift
/contextdocs:context-verify # Score context file health (0–100)
/contextdocs:context-guard install # Install freshness hooks
/contextdocs:context-guard status # Check which hooks are active
🔀 Use with Other AI Tools
ContextDocs generates plain Markdown files placed where each AI tool expects them. AGENTS.md is the canonical shared context; bridge files exist only where a tool still benefits from or requires its own file. No manual copying required for any supported tool.
ContextDocs works natively with Claude Code and OpenCode. The generated context files are plain Markdown — each is placed where the target tool expects it:
| File | Role | Tool | How It's Loaded |
|---|---|---|---|
| AGENTS.md | Canonical shared context | Codex CLI, OpenCode, Gemini CLI, Copilot coding agent | Auto-loaded at startup; Claude Code loads via @AGENTS.md import in CLAUDE.md |
| CLAUDE.md | Claude Code bridge | Claude Code, OpenCode | Auto-loaded every session; starts with @AGENTS.md to import shared context |
| .cursor/rules/agents.mdc | Modern Cursor bridge | Cursor | Loaded when frontmatter (description / globs / alwaysApply) matches; default since 2026 |
| .cursorrules | Legacy Cursor bridge | Cursor | Only emitted when already present; current Cursor versions ignore in Agent mode |
| .github/copilot-instructions.md | Optional Copilot bridge | GitHub Copilot | Optional — Copilot's coding agent loads AGENTS.md natively (since Aug 2025); only emit when adding tool-specific scoping |
| .windsurfrules | Compatibility bridge | Windsurf | Yes — project root convention |
| .clinerules/agents.md | Modern Cline bridge (directory) | Cline | Default for new projects; supports paths: frontmatter for path-scoped rules |
| .clinerules | Legacy Cline bridge (flat) | Cline | Only emitted when already present |
| GEMINI.md | Compatibility bridge | Gemini CLI | Yes — loaded on startup |
Context Guard hooks are Claude Code only. All other features (generation, update, verify) work wherever the plugin runs.
📚 Documentation
- Getting Started Guide — Installation, first context file generation, and Context Guard setup
- Troubleshooting — Signal Gate issues, hook problems, content filter errors, and FAQ
- Documentation Hub — All guides and reference links
- Support — Getting help and common questions
- Security — Vulnerability reporting and response timeline
🔗 Related
For public-facing repository documentation (README, CHANGELOG, ROADMAP, user guides, launch artifacts), see PitchDocs.
🤝 Contributing
Found a way to make generated context files even better? We'd love your help — whether it's improving Signal Gate filtering, fixing a hook script, or adding support for a new AI tool's context format.
See our Contributing Guide to get started. This project follows the Contributor Covenant v3.0.
- Open Issues — See what needs doing
- Feature Requests — Suggest improvements
📄 Licence
MIT — Made by Little Bear Apps 🐶