codebrief 1.2.0 → 1.3.0

package/README.md

@@ -1,124 +1,268 @@
 # codebrief
 
-Bootstrap optimized AI context files for any project. Auto-detects your tech stack, generates code snapshots, and produces config for Claude Code, Cursor, Copilot, Windsurf, Cline, Continue, Aider, and more.
+Give your AI agent full project context, without the warm-up.
 
 ![codebrief demo](demo.gif)
 
+AI coding agents spend their first few minutes reading files, tracing imports, and piecing together your architecture. **codebrief** does that work once, ahead of time, and hands the agent a single context file so it can start writing useful code immediately.
+
+```bash
+npx codebrief
+```
+
+## Before & After
+
+Without codebrief, a typical AI agent session starts like this:
+
+```
+Agent: Let me explore the project structure...
+Agent: Reading src/index.ts...
+Agent: Reading src/types.ts...
+Agent: Reading src/utils/api-client.ts...
+Agent: Reading src/store/auth.ts...
+Agent: Now I understand the architecture. Let me start working...
+```
+
+With codebrief, the agent already knows:
+
+| What | Example |
+|------|---------|
+| Tech stack | Next.js 14 (App Router), TypeScript, Zustand, Tailwind |
+| Key files | `src/types.ts` (highest centrality), `src/api/client.ts` |
+| Architecture | services → hooks → components → pages |
+| Active areas | `src/auth/` changed 12 times in the last 90 days |
+| Coupled files | `routes.ts` and `middleware.ts` always change together |
+| Code snapshot | All public types, interfaces, props, and function signatures |
+
+<details>
+<summary><strong>Example: generated CLAUDE.md</strong> (click to expand)</summary>
+
+```markdown
+# MyProject
+
+> **Keep this file up to date.** When you change the architecture, add a dependency,
+> create a new pattern, or learn a gotcha, update this file in the same step.
+
+## What Is This
+
+A mobile AI chat app connecting to OpenAI, Anthropic, and Google APIs
+
+## Tech Stack
+
+- **Next.js** 14.1.0 (used in 34 files)
+- **TypeScript**
+- **Prisma** (used in 8 files)
+- **Tailwind CSS** (used in 22 files)
+- **npm** (package manager)
+
+## Code Snapshot
+
+<!-- CODE SNAPSHOT (auto-generated) -->
+
+### Core Types
+
+‍```ts
+export interface User {  // imported by 12 files
+  id: string;
+  email: string;
+  role: "admin" | "user";
+}
+
+export type APIResponse<T> = {  // imported by 8 files
+  data: T;
+  error?: string;
+}
+‍```
+
+### Key Functions
+
+‍```ts
+export async function fetchChat(chatId: string): Promise<Chat>  // imported by 6 files
+
+export function useAuth(): AuthContext  // imported by 9 files
+‍```
+
+<!-- /CODE SNAPSHOT -->
+
+## Key Files
+
+| File | Imported By | Stability |
+|------|-------------|-----------|
+| `src/types.ts` | 18 files | stable |
+| `src/lib/api-client.ts` | 12 files | stable |
+| `src/store/auth.ts` | 9 files | stable |
+
+## Architecture
+
+‍```
+┌──────────────┐    ┌──────────────┐
+│    types      │    │   services    │
+└──────────────┘    └──────────────┘
+        │                    │
+        ▼                    ▼
+┌──────────────┐    ┌──────────────┐
+│    hooks      │    │  components   │
+└──────────────┘    └──────────────┘
+‍```
+
+## Recently Active Files
+
+| File | Commits (90d) | Last Changed |
+|------|--------------|--------------|
+| `src/app/chat/page.tsx` | 14 | 2 days ago |
+| `src/lib/api-client.ts` | 11 | 3 days ago |
+
+<!-- ... more sections: change coupling, module clusters, gotchas -->
+```
+
+</details>
+
 ## Quick Start
 
+Run in your project root:
+
 ```bash
 npx codebrief
 ```
 
-Run in your project root. It will:
+codebrief will:
 
-1. **Auto-detect** your tech stack (language, framework, package manager, linter)
+1. **Detect** your tech stack (language, framework, package manager, linter)
 2. **Ask** a few questions (which AI tool, project purpose, key patterns)
 3. **Scan** source files for a code snapshot (types, store shapes, component props)
-4. **Generate** optimized context files for your chosen tool
+4. **Generate** an optimized context file for your chosen tool
 5. **Show** a summary with token savings estimate
 
-On first run, your answers are saved to `.codebrief.json` so future runs skip the prompts entirely.
+Your answers are saved to `.codebrief.json` so future runs skip the prompts.
 
-## What It Does
+## Supported Tools
 
-codebrief builds a comprehensive understanding of your codebase and distills it into context files that AI agents can load instantly — eliminating the expensive exploration phase where agents read dozens of files just to understand the architecture.
+| Tool | Generated file | Docs |
+|------|---------------|------|
+| Claude Code | `CLAUDE.md` | [claude.ai/docs](https://docs.anthropic.com/en/docs/claude-code/memory#claudemd-files) |
+| Cursor | `CLAUDE.md` + `.cursor/rules/*.md` | [cursor.com/docs](https://docs.cursor.com/context/rules-for-ai) |
+| OpenCode | `AGENTS.md` | [opencode.ai](https://opencode.ai/) |
+| GitHub Copilot | `.github/copilot-instructions.md` | [docs.github.com](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) |
+| Windsurf | `.windsurfrules` | [windsurf.com](https://docs.windsurf.com/windsurf/memories#rules) |
+| Cline | `.clinerules` | [cline.bot](https://docs.cline.bot/improving-your-workflow/cline-rules) |
+| Continue.dev | `.continuerules` | [continue.dev/docs](https://docs.continue.dev/customize/deep-dives/rules) |
+| Aider | `.aider.conf.yml` | [aider.chat](https://aider.chat/docs/config/adir_conf.html) |
+| Generic | `CONTEXT.md` | - |
 
-The generated context includes:
+## How It Works
 
-- **Tech stack summary** with detected frameworks, versions, and usage counts
-- **Code snapshot** of all public types, interfaces, function signatures, and component props
-- **Key files** ranked by centrality (PageRank) with stability warnings
-- **Architecture layers** showing dependency flow
-- **Change coupling** — file pairs that frequently change together
-- **Circular dependencies** detected via Tarjan's SCC algorithm
-- **Module clusters** — automatically detected groups of related files
-- **Git activity** — recently active files and churn patterns
-- **Framework conventions** — best practices for your specific stack
+codebrief runs a pipeline of static analysis steps. Here's a quick overview:
 
-## How It Works
+| Step | What it does | Why it matters |
+|------|-------------|----------------|
+| [Dependency graph](#dependency-graph) | Parses all `import`/`require`/`use` statements | Maps how files connect to each other |
+| [PageRank](#pagerank) | Ranks files by structural importance | Surfaces the files an agent should read first |
+| [Dead export removal](#dead-export-removal) | Drops exports nothing imports | Saves tokens on unused code |
+| [Token budgeting](#token-budgeting) | Fits the snapshot into a token limit | Keeps context files within model limits |
+| [Layer detection](#layer-detection) | Classifies files into architecture layers | Gives agents a mental model of your project |
+| [Cycle detection](#cycle-detection) | Finds circular import chains | Warns agents about risky dependency loops |
+| [Instability scoring](#instability-scoring) | Flags volatile, widely-depended-on files | Tells agents where to be extra careful |
+| [Change coupling](#change-coupling) | Finds files that always change together | Prevents incomplete changes |
+| [Module clustering](#module-clustering) | Groups related files into logical modules | Reveals structure beyond folder layout |
+| [Git activity](#git-activity) | Surfaces recently active files | Shows where current work is focused |
+| [Stale detection](#stale-detection) | Hashes file paths + mtimes | Tells you when to re-run |
+
+### Dependency Graph
+
+Parses all `import`, `require`, and `use` statements across your source files and builds a directed graph. This graph powers every other analysis step.
 
-codebrief runs a pipeline of static analysis on your codebase. Here's what each step does and why it matters.
+```
+src/hooks/useAuth.ts  ──imports──▶  src/store/auth.ts
+src/hooks/useAuth.ts  ──imports──▶  src/types.ts
+src/pages/Login.tsx   ──imports──▶  src/hooks/useAuth.ts
+```
 
-### Mapping dependencies
+### PageRank
 
-**Problem:** AI agents don't know which files depend on each other, so they waste time reading unrelated code.
+Runs the [PageRank algorithm](https://en.wikipedia.org/wiki/PageRank) on the import graph. The same algorithm Google uses to rank web pages. Files imported by many important files score highest.
 
-codebrief parses all `import`/`require`/`use` statements across your source files and builds a dependency graph. This graph powers most of the analysis below — it's how codebrief understands the structure of your project without running it.
+**Example:** In a typical project, `types.ts` or `api-client.ts` often ranks #1 because most of the codebase depends on them. These high-centrality files appear first in the generated context so agents understand foundational code before details.
 
-### Ranking files by importance (PageRank)
+### Dead Export Removal
 
-**Problem:** In a project with hundreds of files, which ones should an agent read first?
+Cross-references every named export against the import graph. If nothing in the project imports it, it's excluded from the snapshot.
 
-codebrief runs the same algorithm Google uses to rank web pages — but on your import graph instead of the internet. Files that are imported by many important files get a high score. For example, your main `types.ts` or a shared `api-client.ts` would rank near the top because they sit at the center of your dependency tree. These high-centrality files are surfaced first so agents understand your architecture before diving into details.
+This catches leftover refactors, over-exported utilities, and test-only helpers, keeping the context lean.
 
-### Removing dead exports
+### Token Budgeting
 
-**Problem:** Source files often contain exported functions, types, or constants that nothing actually imports — leftover refactors, unused utilities, or over-exported modules. Including these in context wastes tokens.
+Large projects may have more types and signatures than fit in the token budget. codebrief uses a greedy [knapsack](https://en.wikipedia.org/wiki/Knapsack_problem) approach that prioritizes:
 
-codebrief cross-references every named export against the import graph. If no file in the project imports it, it's excluded from the code snapshot.
+1. Entries from high-centrality files (via PageRank)
+2. Recently active files (via git history)
+3. Core categories (types, store shapes, component props)
 
-### Fitting context into a token budget
+Lower-priority items fill whatever budget remains.
 
-**Problem:** A full code snapshot of every type, interface, and function signature might exceed the token budget — especially in large projects.
+### Layer Detection
 
-codebrief uses a greedy knapsack approach: it prioritizes entries from the most central files, recently active files, and core categories (types, store shapes) first, then fills the remaining budget with lower-priority items. This ensures the most valuable context always makes it in, even under tight limits.
+Classifies files into architecture layers based on directory and naming conventions:
 
-### Detecting architectural layers
+```
+types  →  stores  →  services  →  hooks  →  components  →  pages
+                                              ↑
+                                            utils, config
+```
 
-**Problem:** Agents need to understand the high-level shape of a project — where the types live, where the API calls happen, where the UI components are.
+The generated context includes a dependency-flow summary so agents understand how layers relate (e.g., "services call the API, components use hooks, hooks read from stores").
 
-codebrief classifies files into layers (types, stores, hooks, services, components, pages, utils, config) based on directory and naming conventions, then analyzes how those layers depend on each other. This gives agents a quick mental model like "services call the API, components use hooks, hooks read from stores."
+### Cycle Detection
 
-### Finding circular dependencies (Tarjan's SCC)
+Uses [Tarjan's algorithm](https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm) to find groups of files that form import cycles.
 
-**Problem:** Circular imports cause subtle bugs, make refactoring dangerous, and confuse AI agents trying to understand dependency flow.
+**Example:** `auth.ts → user.ts → permissions.ts → auth.ts`. All three files are reported as a circular dependency cluster. Agents are warned to avoid deepening the cycle.
 
-codebrief uses Tarjan's algorithm to find groups of files that form import cycles. For example, if `auth.ts → user.ts → permissions.ts → auth.ts`, all three files are reported as a circular dependency cluster. This is surfaced in the context so agents avoid introducing more cycles.
+### Instability Scoring
 
-### Flagging unstable files
+Computes an [instability metric](https://en.wikipedia.org/wiki/Software_package_metrics) for each file:
 
-**Problem:** Some files change frequently but are imported by many others — any modification risks breaking things across the project.
+```
+instability = outgoing imports / (outgoing + incoming imports)
+```
 
-codebrief computes an instability score for each file based on how many files it imports vs. how many files import it. Files that are both highly unstable and widely depended on are flagged as risk zones — agents will know to be extra careful when modifying them.
+Files that are both highly unstable (many outgoing deps) **and** widely depended on (many incoming deps) are flagged as risk zones.
 
-### Detecting change coupling
+### Change Coupling
 
-**Problem:** Some files always need to change together (e.g., a component and its test, or a route and its handler) but there's no import relationship between them.
+Analyzes 90 days of git history to find file pairs that frequently appear in the same commits.
 
-codebrief analyzes 90 days of git history to find file pairs that frequently appear in the same commits. If two files were changed together in many commits, they're reported as coupled — so agents know that touching one likely means touching the other.
+**Example output:**
 
-### Discovering module clusters
+| File A | File B | Co-changes | Confidence |
+|--------|--------|------------|------------|
+| `src/api/client.ts` | `src/api/types.ts` | 12 | 92% |
+| `src/routes.ts` | `src/middleware.ts` | 8 | 80% |
 
-**Problem:** Large projects have natural groupings of related files (an auth module, a payments module) but these aren't always obvious from the folder structure.
+This catches implicit dependencies that don't show up in imports. Agents know that touching one file likely means touching the other.
 
-codebrief uses label propagation on the import graph: each file starts with its own label and iteratively adopts the most common label among its neighbors. Files that end up sharing a label form a natural cluster. This reveals logical modules even when the folder layout doesn't match.
+### Module Clustering
 
-### Tracking git activity
+Uses [label propagation](https://en.wikipedia.org/wiki/Label_propagation_algorithm) on the import graph to discover natural groupings. Each file starts with its own label and iteratively adopts the most common label among its neighbors. Files sharing a label form a module cluster.
 
-**Problem:** Agents don't know which parts of the codebase are actively being worked on vs. which are stable.
+This reveals logical boundaries (auth module, payments module, settings module) even when the folder layout doesn't reflect them.
 
-codebrief counts commits per file over the last 90 days to surface hot spots and recently active files. This helps agents understand where current development is focused.
+### Git Activity
 
-### Detecting stale snapshots
+Counts commits per file over the last 90 days to surface:
 
-**Problem:** After a refactor, the code snapshot in your context file may be outdated — describing types and signatures that no longer exist.
+- **Hot spots**: files with the most churn
+- **Recently active files**: where current development is focused
+- **Quiet zones**: stable code that rarely changes
 
-codebrief hashes all source file paths and modification times. When you run `--check`, it compares this hash against the stored one to tell you if the snapshot needs refreshing.
+### Stale Detection
 
-## Supported Tools
+Hashes all source file paths and modification times. Run `--check` to compare against the stored hash:
 
-| Tool | Files Generated |
-|------|----------------|
-| Claude Code | `CLAUDE.md` |
-| Cursor | `CLAUDE.md` + `.cursor/rules/*.md` (glob-scoped) |
-| OpenCode | `AGENTS.md` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| Windsurf | `.windsurfrules` |
-| Cline | `.clinerules` |
-| Continue.dev | `.continuerules` |
-| Aider | `.aider.conf.yml` |
-| Generic | `CONTEXT.md` |
+```bash
+npx codebrief --check
+# exit 0 = snapshot is fresh
+# exit 1 = snapshot is stale, run --refresh-snapshot
+```
 
 ## Options
 
@@ -128,13 +272,17 @@ npx codebrief [directory] [options]
 
 | Flag | Description |
 |------|-------------|
-| `directory` | Path to analyze (defaults to current directory) |
+| `directory` | Path to analyze (defaults to `.`) |
+| `-h, --help` | Show help message |
+| `-V, --version` | Show version number |
 | `--force` | Overwrite existing files without asking |
-| `--dry-run` | Show what would be generated without writing any files |
-| `--refresh-snapshot` | Re-scan source files and update the code snapshot in your existing context file |
-| `--reconfigure` | Force re-prompting even if `.codebrief.json` exists |
-| `--check` | Check if the snapshot is stale (exit code 0 = fresh, 1 = stale). Designed for shell integration. |
+| `--dry-run` | Preview what would be generated |
+| `--refresh-snapshot` | Re-scan source files and update just the code snapshot |
+| `--reconfigure` | Re-prompt even if `.codebrief.json` exists |
+| `--check` | Check if the snapshot is stale (exit 0 = fresh, 1 = stale) |
 | `--max-tokens=N` | Set the token budget for the code snapshot |
+| `--generate-skills` | Generate Claude Code skill files |
+| `-v, --verbose` | Show detailed progress output |
 
 ### Refreshing Snapshots
 
@@ -144,13 +292,14 @@ After a refactor, update just the code snapshot without re-generating the entire
 npx codebrief --refresh-snapshot
 ```
 
-This auto-detects your context file (CLAUDE.md, AGENTS.md, etc.), finds the `<!-- CODE SNAPSHOT -->` markers, re-scans source files, and replaces just that section in-place.
+This finds the `<!-- CODE SNAPSHOT -->` markers in your context file, re-scans source files, and replaces just that section.
 
 ## Shell Integration
 
-Use `--check` to automatically detect stale snapshots when you `cd` into a project:
+Automatically detect stale snapshots when you `cd` into a project:
 
-### zsh
+<details>
+<summary><strong>zsh</strong></summary>
 
 ```zsh
 # Add to ~/.zshrc
@@ -161,7 +310,10 @@ chpwd() {
 }
 ```
 
-### bash
+</details>
+
+<details>
+<summary><strong>bash</strong></summary>
 
 ```bash
 # Add to ~/.bashrc
@@ -173,7 +325,10 @@ cd() {
 }
 ```
 
-### fish
+</details>
+
+<details>
+<summary><strong>fish</strong></summary>
 
 ```fish
 # Add to ~/.config/fish/conf.d/codebrief.fish
@@ -184,6 +339,8 @@ function __codebrief_check --on-variable PWD
 end
 ```
 
+</details>
+
 ## Config File
 
 On first run, codebrief saves your answers to `.codebrief.json`:
@@ -202,23 +359,26 @@ On first run, codebrief saves your answers to `.codebrief.json`:
 }
 ```
 
-Subsequent runs load this config and skip all prompts. Use `--reconfigure` to re-prompt with your saved values as defaults.
+Subsequent runs load this config and skip all prompts. Use `--reconfigure` to re-prompt.
 
-Add `.codebrief.json` to your `.gitignore` — it's a local tool config, not project documentation.
+Add `.codebrief.json` to your `.gitignore`. It's local tool config, not project docs.
 
 ## Framework Conventions
 
-codebrief detects specific frameworks and automatically includes relevant best practices in the generated output:
+codebrief detects your framework and includes relevant best practices:
 
-- **Next.js** — App Router vs Pages Router patterns, server components, route handlers
-- **Express** — middleware chain, error handling, router organization
-- **FastAPI** — dependency injection, Pydantic models, async endpoints
-- **Django** — apps structure, models-views-templates, migrations
-- **NestJS** — modules, controllers, providers, guards
-- **SvelteKit** — load functions, form actions, server routes
-- **Expo / React Native** — routing, native modules, platform-specific files
-- **Vue / Nuxt** — Composition API, auto-imports, data fetching
-- And more: Fastify, Hono, Angular, Svelte, Prisma, Drizzle, Tailwind CSS, Electron
+| Framework | What's included |
+|-----------|----------------|
+| Next.js | App Router vs Pages Router, server components, route handlers |
+| Express | Middleware chain, error handling, router organization |
+| FastAPI | Dependency injection, Pydantic models, async endpoints |
+| Django | Apps structure, models-views-templates, migrations |
+| NestJS | Modules, controllers, providers, guards |
+| SvelteKit | Load functions, form actions, server routes |
+| Expo / React Native | Routing, native modules, platform-specific files |
+| Vue / Nuxt | Composition API, auto-imports, data fetching |
+
+Also supports: Fastify, Hono, Angular, Svelte, Prisma, Drizzle, Tailwind CSS, Electron, and more.
 
 ## Monorepo Support
 
@@ -228,11 +388,11 @@ codebrief detects monorepo tooling and can generate per-package context files:
 - **Turborepo** (`turbo.json`)
 - **Nx** (`nx.json`)
 
-When a monorepo is detected, you'll be asked if you want per-package context files. Each package gets its own scoped context with that package's specific dependencies, frameworks, and code snapshot.
+When detected, you'll be asked if you want per-package files. Each package gets its own scoped context with that package's dependencies, frameworks, and code snapshot.
 
 ## Living Documents
 
-Generated files include maintenance directives telling your AI agent to keep them up to date as the project evolves. The code snapshot section is marked with HTML comments so it's clear what to refresh after refactors.
+Generated files include maintenance directives telling your AI agent to keep them up to date. The code snapshot section uses HTML comment markers (`<!-- CODE SNAPSHOT -->`) so it's clear what to refresh after refactors.
 
 ## Development
 
@@ -241,4 +401,9 @@ npm install
 npm run build      # Build with tsup
 npm run dev        # Watch mode
 npm run typecheck  # Type-check without emitting
+npm test           # Run tests with vitest
 ```
+
+## License
+
+[MIT](LICENSE)