docs: update documentation for v0.4.0 Intelligent Git History

- Add dev_history tool documentation (new MCP tool)
- Update dev_map docs with change frequency feature
- Update dev_plan docs with git history integration
- Update README with v0.4.0 features and version history
- Update tools overview with 9 tools and v0.4.0 section
- Update examples with dev_history usage patterns
- Mark v0.4.0 tasks as complete in PLAN.md
- Add changeset for v0.4.0 release

Author: prosdev

.changeset/intelligent-git-history.md

@@ -0,0 +1,30 @@
+---
+"@lytics/dev-agent": minor
+"@lytics/dev-agent-core": minor
+"@lytics/dev-agent-mcp": minor
+"@lytics/dev-agent-subagents": minor
+---
+
+feat: Intelligent Git History (v0.4.0)
+
+New capabilities for understanding codebase history:
+
+**`dev_history` tool** - Semantic search over git commits
+- Search commit messages by meaning (e.g., "authentication token fix")
+- Get file history with rename tracking
+- Token-budgeted output
+
+**`dev_map` enhancements** - Change frequency indicators
+- 🔥 Hot directories (5+ commits in 30 days)
+- ✏️ Active directories (1-4 commits in 30 days)
+- 📝 Recent activity (commits in 90 days)
+
+**`dev_plan` enhancements** - Git context in planning
+- Related commits shown alongside code snippets
+- Issue/PR references extracted from commits
+- Helps understand prior work on similar features
+
+**Core infrastructure:**
+- `GitIndexer` for semantic commit search
+- `LocalGitExtractor` for git operations
+- Extensible architecture for future git features

PLAN.md

@@ -149,7 +149,7 @@ Focus on quality, documentation, and developer experience.
 
 ---
 
-## Current: Intelligent Git History (v0.4.0)
+## Completed: Intelligent Git History (v0.4.0) ✅
 
 > "Who changed what and why" - completing the context picture.
 
@@ -166,11 +166,11 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 
 | Task | Issue | Status |
 |------|-------|--------|
-| Git types and extractor infrastructure | #91 | 🔲 Todo |
-| Commit indexing in core | #92 | 🔲 Todo |
-| `dev_history` MCP adapter | #93 | 🔲 Todo |
-| Change frequency in `dev_map` | #94 | 🔲 Todo |
-| History integration in `dev_plan` | #95 | 🔲 Todo |
+| Git types and extractor infrastructure | #91 | ✅ Done |
+| Commit indexing in core | #92 | ✅ Done |
+| `dev_history` MCP adapter | #93 | ✅ Done |
+| Change frequency in `dev_map` | #94 | ✅ Done |
+| History integration in `dev_plan` | #95 | ✅ Done |
 
 ### Architecture
 
@@ -179,25 +179,24 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 - Blame methods stubbed (for future `dev_blame`)
 - Cross-repo `repository` field in types
 
-### Out of Scope (v0.5+)
+---
 
-- `dev_blame` (line-level attribution)
-- PR/issue linking from commits
-- Contributor expertise mapping
-- Cross-repo history
+## Current: Extended Git Intelligence (v0.5.0)
 
----
+> Building on git history with deeper insights.
 
-## Future: Extended Intelligence (v0.5+)
+### Tasks
 
-### Git History Enhancements
+| Task | Priority | Status |
+|------|----------|--------|
+| `dev_blame` - line attribution | 🟡 Medium | 🔲 Todo |
+| PR/issue linking from commits | 🟡 Medium | 🔲 Todo |
+| Contributor expertise mapping | 🟢 Low | 🔲 Todo |
+| Cross-repo history | 🟢 Low | 🔲 Todo |
 
-| Feature | Priority |
-|---------|----------|
-| `dev_blame` - line attribution | 🟡 Medium |
-| PR/issue linking from commits | 🟡 Medium |
-| Contributor expertise mapping | 🟢 Low |
-| Cross-repo history | 🟢 Low |
+---
+
+## Future: Extended Intelligence (v0.6+)
 
 ### Multi-Language Support
 

README.md

@@ -4,15 +4,16 @@
 [![pnpm](https://img.shields.io/badge/pnpm-8.15.4-orange.svg)](https://pnpm.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Local-first repository context provider for AI tools. Semantic code search, relationship queries, and codebase mapping via MCP.**
+**Local-first repository context provider for AI tools. Semantic code search, git history, relationship queries, and codebase mapping via MCP.**
 
 ## What is dev-agent?
 
 dev-agent provides **rich, structured context** to AI assistants like Claude and Cursor. Instead of AI tools reading files one at a time, dev-agent gives them:
 
 - 🔍 **Semantic search** with code snippets and relationships
-- 🗺️ **Codebase maps** showing structure and hot paths
+- 🗺️ **Codebase maps** showing structure and change frequency
 - 🔗 **Relationship queries** (what calls what)
+- 📜 **Git history search** (who changed what and why)
 - 📋 **Issue context** assembled for planning
 
 **Philosophy:** Provide data, let LLMs reason. We don't try to be smart with heuristics—we provide comprehensive context so AI assistants can be smart.
@@ -36,7 +37,7 @@ dev mcp install           # For Claude Code
 
 ## MCP Tools
 
-When integrated with Cursor or Claude Code, dev-agent provides 8 powerful tools:
+When integrated with Cursor or Claude Code, dev-agent provides 9 powerful tools:
 
 ### `dev_search` - Semantic Code Search
 Natural language search with rich results including code snippets, imports, and relationships.
@@ -64,17 +65,19 @@ Find what functions validateToken calls
 - File paths and line numbers
 - Relevance scoring
 
-### `dev_map` - Codebase Overview ✨ New in v0.3
-Get a high-level view of repository structure.
+### `dev_map` - Codebase Overview ✨ Enhanced in v0.4
+Get a high-level view of repository structure with change frequency.
 
 ```
 Show me the codebase structure with depth 3
 Focus on the packages/core directory
+Show hot areas with recent changes
 ```
 
 **Features:**
 - Directory tree with component counts
 - **Hot Paths:** Most referenced files
+- **Change Frequency:** 🔥 Hot (5+ commits/30d), ✏️ Active (1-4/30d), 📝 Recent (90d)
 - **Smart Depth:** Adaptive expansion based on density
 - **Signatures:** Function/class signatures in exports
 
@@ -89,13 +92,27 @@ Focus on the packages/core directory
 ## Directory Structure
 
 └── packages/ (195 components)
-    ├── core/ (45 components)
+    ├── 🔥 core/ (45 components) — 12 commits in 30d
     │   └── exports: function search(query): Promise<Result[]>, class RepositoryIndexer
-    ├── mcp-server/ (28 components)
+    ├── ✏️ mcp-server/ (28 components) — 3 commits in 30d
     │   └── exports: class MCPServer, function createAdapter(config): Adapter
 ```
 
-### `dev_plan` - Context Assembly ✨ Refactored in v0.3
+### `dev_history` - Git History Search ✨ New in v0.4
+Semantic search over git commit history.
+
+```
+Find commits about authentication token fixes
+Show history for src/auth/middleware.ts
+```
+
+**Features:**
+- **Semantic search:** Find commits by meaning, not just text
+- **File history:** Track changes with rename detection
+- **Issue/PR refs:** Extracted from commit messages
+- **Token-budgeted output**
+
+### `dev_plan` - Context Assembly ✨ Enhanced in v0.4
 Assemble rich context for implementing GitHub issues.
 
 ```
@@ -105,6 +122,7 @@ Assemble context for issue #42
 **Returns:**
 - Full issue with comments
 - Relevant code snippets from semantic search
+- **Related commits** from git history (new in v0.4)
 - Detected codebase patterns (test naming, locations)
 - Metadata (tokens, timing)
 
@@ -245,6 +263,11 @@ pnpm typecheck
 
 ## Version History
 
+- **v0.4.0** - Intelligent Git History release
+  - New `dev_history` tool for semantic commit search
+  - Enhanced `dev_map` with change frequency indicators (🔥 hot, ✏️ active)
+  - Enhanced `dev_plan` with related commits from git history
+  - New `GitIndexer` and `LocalGitExtractor` in core
 - **v0.3.0** - Context Quality release
   - New `dev_refs` tool for relationship queries
   - Enhanced `dev_map` with hot paths, smart depth, signatures

examples/README.md

@@ -103,13 +103,51 @@ dev_map:
 dev_map:
   includeHotPaths: true
   smartDepth: true
+
+# Show change frequency (v0.4+)
+dev_map:
+  includeChangeFrequency: true
 ```
 
 **Output shows:**
 - Directory structure
 - Component counts per directory
 - Exported symbols with signatures
 - Hot paths (frequently referenced files)
+- Change frequency indicators (🔥 hot, ✏️ active, 📝 recent)
+
+---
+
+### `dev_history` - Git History Search ✨ v0.4
+
+Semantic search over git commits:
+
+```
+# Search commits by meaning
+dev_history:
+  query: "authentication token fix"
+
+# Get file history
+dev_history:
+  mode: "file"
+  file: "src/auth/middleware.ts"
+
+# Filter by author
+dev_history:
+  query: "performance optimization"
+  author: "alice"
+
+# Recent commits only
+dev_history:
+  query: "bug fix"
+  since: "30 days ago"
+```
+
+**Output shows:**
+- Commits with relevance scores
+- Author and date
+- Changed files
+- Issue/PR references extracted from messages
 
 ---
 
@@ -122,7 +160,7 @@ Get rich context for implementing a GitHub issue:
 dev_plan:
   issue: 42
 
-# Full context package
+# Full context package (v0.4+)
 dev_plan:
   issue: 42
   includeCode: true
@@ -133,6 +171,7 @@ dev_plan:
 **Returns:**
 - Issue details (title, body, labels, comments)
 - Relevant code snippets from semantic search
+- **Related commits** from git history (v0.4+)
 - Codebase patterns (test conventions, etc.)
 - Related issues/PRs
 
@@ -238,7 +277,12 @@ dev_health:
    dev_refs: { name: "suspectFunction", direction: "callees" }
    ```
 
-3. **Find similar issues:**
+3. **Find related commits:**
+   ```
+   dev_history: { query: "similar bug fix" }
+   ```
+
+4. **Find similar issues:**
    ```
    dev_gh: { action: "search", query: "similar error" }
    ```
@@ -259,10 +303,15 @@ dev_health:
 
 1. **Understand the change area:**
    ```
-   dev_map: { focus: "path/to/changed/dir" }
+   dev_map: { focus: "path/to/changed/dir", includeChangeFrequency: true }
+   ```
+
+2. **Check file history:**
+   ```
+   dev_history: { mode: "file", file: "path/to/changed/file.ts" }
    ```
 
-2. **Check impact:**
+3. **Check impact:**
    ```
    dev_refs: { name: "changedFunction", direction: "callers" }
    ```

website/content/docs/tools/_meta.js

@@ -3,6 +3,7 @@ export default {
   'dev-search': 'dev_search',
   'dev-refs': 'dev_refs',
   'dev-map': 'dev_map',
+  'dev-history': 'dev_history',
   'dev-plan': 'dev_plan',
   'dev-explore': 'dev_explore',
   'dev-gh': 'dev_gh',