claude-auto-context

Auto-Context

Auto-Context is a Claude Code plugin that makes your project smarter over time. Instead of manually maintaining CLAUDE.md, it observes your coding sessions, extracts patterns, detects conventions, and progressively improves your project's context — so Claude gets better at navigating and understanding your codebase with every session.

Think of it as "organizational scar tissue" — but automated.

How it works

It starts the moment you open a Claude Code session. Tool calls (Edit, Write, Bash, NotebookEdit) and user prompts get silently captured and stored in a local SQLite database. Payloads are compressed at ingestion — only metadata (file paths, commands) is kept, not full file contents.

When enough events accumulate (100+), a background worker launches. It analyzes the events across sessions, delegates to specialized sub-agents via the Claude Agent SDK, and produces:

1. Rules files (.claude/rules/local/*.md) are auto-generated from repeated conventions and user corrections. Claude loads them automatically when touching matching files.
2. Structural suggestions are created when agents detect AI-unfriendly code patterns (monoliths, unclear naming, missing context). These require your explicit approval.
3. Skills (.claude/skills/*/SKILL.md) are extracted from repeated multi-step workflows — reusable slash commands.
4. Hooks (.claude/hooks/*.sh) are generated when repetitive manual actions are detected (lint, format, test).
5. Hygiene reports flag duplicates, contradictions, and stale references in existing rules and suggestions.

Nothing structural changes without your say-so. You run /cac-apply, review the evidence, and decide.

Installation

From GitHub (Recommended)

Add the marketplace:

/plugin marketplace add getklaim/claude-auto-context

Install the plugin:

/plugin install claude-auto-context@claude-auto-context-marketplace

Or open the interactive plugin manager with /plugin, navigate to the Marketplaces tab to add the marketplace, then switch to Discover to install.

From Git URL

/plugin marketplace add https://github.com/getklaim/claude-auto-context.git

Verify Installation

Start a new Claude Code session. The setup hook will auto-install Bun (if missing) and create .claude/rules/local/. The background worker launches automatically when enough events accumulate — no manual setup needed.

Updating

/plugin update claude-auto-context@claude-auto-context-marketplace

The Core Workflow

Automatic (Zero Config)

Once installed, hooks fire automatically across six lifecycle events:

Event	What happens
SessionStart	Outputs dashboard stats (rules count, pending suggestions, DB size) into session context
Setup	Installs Bun if missing, creates .claude/rules/local/, runs auto-cleanup
UserPromptSubmit	Captures user prompt → SQLite (uncompressed, to preserve intent), checks for pending suggestions
PreToolUse	Version sync on commit, blocks conflict markers and planning files from staging
PostToolUse	Captures Edit|Write|Bash|NotebookEdit events → SQLite (compressed), syntax checks on edited files
Stop	Launches background worker if 100+ pending events

All hooks execute in under 100ms. You never notice them.

Commands

Command	Purpose
/cac-apply	Review and apply a specific structural suggestion
/create-suggestion	Manually create a structural suggestion with evidence
/extract-rules	Manually extract convention rules from current session
/context-hygiene	Run a context quality audit (duplicates, contradictions, stale refs)
/cac-create-skill	Create a SKILL.md from a detected workflow pattern
/run-worker	Manually trigger the background worker

What the Worker Produces

Auto-generated (no approval needed):

.claude/rules/local/
  error-handling.md    ← "Use Result type, not try-catch" (globs: src/**/*.ts)
  api-patterns.md      ← "All endpoints return ApiResponse<T>" (globs: src/api/**)

Rules files are scoped by glob pattern via frontmatter. Claude loads them automatically when it touches matching files — no CLAUDE.md bloat. Rules auto-decay: revalidated after 30 days, force-deleted after 60 days of no validation.

Suggestions (requires your approval):

.claude-auto-context/suggestions/
  001-split-utils.md          ← "src/utils.ts has 4% signal ratio → split into date.ts, string.ts"
  002-unify-route-patterns.md ← "routes/ uses 3 different patterns → standardize"

Each suggestion includes the problem, proposed fix, and evidence from specific sessions.

Architecture