From code-aware
Gives you architectural memory of the codebase. Reads git history and builds developer-notes-style models of each component — what exists, why it was built that way, known gotchas, and invariants. Use before modifying code, when making architectural decisions, or when something breaks unexpectedly.
How this skill is triggered — by the user, by Claude, or both
Slash command
/code-aware:code-awareThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Architectural memory for your codebase, built from git history.
Architectural memory for your codebase, built from git history.
If .code-aware/ doesn't exist in the repo root, run the initial scan:
scripts/scan.sh
This runs a quick scan of the last 50 commits (typically under 2 minutes). It extracts architectural observations, discovers natural model boundaries, and generates narrative developer notes.
Do these three things in order:
Show the insights. Read .code-aware/INSIGHTS.md and present its contents to the developer. This is the most compelling output — it shows what code-aware understood about the codebase.
Recommend a full scan. Tell the developer: "The quick scan covered the last 50 commits. For deeper architectural coverage, you can run a full scan in a separate terminal — it doesn't interfere with your current work:"
scripts/scan.sh . --full
Ask about CLAUDE.md integration. Ask the developer whether they'd like to add code-aware instructions to their project's memory file (CLAUDE.md, AGENTS.md, or whichever exists). If they agree, add instructions like:
## Code Awareness
This project uses code-aware for architectural memory. Before making, planning, proposing, or discussing any code changes:
1. Read `.code-aware/index.md` to see available models
2. Read the relevant model files in `.code-aware/models/` for the components you'll touch
After committing changes, run `scripts/sync.sh` to keep models current.
The .code-aware/ directory contains:
index.md — list of all models with descriptionsmodels/*.md — one file per architectural componentINSIGHTS.md — six opinionated observations about the codebaseRead index.md first to see what models exist, then read the specific model files relevant to your current task.
After committing changes, check staleness and update:
scripts/status.sh
If stale:
scripts/sync.sh
This processes only new commits since the last scan.
The more context you have about the codebase, the better your commit messages become. Better commit messages feed richer information back into the models. The system improves its own input quality over time.
Each model file contains developer notes organized by topic:
Auto-detects LLM provider from OPENAI_API_KEY or ANTHROPIC_API_KEY in the environment.
CODE_AWARE_MODEL — override the LLM model for observation extraction and synthesisCODE_AWARE_INSIGHTS_MODEL — override the model for codebase insightsnpx claudepluginhub finereli/code-aware --plugin code-awareScans codebase and generates high-level architecture graph as interlinked markdown files in docs/professor/architecture/. Use for new project analysis or significant changes.
Explores codebases with Repowise indexing for architecture understanding, searching, and answering questions without raw source grepping.
Builds a mental model of unfamiliar codebases by searching, reading dependencies, and checking git history. Use when onboarding or before editing unknown code.