lytics · prosdev · Dec 15, 2025 · Dec 14, 2025 · Dec 15, 2025 · Dec 15, 2025
diff --git a/.changeset/dev-explore-to-dev-inspect.md b/.changeset/dev-explore-to-dev-inspect.md
@@ -0,0 +1,87 @@
+---
+"@lytics/dev-agent-core": patch
+"@lytics/dev-agent-mcp": patch
+"@lytics/dev-agent": patch
+"@lytics/dev-agent-cli": patch
+---
+
+feat(mcp): refactor dev_inspect and optimize pattern analysis
+
+**API Simplification:**
+
+- `dev_inspect` simplified to single-purpose tool (action parameter streamlined)
+- Previously: `dev_inspect({ action: "compare", query: "file.ts" })`
+- Now: `dev_inspect({ query: "file.ts" })`
+- Existing usage continues to work with dynamic MCP schema discovery
+
+**Major Features:**
+
+- Created `PatternAnalysisService` with 5 pattern extractors:
+  - Import style (ESM, CJS, mixed, unknown)
+  - Error handling (throw, result, callback, unknown)
+  - Type coverage (full, partial, none)
+  - Testing (co-located test files)
+  - File size (lines vs similar files)
+- Batch scanning optimization (5-10x faster: 500-1000ms vs 2-3 seconds)
+- Embedding-based similarity search (no more false matches)
+- Extension filtering (`.ts` only compares with `.ts`)
+- Comprehensive pattern analysis (finds similar files + analyzes patterns)
+
+**Performance:**
+
+- One ts-morph initialization vs 6 separate scans
+- Batch scan all files in one pass
+- `searchByDocumentId()` for embedding-based similarity
+- Pattern analysis: 500-1000ms (down from 2-3 seconds)
+
+**Bug Fixes:**
+
+- Fixed `findSimilar` to use document embeddings instead of file paths
+- Fixed `--force` flag to properly clear old vector data
+- Fixed race condition in LanceDB table creation
+- Removed `outputSchema` from all 9 MCP adapters (Cursor/Claude compatibility)
+
+**New Features:**
+
+- Test utilities in `@lytics/dev-agent-core/utils`:
+  - `isTestFile()` — Check if file is a test file
+  - `findTestFile()` — Find co-located test files
+- Vector store `clear()` method
+- Vector store `searchByDocumentId()` method
+- Comprehensive pattern comparison with statistical analysis
+
+**Migration Guide:**
+
+```typescript
+// Before (v0.8.4)
+dev_inspect({ action: "compare", query: "src/auth.ts" })
+dev_inspect({ action: "validate", query: "src/auth.ts" })
+
+// After (v0.8.5) - Streamlined!
+dev_inspect({ query: "src/auth.ts" })
+```
+
+The tool now automatically finds similar files AND performs pattern analysis. No migration needed - MCP tools discover the new schema dynamically.
+
+**Re-index Recommended:**
+
+```bash
+dev index . --force
+```
+
+This clears old data and rebuilds with improved embedding-based search.
+
+**Documentation:**
+
+- Complete rewrite of dev-inspect.mdx
+- Updated README.md with pattern categories
+- Updated CLAUDE.md with new descriptions
+- Added v0.8.5 changelog entry to website
+- Migration guide from dev_explore
+
+**Tests:**
+
+- All 1100+ tests passing
+- Added 10 new test-utils tests
+- Pattern analysis service fully tested
+- Integration tests for InspectAdapter
diff --git a/AGENTS.md b/AGENTS.md
@@ -191,7 +191,7 @@ MCP server with built-in adapters for AI tools.
 - **HistoryAdapter:** Semantic git commit search (`dev_history`)
 - **StatusAdapter:** Repository status (`dev_status`)
 - **PlanAdapter:** Context assembly for issues (`dev_plan`)
-- **ExploreAdapter:** Code exploration (`dev_explore`)
+- **InspectAdapter:** File analysis and pattern checking (`dev_inspect`)
 - **GitHubAdapter:** Issue/PR search (`dev_gh`)
 - **HealthAdapter:** Server health checks (`dev_health`)
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `dev_search` - Semantic code search with type-aware understanding
   - `dev_status` - Repository health and statistics
   - `dev_plan` - Implementation planning from GitHub issues
-  - `dev_explore` - Code pattern discovery and relationship mapping
+  - `dev_inspect` - File analysis (similarity + pattern checking)
   - `dev_gh` - GitHub issue/PR search with offline caching
 - **Multi-language Support** - TypeScript, JavaScript, Go, Python, Rust, Markdown
 - **Local-first Architecture** - All embeddings and indexing run locally

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -168,7 +168,7 @@ Once installed, AI tools gain access to:
 - **`dev_map`** - Codebase structure with component counts and change frequency
 - **`dev_history`** - Semantic search over git commits (who changed what and why)
 - **`dev_plan`** - Assemble context for GitHub issues (code + history + patterns)
-- **`dev_explore`** - Find similar code, trace relationships
+- **`dev_inspect`** - Inspect files for pattern analysis (finds similar code, compares error handling, types, imports, testing)
 - **`dev_gh`** - Search GitHub issues/PRs semantically
 - **`dev_status`** - Repository indexing status
 - **`dev_health`** - Server health checks

diff --git a/PLAN.md b/PLAN.md
@@ -44,7 +44,7 @@ Dev-agent provides semantic code search, codebase intelligence, and GitHub integ
 | Adapter framework | ✅ Done | `@lytics/dev-agent-mcp` |
 | `dev_search` - Semantic code search | ✅ Done | MCP adapter |
 | `dev_status` - Repository status | ✅ Done | MCP adapter |
-| `dev_explore` - Code exploration | ✅ Done | MCP adapter |
+| `dev_inspect` - File analysis | ✅ Done | MCP adapter |
 | `dev_plan` - Issue planning | ✅ Done | MCP adapter |
 | `dev_gh` - GitHub search | ✅ Done | MCP adapter |
 | `dev_health` - Health checks | ✅ Done | MCP adapter |
@@ -219,8 +219,8 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 | Phase | Tool | Status |
 |-------|------|--------|
 | 1 (v0.4.4) | `dev_search` | ✅ Done |
-| 2 | `dev_refs`, `dev_explore` | 🔲 Todo |
-| 3 | `dev_map`, `dev_status` | 🔲 Todo |
+| 2 | `dev_refs`, `dev_inspect` | ✅ Done |
+| 3 | `dev_map`, `dev_status` | ✅ Done |
 
 **Implementation (Phase 1):**
 - After search results, check filesystem for test siblings
@@ -234,7 +234,7 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 |------|--------|
 | Improved dev_search description ("USE THIS FIRST") | ✅ Done |
 | Improved dev_map description (vs list_dir) | ✅ Done |
-| Improved dev_explore description (workflow hints) | ✅ Done |
+| Improved dev_inspect description (file analysis) | ✅ Done |
 | Improved dev_refs description (specific symbols) | ✅ Done |
 | All 9 adapters registered in CLI | ✅ Done |
 

diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ dev-agent indexes your codebase and provides 9 MCP tools to AI assistants. Inste
 - `dev_map` — Codebase structure with change frequency
 - `dev_history` — Semantic search over git commits
 - `dev_plan` — Assemble context for GitHub issues
-- `dev_explore` — Find similar code, trace relationships
+- `dev_inspect` — Inspect files (compare similar code, check patterns)
 - `dev_gh` — Search GitHub issues/PRs semantically
 - `dev_status` / `dev_health` — Monitoring
 
@@ -157,14 +157,21 @@ Assemble context for issue #42
 
 **Note:** This tool no longer generates task breakdowns. It provides comprehensive context so the AI assistant can create better plans.
 
-### `dev_explore` - Code Exploration
-Discover patterns, find similar code, analyze relationships.
+### `dev_inspect` - File Analysis
+Inspect files for pattern analysis. Finds similar code and compares patterns (error handling, type coverage, imports, testing).
 
 ```
-Find code similar to src/auth/middleware.ts
-Search for error handling patterns
+Inspect src/auth/middleware.ts for patterns
+Check how src/hooks/useAuth.ts compares to similar hooks
 ```
 
+**Pattern Categories:**
+- Import style (ESM vs CJS)
+- Error handling (throw vs result types)
+- Type coverage (full, partial, none)
+- Test coverage (co-located test files)
+- File size relative to similar code
+
 ### `dev_status` - Repository Status
 View indexing status, component health, and repository information.
 

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
@@ -456,7 +456,7 @@ dev github index
 **Expected:**
 - `dev_search`: 100-500ms
 - `dev_status`: 50-100ms
-- `dev_explore`: 200-800ms
+- `dev_inspect`: 200-800ms
 - `dev_plan`: 5-15 seconds
 - `dev_gh`: 100-300ms
 
@@ -546,7 +546,7 @@ dev github index
 **Solution:**
 Check the tool's input schema:
 - `dev_search`: Requires `query` (string)
-- `dev_explore`: Requires `action` and `query`
+- `dev_inspect`: Requires `action` and `query` (file path)
 - `dev_plan`: Requires `issue` (number)
 - `dev_gh`: Requires `action`
 
@@ -655,7 +655,7 @@ dev mcp start --verbose
 # In another terminal, send test message
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | dev mcp start
 
-# Should list all 9 tools: dev_search, dev_refs, dev_map, dev_history, dev_status, dev_plan, dev_explore, dev_gh, dev_health
+# Should list all 9 tools: dev_search, dev_refs, dev_map, dev_history, dev_status, dev_plan, dev_inspect, dev_gh, dev_health
 ```
 
 ### Inspect storage
@@ -875,7 +875,7 @@ dev_health
 **Solution:**
 - Index at monorepo root
 - Search works across all projects
-- Use `dev_explore` to find related code
+- Use `dev_inspect` to analyze specific files
 
 ### Non-git repositories
 
@@ -890,7 +890,7 @@ dev_health
 dev index .
 
 # Skip GitHub indexing
-# Just use dev_search, dev_status, dev_explore, dev_plan
+# Just use dev_search, dev_status, dev_inspect, dev_plan
 ```
 
 ### Very large files (>10MB)

diff --git a/biome.json b/biome.json
@@ -26,6 +26,12 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/__fixtures__/**"],
+      "linter": {
+        "enabled": false
+      }
     }
   ],
   "formatter": {

diff --git a/examples/README.md b/examples/README.md
@@ -200,20 +200,20 @@ dev github index
 
 ---
 
-### `dev_explore` - Code Exploration
+### `dev_inspect` - File Analysis
 
-Find patterns and similar code:
+Inspect files and compare implementations:
 
 ```
-# Find patterns
-dev_explore:
-  action: "pattern"
-  query: "error handling middleware"
-
-# Find similar code
-dev_explore:
-  action: "similar"
-  path: "src/utils/retry.ts"
+# Compare similar implementations
+dev_inspect:
+  action: "compare"
+  query: "src/utils/retry.ts"
+
+# Validate pattern consistency (coming soon)
+dev_inspect:
+  action: "validate"
+  query: "src/hooks/useAuth.ts"
 ```
 
 ---
@@ -294,9 +294,9 @@ dev_health:
    dev_plan: { issue: 123 }
    ```
 
-2. **Explore relevant patterns:**
+2. **Search for relevant patterns:**
    ```
-   dev_explore: { action: "pattern", query: "feature type from issue" }
+   dev_search: { query: "feature type from issue" }
    ```
 
 ### Code Review Prep

diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts
@@ -61,7 +61,7 @@ Setup:
   3. Restart Cursor to activate
 
 Available Tools (9):
-  dev_search, dev_status, dev_plan, dev_explore, dev_gh,
+  dev_search, dev_status, dev_plan, dev_inspect, dev_gh,
   dev_health, dev_refs, dev_map, dev_history
 `
   )
@@ -251,7 +251,7 @@ Available Tools (9):
 
           logger.info(chalk.green('MCP server started successfully!'));
           logger.info(
-            'Available tools: dev_search, dev_status, dev_plan, dev_explore, dev_gh, dev_health, dev_refs, dev_map, dev_history'
+            'Available tools: dev_search, dev_status, dev_plan, dev_inspect, dev_gh, dev_health, dev_refs, dev_map, dev_history'
           );
 
           if (options.transport === 'stdio') {

diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
@@ -15,11 +15,5 @@
     { "path": "../logger" }
   ],
   "include": ["src/**/*"],
-  "exclude": [
-    "node_modules",
-    "dist",
-    "**/*.test.ts",
-    "**/*.spec.ts",
-    "**/__tests__/**"
-  ]
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"]
 }
diff --git a/packages/core/src/indexer/index.ts b/packages/core/src/indexer/index.ts
@@ -92,6 +92,13 @@ export class RepositoryIndexer {
     const _documentsIndexed = 0;
 
     try {
+      // Clear vector store if force re-index requested
+      if (options.force) {
+        options.logger?.info('Force re-index requested, clearing existing vectors');
+        await this.vectorStorage.clear();
+        this.state = null; // Reset state to force fresh scan
+      }
+
       // Phase 1: Scan repository
       const onProgress = options.onProgress;
       onProgress?.({
@@ -526,6 +533,14 @@ export class RepositoryIndexer {
     return this.vectorStorage.search(query, options);
   }
 
+  /**
+   * Find similar documents to a given document by ID
+   * More efficient than search() as it reuses the document's existing embedding
+   */
+  async searchByDocumentId(documentId: string, options?: SearchOptions): Promise<SearchResult[]> {
+    return this.vectorStorage.searchByDocumentId(documentId, options);
+  }
+
   /**
    * Get all indexed documents without semantic search (fast scan)
    * Use this when you need all documents and don't need relevance ranking

diff --git a/packages/core/src/observability/README.md b/packages/core/src/observability/README.md
@@ -126,7 +126,7 @@ Track parent-child relationships:
 
 ```typescript
 const parent = tracker.startRequest('dev_plan', { issue: 42 });
-const child = tracker.startRequest('dev_explore', { action: 'pattern' }, parent.requestId);
+const child = tracker.startRequest('dev_inspect', { action: 'compare' }, parent.requestId);
 // child.parentId === parent.requestId
 ```
 
@@ -144,7 +144,7 @@ const metrics = tracker.getMetrics();
 //   p99Duration: 890,
 //   byTool: {
 //     'dev_search': { count: 500, avgDuration: 100 },
-//     'dev_explore': { count: 300, avgDuration: 200 },
+//     'dev_inspect': { count: 300, avgDuration: 200 },
 //     'dev_plan': { count: 200, avgDuration: 180 }
 //   }
 // }

diff --git a/packages/core/src/observability/__tests__/observability.test.ts b/packages/core/src/observability/__tests__/observability.test.ts
@@ -184,11 +184,11 @@ describe('RequestTracker', () => {
   describe('startRequest', () => {
     it('should create request context with unique ID', () => {
       const ctx1 = tracker.startRequest('dev_search', { query: 'auth' });
-      const ctx2 = tracker.startRequest('dev_explore', { action: 'pattern' });
+      const ctx2 = tracker.startRequest('dev_inspect', { action: 'compare' });
 
       expect(ctx1.requestId).not.toBe(ctx2.requestId);
       expect(ctx1.tool).toBe('dev_search');
-      expect(ctx2.tool).toBe('dev_explore');
+      expect(ctx2.tool).toBe('dev_inspect');
     });
 
     it('should emit request.started event', async () => {
@@ -208,7 +208,7 @@ describe('RequestTracker', () => {
 
     it('should track parent ID for nested requests', () => {
       const parent = tracker.startRequest('dev_plan', { issue: 1 });
-      const child = tracker.startRequest('dev_explore', { action: 'pattern' }, parent.requestId);
+      const child = tracker.startRequest('dev_inspect', { action: 'compare' }, parent.requestId);
 
       expect(child.parentId).toBe(parent.requestId);
     });
@@ -282,7 +282,7 @@ describe('RequestTracker', () => {
         tracker.completeRequest(ctx.requestId);
       }
 
-      const ctx = tracker.startRequest('dev_explore', {});
+      const ctx = tracker.startRequest('dev_inspect', {});
       tracker.failRequest(ctx.requestId, 'error');
 
       const metrics = tracker.getMetrics();
@@ -291,7 +291,7 @@ describe('RequestTracker', () => {
       expect(metrics.failed).toBe(1);
       expect(metrics.avgDuration).toBeGreaterThan(0);
       expect(metrics.byTool.dev_search.count).toBe(5);
-      expect(metrics.byTool.dev_explore.count).toBe(1);
+      expect(metrics.byTool.dev_inspect.count).toBe(1);
     });
 
     it('should calculate percentiles', async () => {