From 480c06b3d0e987735179cc36904154c3dca3bb66 Mon Sep 17 00:00:00 2001
From: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date: Sun, 30 Nov 2025 08:38:54 +0800
Subject: [PATCH] Initial commit

---
 .claude-plugin/plugin.json           |   19 +
 README.md                            |    3 +
 agents/codebase-detective.md         |  350 +++++++
 commands/analyze.md                  |  193 ++++
 plugin.lock.json                     |   61 ++
 skills/claudish-usage/SKILL.md       | 1298 ++++++++++++++++++++++++++
 skills/deep-analysis/SKILL.md        |  277 ++++++
 skills/semantic-code-search/SKILL.md |  878 +++++++++++++++++
 8 files changed, 3079 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 README.md
 create mode 100644 agents/codebase-detective.md
 create mode 100644 commands/analyze.md
 create mode 100644 plugin.lock.json
 create mode 100644 skills/claudish-usage/SKILL.md
 create mode 100644 skills/deep-analysis/SKILL.md
 create mode 100644 skills/semantic-code-search/SKILL.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..5095c66
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+  "name": "code-analysis",
+  "description": "Deep code investigation and analysis toolkit. Features the codebase-detective agent for understanding code patterns, relationships, and architecture across complex codebases.",
+  "version": "1.3.3",
+  "author": {
+    "name": "Jack Rudenko",
+    "email": "i@madappgang.com",
+    "company": "MadAppGang"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "agents": [
+    "./agents"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d5a9fc6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# code-analysis
+
+Deep code investigation and analysis toolkit. Features the codebase-detective agent for understanding code patterns, relationships, and architecture across complex codebases.
diff --git a/agents/codebase-detective.md b/agents/codebase-detective.md
new file mode 100644
index 0000000..bee2cf5
--- /dev/null
+++ b/agents/codebase-detective.md
@@ -0,0 +1,350 @@
+---
+name: detective
+description: Use this agent when you need to investigate, analyze, or understand patterns in a codebase. This includes finding specific implementations, understanding code relationships, discovering usage patterns, tracking down bugs, analyzing architecture decisions, or investigating how certain features work. The agent excels at deep-dive investigations that require examining multiple files and understanding complex code relationships.\n\nExamples:\n- <example>\n  Context: The user wants to understand how authentication is implemented across the codebase.\n  user: "How is authentication handled in this application?"\n  assistant: "I'll use the codebase-detective agent to investigate the authentication implementation."\n  <commentary>\n  Since the user is asking about understanding a specific aspect of the codebase, use the Task tool to launch the codebase-detective agent to analyze authentication patterns.\n  </commentary>\n</example>\n- <example>\n  Context: The user needs to find all places where a specific API endpoint is called.\n  user: "Where is the /api/users endpoint being called from?"\n  assistant: "Let me launch the codebase-detective agent to track down all calls to that endpoint."\n  <commentary>\n  The user needs to trace usage patterns, so use the codebase-detective agent to investigate API endpoint usage.\n  </commentary>\n</example>\n- <example>\n  Context: The user is trying to understand why a feature isn't working as expected.\n  user: "The payment processing seems broken - can you investigate what might be wrong?"\n  assistant: "I'll use the codebase-detective agent to investigate the payment processing implementation and identify potential issues."\n  <commentary>\n  Debugging requires deep investigation, so use the codebase-detective agent to analyze the payment processing code.\n  </commentary>\n</example>
+color: blue
+---
+
+You are CodebaseDetective, a code navigation specialist. You help users quickly find specific code, understand relationships, and navigate complex codebases efficiently.
+
+## Core Mission
+
+Navigate codebases to find specific implementations, understand code flow, and locate exact pieces of functionality users are looking for.
+
+## Navigation Approach
+
+### With MCP Tools Available
+
+1. **Index**: `index_codebase` with appropriate settings
+2. **Search**: Use semantic queries to find relevant code
+3. **Trace**: Follow relationships between components
+4. **Pinpoint**: Provide exact file locations and context
+
+### Fallback Mode (No MCP Tools)
+
+When Claude-Context tools unavailable, use standard commands:
+
+1. **Map Structure**: `ls -la`, `find`, `tree`
+2. **Search Patterns**: `grep -r`, `rg` (ripgrep), `ag` (silver searcher)
+3. **Read Files**: `cat`, `head`, `tail` for specific files
+4. **Follow Imports**: Trace dependencies manually
+5. **Use Git**: `git grep`, `git ls-files`
+
+## Navigation Workflows
+
+### 🎯 Finding Specific Functionality
+
+```typescript
+// With MCP:
+index_codebase with path: "/project"
+search_code with query: "user registration signup flow"
+search_code with query: "email validation verify"
+
+// Fallback:
+grep -r "register\|signup\|createUser" . --include="*.ts"
+find . -name "*register*" -o -name "*signup*"
+rg "func.*Register|type.*Registration" --type go
+```
+
+### 🗺️ Tracing Code Flow
+
+```typescript
+// With MCP:
+search_code with query: "HTTP handler for POST /api/users"
+search_code with query: "UserService.create method implementation"
+search_code with query: "where UserRepository save is called"
+
+// Fallback:
+grep -r "POST.*users\|post.*users" . --include="*.ts"
+grep -r "class UserService\|func.*UserService" .
+rg "UserRepository.*save|repository.Save" --type go
+```
+
+### 🔗 Finding Dependencies
+
+```typescript
+// With MCP:
+search_code with query: "imports from auth module"
+search_code with query: "where JWTService is used"
+search_code with query: "database connection initialization"
+
+// Fallback:
+grep -r "import.*from.*auth" . --include="*.ts"
+grep -r "JWTService\|jwtService" . --include="*.ts"
+rg "import.*database|require.*database" --type ts
+```
+
+### 📦 Locating Configurations
+
+```golang
+// With MCP:
+search_code with query: "environment variables configuration loading"
+search_code with query: "database connection string setup"
+search_code with query: "server port listening configuration"
+
+// Fallback:
+grep -r "os.Getenv\|viper\|config" . --include="*.go"
+find . -name "*config*" -o -name "*.env*"
+rg "Listen|ListenAndServe|port" --type go
+```
+
+## Common Navigation Patterns
+
+### TypeScript/Node.js Projects
+
+```typescript
+// Finding Express/Fastify routes
+// MCP:
+search_code with query: "router.get router.post app.get app.post route handlers"
+
+// Fallback:
+grep -r "router\.\(get\|post\|put\|delete\)" . --include="*.ts"
+rg "@Get|@Post|@Controller" --type ts  // NestJS
+find . -path "*/routes/*" -name "*.ts"
+
+// Finding service implementations
+// MCP:
+search_code with query: "class service implements injectable"
+
+// Fallback:
+grep -r "class.*Service\|@Injectable" . --include="*.ts"
+rg "export class.*Service" --type ts
+```
+
+### Go Projects
+
+```golang
+// Finding HTTP handlers
+// MCP:
+search_code with query: "http.HandlerFunc ServeHTTP gin.Context"
+
+// Fallback:
+grep -r "func.*Handler\|HandlerFunc" . --include="*.go"
+rg "gin.Context|echo.Context|http.HandlerFunc" --type go
+find . -path "*/handlers/*" -name "*.go"
+
+// Finding struct definitions
+// MCP:
+search_code with query: "type User struct model definition"
+
+// Fallback:
+grep -r "type.*struct" . --include="*.go" | grep -i user
+rg "type\s+\w+\s+struct" --type go
+```
+
+## Quick Location Commands
+
+### TypeScript Project Navigation
+
+```bash
+# Find entry point
+ls src/index.* src/main.* src/app.*
+
+# Find all controllers (NestJS)
+find . -name "*.controller.ts"
+
+# Find all services
+find . -name "*.service.ts"
+
+# Find test files
+find . -name "*.spec.ts" -o -name "*.test.ts"
+
+# Find interfaces/types
+find . -name "*.interface.ts" -o -name "*.type.ts"
+grep -r "interface\|type.*=" . --include="*.ts" | head -20
+```
+
+### Go Project Navigation
+
+```bash
+# Find main package
+find . -name "main.go"
+
+# Find all handlers
+find . -path "*/handler*" -name "*.go"
+find . -path "*/controller*" -name "*.go"
+
+# Find models
+find . -path "*/model*" -name "*.go"
+grep -r "type.*struct" . --include="*.go" | grep -v test
+
+# Find interfaces
+grep -r "type.*interface" . --include="*.go"
+
+# Find go.mod for dependencies
+cat go.mod
+```
+
+## Search Query Templates
+
+### Semantic Searches (MCP)
+
+- "WebSocket connection handler implementation"
+- "middleware that checks authentication"
+- "where user data is validated"
+- "GraphQL resolver for user queries"
+- "background job processing worker"
+- "cache invalidation logic"
+- "file upload handling"
+- "pagination implementation"
+
+### Pattern Searches (Fallback)
+
+```bash
+# TypeScript patterns
+"class.*Controller"          # Controllers
+"@Module|@Injectable"         # NestJS
+"express.Router()"           # Express routes
+"interface.*Props"           # React props
+"useState|useEffect"         # React hooks
+"async.*await|Promise"       # Async code
+
+# Go patterns
+"func.*\(.*\*.*\)"          # Methods with pointer receivers
+"go func"                    # Goroutines
+"chan\s+\w+"                # Channels
+"context\.Context"          # Context usage
+"defer\s+"                  # Defer statements
+"\*\w+Repository"           # Repository pattern
+```
+
+## Navigation Strategies
+
+### 1. Top-Down Exploration
+
+```typescript
+// Start from entry point
+// MCP:
+search_code with query: "main function application entry"
+
+// Fallback:
+cat src/index.ts src/main.ts
+cat cmd/main.go main.go
+```
+
+### 2. Bottom-Up Discovery
+
+```typescript
+// Start from specific functionality
+// MCP:
+search_code with query: "specific function or class name"
+
+// Fallback:
+grep -r "functionName" . --include="*.ts"
+rg "SpecificClass" --type go
+```
+
+### 3. Follow the Imports
+
+```typescript
+// Trace dependencies
+// MCP:
+search_code with query: "import UserService from"
+
+// Fallback:
+grep -r "import.*UserService" . --include="*.ts"
+grep -r "import.*\".*user" . --include="*.go"
+```
+
+## Output Format
+
+### 📍 Location Report: [What You're Looking For]
+
+**Search Method**: [MCP/Fallback]
+
+**Found In**:
+
+- Primary: `src/services/user.service.ts:45-67`
+- Related: `src/controllers/user.controller.ts:23`
+- Tests: `src/services/user.service.spec.ts`
+
+**Code Structure**:
+
+```
+src/
+├── services/
+│   └── user.service.ts  <-- Main implementation
+├── controllers/
+│   └── user.controller.ts  <-- Uses the service
+└── repositories/
+    └── user.repository.ts  <-- Data layer
+```
+
+**How to Navigate There**:
+
+1. Open main file: `cat src/services/user.service.ts`
+2. Check usage: `grep -r "UserService" . --include="*.ts"`
+3. See tests: `cat src/services/user.service.spec.ts`
+
+## Decision Flow
+
+1. **Try MCP First**:
+   ```
+   index_codebase with path: "/project"
+   ```
+2. **If MCP Unavailable**:
+
+   ```bash
+   # Get overview
+   tree -L 2 -I 'node_modules|vendor'
+
+   # Search for your target
+   rg "targetFunction" --type ts --type go
+   ```
+
+3. **Refine Search**:
+   - Too many results? Add context: `"class.*targetFunction"`
+   - No results? Broaden: Remove specific terms, try synonyms
+   - Check different file extensions: `.ts`, `.tsx`, `.go`, `.js`
+
+## Quick Navigation Tips
+
+- **Always start with structure**: Understand folder organization
+- **Use semantic search (MCP)** for concepts and functionality
+- **Use pattern search (grep)** for specific syntax and names
+- **Follow the breadcrumbs**: One file often leads to another
+- **Check tests**: They often show how code is used
+
+````
+
+## Practical Examples
+
+### Finding API Endpoint Implementation
+```typescript
+// User wants to find: "Where is the login endpoint?"
+
+// MCP Approach:
+index_codebase with path: "/project"
+search_code with query: "login endpoint POST authentication"
+
+// Fallback Approach:
+grep -r "login" . --include="*.ts" | grep -i "post\|route"
+rg "/login|/auth" --type ts
+find . -name "*auth*" -o -name "*login*"
+````
+
+### Locating Database Operations
+
+```golang
+// User wants to find: "Where do we save user data?"
+
+// MCP Approach:
+search_code with query: "save user database insert create"
+
+// Fallback Approach:
+grep -r "Save\|Insert\|Create" . --include="*.go" | grep -i user
+rg "func.*Save.*User|CreateUser|InsertUser" --type go
+```
+
+### Finding Configuration Loading
+
+```typescript
+// User wants to find: "Where is the config loaded?"
+
+// MCP Approach:
+search_code with query: "configuration loading environment variables"
+
+// Fallback Approach:
+grep -r "process.env\|config" . --include="*.ts"
+find . -name "*config*" | xargs ls -la
+cat src/config/* env.d.ts .env.example
+```
diff --git a/commands/analyze.md b/commands/analyze.md
new file mode 100644
index 0000000..15d90c5
--- /dev/null
+++ b/commands/analyze.md
@@ -0,0 +1,193 @@
+---
+description: Deep codebase investigation to understand architecture, trace functionality, find implementations, and analyze code patterns
+allowed-tools: Task, AskUserQuestion, Bash, Read, TodoWrite, Glob, Grep
+---
+
+## Mission
+
+Launch the codebase-detective agent to perform comprehensive code analysis, investigation, and navigation across complex codebases. This command helps understand how code works, find specific implementations, trace functionality flow, and analyze architectural patterns.
+
+## Analysis Request
+
+$ARGUMENTS
+
+## When to Use This Command
+
+Use `/analyze` when you need to:
+
+- **Understand Architecture**: How is authentication implemented? What's the database layer structure?
+- **Find Implementations**: Where is the user registration logic? Which file handles payments?
+- **Trace Functionality**: Follow the flow from API endpoint to database
+- **Debug Issues**: Why isn't the login working? Where is this error coming from?
+- **Find Patterns**: Where are all the API calls made? What components use Redux?
+- **Analyze Dependencies**: What uses this service? Where is this utility imported?
+
+## How It Works
+
+This command launches the **codebase-detective** agent, which:
+
+1. Uses semantic code search (MCP claude-context) when available
+2. Falls back to standard grep/find/rg tools when needed
+3. Traces imports and dependencies across files
+4. Analyzes code structure and patterns
+5. Provides exact file locations with line numbers
+6. Explains code relationships and flow
+
+## Instructions
+
+### Step 1: Understand the Request
+
+Parse the user's analysis request from $ARGUMENTS:
+
+- What are they trying to understand?
+- What specific code/functionality are they looking for?
+- What's the context (debugging, learning, refactoring)?
+
+### Step 2: Launch codebase-detective Agent
+
+Use the Task tool to launch the agent:
+
+```
+Task(
+  subagent_type: "code-analysis:detective",
+  description: "Analyze codebase for [brief description]",
+  prompt: `
+    Investigate the following in the codebase:
+
+    [User's analysis request from $ARGUMENTS]
+
+    Working directory: [current working directory]
+
+    Please provide:
+    1. Exact file locations with line numbers
+    2. Code snippets showing the implementation
+    3. Explanation of how the code works
+    4. Related files and dependencies
+    5. Code flow/architecture diagram if complex
+
+    Use semantic search (claude-context MCP) if available, otherwise
+    use grep/ripgrep/find for pattern matching.
+  `
+)
+```
+
+### Step 3: Present Results
+
+After the agent completes:
+
+1. **Summarize Findings**: Key files, main implementation locations
+2. **Show Code Structure**: How components relate to each other
+3. **Provide Next Steps**: Suggestions for what to do with this information
+4. **Offer Follow-up**: Ask if they want deeper analysis of specific parts
+
+## Example Usage
+
+### Example 1: Finding Authentication Logic
+
+```
+User: /analyze Where is user authentication handled?
+
+Agent launches with prompt:
+"Find and explain the authentication implementation. Include:
+- Login endpoint/handler
+- Token generation/validation
+- Authentication middleware
+- Session management
+- Related security code"
+
+Results:
+- src/auth/login.handler.ts:23-67 (login endpoint)
+- src/middleware/auth.middleware.ts:12-45 (JWT validation)
+- src/services/token.service.ts:89-120 (token generation)
+```
+
+### Example 2: Tracing Bug
+
+```
+User: /analyze The user profile page shows "undefined" for email field
+
+Agent launches with prompt:
+"Trace the user profile email display issue:
+1. Find the profile page component
+2. Locate where email data is fetched
+3. Check how email is passed to the component
+4. Identify where 'undefined' might be introduced"
+
+Results:
+- Identified missing null check in ProfilePage.tsx:156
+- Found API returns 'e-mail' but code expects 'email'
+- Provided exact line numbers for the mismatch
+```
+
+### Example 3: Understanding Architecture
+
+```
+User: /analyze How does the payment processing flow work?
+
+Agent launches with prompt:
+"Map out the complete payment processing flow:
+1. Entry point (API endpoint or UI trigger)
+2. Validation and business logic
+3. Payment gateway integration
+4. Database persistence
+5. Success/failure handling
+6. Related services and utilities"
+
+Results:
+- Flow diagram from checkout button to confirmation
+- 7 key files involved with their roles
+- External dependencies (Stripe SDK)
+- Error handling strategy
+```
+
+## Tips for Effective Analysis
+
+1. **Be Specific**: Instead of "analyze the codebase", ask "where is the email validation logic?"
+2. **Provide Context**: Mention if you're debugging, refactoring, or learning
+3. **Ask Follow-ups**: After initial results, drill deeper into specific files
+4. **Use for Navigation**: Get oriented in unfamiliar codebases quickly
+
+## Output Format
+
+The agent will provide:
+
+```
+📍 Location Report: [What was analyzed]
+
+**Primary Files**:
+- path/to/main/file.ts:45-67 - [Brief description]
+- path/to/related/file.ts:23 - [Brief description]
+
+**Code Flow**:
+1. Entry point: [File:line]
+2. Processing: [File:line]
+3. Result: [File:line]
+
+**Related Components**:
+- [Component name] - [Purpose]
+- [Service name] - [Purpose]
+
+**How to Navigate**:
+[Commands to explore the code further]
+
+**Recommendations**:
+[Suggestions based on analysis]
+```
+
+## Success Criteria
+
+The command is successful when:
+
+1. ✅ User's question is fully answered with exact locations
+2. ✅ Code relationships and flow are clearly explained
+3. ✅ File paths and line numbers are provided
+4. ✅ User can navigate to the code and understand it
+5. ✅ Follow-up questions are anticipated and addressed
+
+## Notes
+
+- The codebase-detective agent is optimized for speed and accuracy
+- It will use the best available tools (MCP search or grep/ripgrep)
+- Results include actionable next steps
+- Can handle complex, multi-file investigations
+- Excellent for onboarding to new codebases
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..7b6e767
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:MadAppGang/claude-code:plugins/code-analysis",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "4f16b4a282b9bf71204a1591d80e9257a5ae4f78",
+    "treeHash": "94547acde711643c8ea0ed22c064ba63a44f96dcaf4a4bd2f5e01aed9467f1e2",
+    "generatedAt": "2025-11-28T10:12:05.375590Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "code-analysis",
+    "description": "Deep code investigation and analysis toolkit. Features the codebase-detective agent for understanding code patterns, relationships, and architecture across complex codebases.",
+    "version": "1.3.3"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "c331c7016c66769955d81c1313cc63f230c3c40c76b86da076fdcad1e36b5d82"
+      },
+      {
+        "path": "agents/codebase-detective.md",
+        "sha256": "fc2b45e3b6965e91cca1a7a7c08ae93efa040b53a4e34bea4236786f540e7a7e"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "74f8f8ed771a0c7e98bdac2dddc5742fc381cf3508bf484d22f2f25b10c3f055"
+      },
+      {
+        "path": "commands/analyze.md",
+        "sha256": "1b1cb98fc23540b42799a17053d8edff9f6214d7a0976be0e8316b9573c05c3b"
+      },
+      {
+        "path": "skills/claudish-usage/SKILL.md",
+        "sha256": "3acc6b43aa094d7fc703018f91751565f97a88870b4a9d38cc60ad4210c513f6"
+      },
+      {
+        "path": "skills/deep-analysis/SKILL.md",
+        "sha256": "b61dee5c3276a857250a3910b730b7f5ae7761efd0862036253206a767383965"
+      },
+      {
+        "path": "skills/semantic-code-search/SKILL.md",
+        "sha256": "e316b64d5ca0135d610d67860a94f6226eb952d750c71ae40648ae002e144a80"
+      }
+    ],
+    "dirSha256": "94547acde711643c8ea0ed22c064ba63a44f96dcaf4a4bd2f5e01aed9467f1e2"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/skills/claudish-usage/SKILL.md b/skills/claudish-usage/SKILL.md
new file mode 100644
index 0000000..6f0d1ff
--- /dev/null
+++ b/skills/claudish-usage/SKILL.md
@@ -0,0 +1,1298 @@
+---
+name: claudish-usage
+description: CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.
+---
+
+# Claudish Usage Skill
+
+**Version:** 1.1.0
+**Purpose:** Guide AI agents on how to use Claudish CLI to run Claude Code with OpenRouter models
+**Status:** Production Ready
+
+## ⚠️ CRITICAL RULES - READ FIRST
+
+### 🚫 NEVER Run Claudish from Main Context
+
+**Claudish MUST ONLY be run through sub-agents** unless the user **explicitly** requests direct execution.
+
+**Why:**
+- Running Claudish directly pollutes main context with 10K+ tokens (full conversation + reasoning)
+- Destroys context window efficiency
+- Makes main conversation unmanageable
+
+**When you can run Claudish directly:**
+- ✅ User explicitly says "run claudish directly" or "don't use a sub-agent"
+- ✅ User is debugging and wants to see full output
+- ✅ User specifically requests main context execution
+
+**When you MUST use sub-agent:**
+- ✅ User says "use Grok to implement X" (delegate to sub-agent)
+- ✅ User says "ask GPT-5 to review X" (delegate to sub-agent)
+- ✅ User mentions any model name without "directly" (delegate to sub-agent)
+- ✅ Any production task (always delegate)
+
+### 📋 Workflow Decision Tree
+
+```
+User Request
+    ↓
+Does it mention Claudish/OpenRouter/model name? → NO → Don't use this skill
+    ↓ YES
+    ↓
+Does user say "directly" or "in main context"? → YES → Run in main context (rare)
+    ↓ NO
+    ↓
+Find appropriate agent or create one → Delegate to sub-agent (default)
+```
+
+## 🤖 Agent Selection Guide
+
+### Step 1: Find the Right Agent
+
+**When user requests Claudish task, follow this process:**
+
+1. **Check for existing agents** that support proxy mode or external model delegation
+2. **If no suitable agent exists:**
+   - Suggest creating a new proxy-mode agent for this task type
+   - Offer to proceed with generic `general-purpose` agent if user declines
+3. **If user declines agent creation:**
+   - Warn about context pollution
+   - Ask if they want to proceed anyway
+
+### Step 2: Agent Type Selection Matrix
+
+| Task Type | Recommended Agent | Fallback | Notes |
+|-----------|------------------|----------|-------|
+| **Code implementation** | Create coding agent with proxy mode | `general-purpose` | Best: custom agent for project-specific patterns |
+| **Code review** | Use existing code review agent + proxy | `general-purpose` | Check if plugin has review agent first |
+| **Architecture planning** | Use existing architect agent + proxy | `general-purpose` | Look for `architect` or `planner` agents |
+| **Testing** | Use existing test agent + proxy | `general-purpose` | Look for `test-architect` or `tester` agents |
+| **Refactoring** | Create refactoring agent with proxy | `general-purpose` | Complex refactors benefit from specialized agent |
+| **Documentation** | `general-purpose` | - | Simple task, generic agent OK |
+| **Analysis** | Use existing analysis agent + proxy | `general-purpose` | Check for `analyzer` or `detective` agents |
+| **Other** | `general-purpose` | - | Default for unknown task types |
+
+### Step 3: Agent Creation Offer (When No Agent Exists)
+
+**Template response:**
+```
+I notice you want to use [Model Name] for [task type].
+
+RECOMMENDATION: Create a specialized [task type] agent with proxy mode support.
+
+This would:
+✅ Provide better task-specific guidance
+✅ Reusable for future [task type] tasks
+✅ Optimized prompting for [Model Name]
+
+Options:
+1. Create specialized agent (recommended) - takes 2-3 minutes
+2. Use generic general-purpose agent - works but less optimized
+3. Run directly in main context (NOT recommended - pollutes context)
+
+Which would you prefer?
+```
+
+### Step 4: Common Agents by Plugin
+
+**Frontend Plugin:**
+- `typescript-frontend-dev` - Use for UI implementation with external models
+- `frontend-architect` - Use for architecture planning with external models
+- `senior-code-reviewer` - Use for code review (can delegate to external models)
+- `test-architect` - Use for test planning/implementation
+
+**Bun Backend Plugin:**
+- `backend-developer` - Use for API implementation with external models
+- `api-architect` - Use for API design with external models
+
+**Code Analysis Plugin:**
+- `codebase-detective` - Use for investigation tasks with external models
+
+**No Plugin:**
+- `general-purpose` - Default fallback for any task
+
+### Step 5: Example Agent Selection
+
+**Example 1: User says "use Grok to implement authentication"**
+```
+Task: Code implementation (authentication)
+Plugin: Bun Backend (if backend) or Frontend (if UI)
+
+Decision:
+1. Check for backend-developer or typescript-frontend-dev agent
+2. Found backend-developer? → Use it with Grok proxy
+3. Not found? → Offer to create custom auth agent
+4. User declines? → Use general-purpose with file-based pattern
+```
+
+**Example 2: User says "ask GPT-5 to review my API design"**
+```
+Task: Code review (API design)
+Plugin: Bun Backend
+
+Decision:
+1. Check for api-architect or senior-code-reviewer agent
+2. Found? → Use it with GPT-5 proxy
+3. Not found? → Use general-purpose with review instructions
+4. Never run directly in main context
+```
+
+**Example 3: User says "use Gemini to refactor this component"**
+```
+Task: Refactoring (component)
+Plugin: Frontend
+
+Decision:
+1. No specialized refactoring agent exists
+2. Offer to create component-refactoring agent
+3. User declines? → Use typescript-frontend-dev with proxy
+4. Still no agent? → Use general-purpose with file-based pattern
+```
+
+## Overview
+
+**Claudish** is a CLI tool that allows running Claude Code with any OpenRouter model (Grok, GPT-5, MiniMax, Gemini, etc.) by proxying requests through a local Anthropic API-compatible server.
+
+**Key Principle:** **ALWAYS** use Claudish through sub-agents with file-based instructions to avoid context window pollution.
+
+## What is Claudish?
+
+Claudish (Claude-ish) is a proxy tool that:
+- ✅ Runs Claude Code with **any OpenRouter model** (not just Anthropic models)
+- ✅ Uses local API-compatible proxy server
+- ✅ Supports 100% of Claude Code features
+- ✅ Provides cost tracking and model selection
+- ✅ Enables multi-model workflows
+
+**Use Cases:**
+- Run tasks with different AI models (Grok for speed, GPT-5 for reasoning, Gemini for vision)
+- Compare model performance on same task
+- Reduce costs with cheaper models for simple tasks
+- Access models with specialized capabilities
+
+## Requirements
+
+### System Requirements
+- **OpenRouter API Key** - Required (set as `OPENROUTER_API_KEY` environment variable)
+- **Claudish CLI** - Install with: `npm install -g claudish` or `bun install -g claudish`
+- **Claude Code** - Must be installed
+
+### Environment Variables
+
+```bash
+# Required
+export OPENROUTER_API_KEY='sk-or-v1-...'  # Your OpenRouter API key
+
+# Optional (but recommended)
+export ANTHROPIC_API_KEY='sk-ant-api03-placeholder'  # Prevents Claude Code dialog
+
+# Optional - default model
+export CLAUDISH_MODEL='x-ai/grok-code-fast-1'  # or ANTHROPIC_MODEL
+```
+
+**Get OpenRouter API Key:**
+1. Visit https://openrouter.ai/keys
+2. Sign up (free tier available)
+3. Create API key
+4. Set as environment variable
+
+## Quick Start Guide
+
+### Step 1: Install Claudish
+
+```bash
+# With npm (works everywhere)
+npm install -g claudish
+
+# With Bun (faster)
+bun install -g claudish
+
+# Verify installation
+claudish --version
+```
+
+### Step 2: Get Available Models
+
+```bash
+# List ALL OpenRouter models grouped by provider
+claudish --models
+
+# Fuzzy search models by name, ID, or description
+claudish --models gemini
+claudish --models "grok code"
+
+# Show top recommended programming models (curated list)
+claudish --top-models
+
+# JSON output for parsing
+claudish --models --json
+claudish --top-models --json
+
+# Force update from OpenRouter API
+claudish --models --force-update
+```
+
+### Step 3: Run Claudish
+
+**Interactive Mode (default):**
+```bash
+# Shows model selector, persistent session
+claudish
+```
+
+**Single-shot Mode:**
+```bash
+# One task and exit (requires --model)
+claudish --model x-ai/grok-code-fast-1 "implement user authentication"
+```
+
+**With stdin for large prompts:**
+```bash
+# Read prompt from stdin (useful for git diffs, code review)
+git diff | claudish --stdin --model openai/gpt-5-codex "Review these changes"
+```
+
+## Recommended Models
+
+**Top Models for Development (verified from OpenRouter):**
+
+1. **x-ai/grok-code-fast-1** - xAI's Grok (fast coding, visible reasoning)
+   - Category: coding
+   - Context: 256K
+   - Best for: Quick iterations, agentic coding
+
+2. **google/gemini-2.5-flash** - Google's Gemini (state-of-the-art reasoning)
+   - Category: reasoning
+   - Context: 1000K
+   - Best for: Complex analysis, multi-step reasoning
+
+3. **minimax/minimax-m2** - MiniMax M2 (high performance)
+   - Category: coding
+   - Context: 128K
+   - Best for: General coding tasks
+
+4. **openai/gpt-5** - OpenAI's GPT-5 (advanced reasoning)
+   - Category: reasoning
+   - Context: 128K
+   - Best for: Complex implementations, architecture decisions
+
+5. **qwen/qwen3-vl-235b-a22b-instruct** - Alibaba's Qwen (vision-language)
+   - Category: vision
+   - Context: 32K
+   - Best for: UI/visual tasks, design implementation
+
+**Get Latest Models:**
+```bash
+# List all models (auto-updates every 2 days)
+claudish --models
+
+# Search for specific models
+claudish --models grok
+claudish --models "gemini flash"
+
+# Show curated top models
+claudish --top-models
+
+# Force immediate update
+claudish --models --force-update
+```
+
+## NEW: Direct Agent Selection (v2.1.0)
+
+**Use `--agent` flag to invoke agents directly without the file-based pattern:**
+
+```bash
+# Use specific agent (prepends @agent- automatically)
+claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "implement React component"
+
+# Claude receives: "Use the @agent-frontend:developer agent to: implement React component"
+
+# List available agents in project
+claudish --list-agents
+```
+
+**When to use `--agent` vs file-based pattern:**
+
+**Use `--agent` when:**
+- Single, simple task that needs agent specialization
+- Direct conversation with one agent
+- Testing agent behavior
+- CLI convenience
+
+**Use file-based pattern when:**
+- Complex multi-step workflows
+- Multiple agents needed
+- Large codebases
+- Production tasks requiring review
+- Need isolation from main conversation
+
+**Example comparisons:**
+
+**Simple task (use `--agent`):**
+```bash
+claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "create button component"
+```
+
+**Complex task (use file-based):**
+```typescript
+// multi-phase-workflow.md
+Phase 1: Use api-architect to design API
+Phase 2: Use backend-developer to implement
+Phase 3: Use test-architect to add tests
+Phase 4: Use senior-code-reviewer to review
+
+then:
+claudish --model x-ai/grok-code-fast-1 --stdin < multi-phase-workflow.md
+```
+
+## Best Practice: File-Based Sub-Agent Pattern
+
+### ⚠️ CRITICAL: Don't Run Claudish Directly from Main Conversation
+
+**Why:** Running Claudish directly in main conversation pollutes context window with:
+- Entire conversation transcript
+- All tool outputs
+- Model reasoning (can be 10K+ tokens)
+
+**Solution:** Use file-based sub-agent pattern
+
+### File-Based Pattern (Recommended)
+
+**Step 1: Create instruction file**
+```markdown
+# /tmp/claudish-task-{timestamp}.md
+
+## Task
+Implement user authentication with JWT tokens
+
+## Requirements
+- Use bcrypt for password hashing
+- Generate JWT with 24h expiration
+- Add middleware for protected routes
+
+## Deliverables
+Write implementation to: /tmp/claudish-result-{timestamp}.md
+
+## Output Format
+```markdown
+## Implementation
+
+[code here]
+
+## Files Created/Modified
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Tests
+[test code if applicable]
+
+## Notes
+[any important notes]
+```
+```
+
+**Step 2: Run Claudish with file instruction**
+```bash
+# Read instruction from file, write result to file
+claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-task-{timestamp}.md > /tmp/claudish-result-{timestamp}.md
+```
+
+**Step 3: Read result file and provide summary**
+```typescript
+// In your agent/command:
+const result = await Read({ file_path: "/tmp/claudish-result-{timestamp}.md" });
+
+// Parse result
+const filesModified = extractFilesModified(result);
+const summary = extractSummary(result);
+
+// Provide short feedback to main agent
+return `✅ Task completed. Modified ${filesModified.length} files. ${summary}`;
+```
+
+### Complete Example: Using Claudish in Sub-Agent
+
+```typescript
+/**
+ * Example: Run code review with Grok via Claudish sub-agent
+ */
+async function runCodeReviewWithGrok(files: string[]) {
+  const timestamp = Date.now();
+  const instructionFile = `/tmp/claudish-review-instruction-${timestamp}.md`;
+  const resultFile = `/tmp/claudish-review-result-${timestamp}.md`;
+
+  // Step 1: Create instruction file
+  const instruction = `# Code Review Task
+
+## Files to Review
+${files.map(f => `- ${f}`).join('\n')}
+
+## Review Criteria
+- Code quality and maintainability
+- Potential bugs or issues
+- Performance considerations
+- Security vulnerabilities
+
+## Output Format
+Write your review to: ${resultFile}
+
+Use this format:
+\`\`\`markdown
+## Summary
+[Brief overview]
+
+## Issues Found
+### Critical
+- [issue 1]
+
+### Medium
+- [issue 2]
+
+### Low
+- [issue 3]
+
+## Recommendations
+- [recommendation 1]
+
+## Files Reviewed
+- [file 1]: [status]
+\`\`\`
+`;
+
+  await Write({ file_path: instructionFile, content: instruction });
+
+  // Step 2: Run Claudish with stdin
+  await Bash(`claudish --model x-ai/grok-code-fast-1 --stdin < ${instructionFile}`);
+
+  // Step 3: Read result
+  const result = await Read({ file_path: resultFile });
+
+  // Step 4: Parse and return summary
+  const summary = extractSummary(result);
+  const issueCount = extractIssueCount(result);
+
+  // Step 5: Clean up temp files
+  await Bash(`rm ${instructionFile} ${resultFile}`);
+
+  // Step 6: Return concise feedback
+  return {
+    success: true,
+    summary,
+    issueCount,
+    fullReview: result  // Available if needed, but not in main context
+  };
+}
+
+function extractSummary(review: string): string {
+  const match = review.match(/## Summary\s*\n(.*?)(?=\n##|$)/s);
+  return match ? match[1].trim() : "Review completed";
+}
+
+function extractIssueCount(review: string): { critical: number; medium: number; low: number } {
+  const critical = (review.match(/### Critical\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
+  const medium = (review.match(/### Medium\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
+  const low = (review.match(/### Low\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
+
+  return { critical, medium, low };
+}
+```
+
+## Sub-Agent Delegation Pattern
+
+When running Claudish from an agent, use the Task tool to create a sub-agent:
+
+### Pattern 1: Simple Task Delegation
+
+```typescript
+/**
+ * Example: Delegate implementation to Grok via Claudish
+ */
+async function implementFeatureWithGrok(featureDescription: string) {
+  // Use Task tool to create sub-agent
+  const result = await Task({
+    subagent_type: "general-purpose",
+    description: "Implement feature with Grok",
+    prompt: `
+Use Claudish CLI to implement this feature with Grok model:
+
+${featureDescription}
+
+INSTRUCTIONS:
+1. Search for available models:
+   claudish --models grok
+
+2. Run implementation with Grok:
+   claudish --model x-ai/grok-code-fast-1 "${featureDescription}"
+
+3. Return ONLY:
+   - List of files created/modified
+   - Brief summary (2-3 sentences)
+   - Any errors encountered
+
+DO NOT return the full conversation transcript or implementation details.
+Keep your response under 500 tokens.
+    `
+  });
+
+  return result;
+}
+```
+
+### Pattern 2: File-Based Task Delegation
+
+```typescript
+/**
+ * Example: Use file-based instruction pattern in sub-agent
+ */
+async function analyzeCodeWithGemini(codebasePath: string) {
+  const timestamp = Date.now();
+  const instructionFile = `/tmp/claudish-analyze-${timestamp}.md`;
+  const resultFile = `/tmp/claudish-analyze-result-${timestamp}.md`;
+
+  // Create instruction file
+  const instruction = `# Codebase Analysis Task
+
+## Codebase Path
+${codebasePath}
+
+## Analysis Required
+- Architecture overview
+- Key patterns used
+- Potential improvements
+- Security considerations
+
+## Output
+Write analysis to: ${resultFile}
+
+Keep analysis concise (under 1000 words).
+`;
+
+  await Write({ file_path: instructionFile, content: instruction });
+
+  // Delegate to sub-agent
+  const result = await Task({
+    subagent_type: "general-purpose",
+    description: "Analyze codebase with Gemini",
+    prompt: `
+Use Claudish to analyze codebase with Gemini model.
+
+Instruction file: ${instructionFile}
+Result file: ${resultFile}
+
+STEPS:
+1. Read instruction file: ${instructionFile}
+2. Run: claudish --model google/gemini-2.5-flash --stdin < ${instructionFile}
+3. Wait for completion
+4. Read result file: ${resultFile}
+5. Return ONLY a 2-3 sentence summary
+
+DO NOT include the full analysis in your response.
+The full analysis is in ${resultFile} if needed.
+    `
+  });
+
+  // Read full result if needed
+  const fullAnalysis = await Read({ file_path: resultFile });
+
+  // Clean up
+  await Bash(`rm ${instructionFile} ${resultFile}`);
+
+  return {
+    summary: result,
+    fullAnalysis
+  };
+}
+```
+
+### Pattern 3: Multi-Model Comparison
+
+```typescript
+/**
+ * Example: Run same task with multiple models and compare
+ */
+async function compareModels(task: string, models: string[]) {
+  const results = [];
+
+  for (const model of models) {
+    const timestamp = Date.now();
+    const resultFile = `/tmp/claudish-${model.replace('/', '-')}-${timestamp}.md`;
+
+    // Run task with each model
+    await Task({
+      subagent_type: "general-purpose",
+      description: `Run task with ${model}`,
+      prompt: `
+Use Claudish to run this task with ${model}:
+
+${task}
+
+STEPS:
+1. Run: claudish --model ${model} --json "${task}"
+2. Parse JSON output
+3. Return ONLY:
+   - Cost (from total_cost_usd)
+   - Duration (from duration_ms)
+   - Token usage (from usage.input_tokens and usage.output_tokens)
+   - Brief quality assessment (1-2 sentences)
+
+DO NOT return full output.
+      `
+    });
+
+    results.push({
+      model,
+      resultFile
+    });
+  }
+
+  return results;
+}
+```
+
+## Common Workflows
+
+### Workflow 1: Quick Code Generation with Grok
+
+```bash
+# Fast, agentic coding with visible reasoning
+claudish --model x-ai/grok-code-fast-1 "add error handling to api routes"
+```
+
+### Workflow 2: Complex Refactoring with GPT-5
+
+```bash
+# Advanced reasoning for complex tasks
+claudish --model openai/gpt-5 "refactor authentication system to use OAuth2"
+```
+
+### Workflow 3: UI Implementation with Qwen (Vision)
+
+```bash
+# Vision-language model for UI tasks
+claudish --model qwen/qwen3-vl-235b-a22b-instruct "implement dashboard from figma design"
+```
+
+### Workflow 4: Code Review with Gemini
+
+```bash
+# State-of-the-art reasoning for thorough review
+git diff | claudish --stdin --model google/gemini-2.5-flash "Review these changes for bugs and improvements"
+```
+
+### Workflow 5: Multi-Model Consensus
+
+```bash
+# Run same task with multiple models
+for model in "x-ai/grok-code-fast-1" "google/gemini-2.5-flash" "openai/gpt-5"; do
+  echo "=== Testing with $model ==="
+  claudish --model "$model" "find security vulnerabilities in auth.ts"
+done
+```
+
+## Claudish CLI Flags Reference
+
+### Essential Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--model <model>` | OpenRouter model to use | `--model x-ai/grok-code-fast-1` |
+| `--stdin` | Read prompt from stdin | `git diff \| claudish --stdin --model grok` |
+| `--models` | List all models or search | `claudish --models` or `claudish --models gemini` |
+| `--top-models` | Show top recommended models | `claudish --top-models` |
+| `--json` | JSON output (implies --quiet) | `claudish --json "task"` |
+| `--help-ai` | Print AI agent usage guide | `claudish --help-ai` |
+
+### Advanced Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--interactive` / `-i` | Interactive mode | Auto (no prompt = interactive) |
+| `--quiet` / `-q` | Suppress log messages | Quiet in single-shot |
+| `--verbose` / `-v` | Show log messages | Verbose in interactive |
+| `--debug` / `-d` | Enable debug logging to file | Disabled |
+| `--port <port>` | Proxy server port | Random (3000-9000) |
+| `--no-auto-approve` | Require permission prompts | Auto-approve enabled |
+| `--dangerous` | Disable sandbox | Disabled |
+| `--monitor` | Proxy to real Anthropic API (debug) | Disabled |
+| `--force-update` | Force refresh model cache | Auto (>2 days) |
+
+### Output Modes
+
+1. **Quiet Mode (default in single-shot)**
+   ```bash
+   claudish --model grok "task"
+   # Clean output, no [claudish] logs
+   ```
+
+2. **Verbose Mode**
+   ```bash
+   claudish --verbose "task"
+   # Shows all [claudish] logs for debugging
+   ```
+
+3. **JSON Mode**
+   ```bash
+   claudish --json "task"
+   # Structured output: {result, cost, usage, duration}
+   ```
+
+## Cost Tracking
+
+Claudish automatically tracks costs in the status line:
+
+```
+directory • model-id • $cost • ctx%
+```
+
+**Example:**
+```
+my-project • x-ai/grok-code-fast-1 • $0.12 • 67%
+```
+
+Shows:
+- 💰 **Cost**: $0.12 USD spent in current session
+- 📊 **Context**: 67% of context window remaining
+
+**JSON Output Cost:**
+```bash
+claudish --json "task" | jq '.total_cost_usd'
+# Output: 0.068
+```
+
+## Error Handling
+
+### Error 1: OPENROUTER_API_KEY Not Set
+
+**Error:**
+```
+Error: OPENROUTER_API_KEY environment variable is required
+```
+
+**Fix:**
+```bash
+export OPENROUTER_API_KEY='sk-or-v1-...'
+# Or add to ~/.zshrc or ~/.bashrc
+```
+
+### Error 2: Claudish Not Installed
+
+**Error:**
+```
+command not found: claudish
+```
+
+**Fix:**
+```bash
+npm install -g claudish
+# Or: bun install -g claudish
+```
+
+### Error 3: Model Not Found
+
+**Error:**
+```
+Model 'invalid/model' not found
+```
+
+**Fix:**
+```bash
+# List available models
+claudish --models
+
+# Use valid model ID
+claudish --model x-ai/grok-code-fast-1 "task"
+```
+
+### Error 4: OpenRouter API Error
+
+**Error:**
+```
+OpenRouter API error: 401 Unauthorized
+```
+
+**Fix:**
+1. Check API key is correct
+2. Verify API key at https://openrouter.ai/keys
+3. Check API key has credits (free tier or paid)
+
+### Error 5: Port Already in Use
+
+**Error:**
+```
+Error: Port 3000 already in use
+```
+
+**Fix:**
+```bash
+# Let Claudish pick random port (default)
+claudish --model grok "task"
+
+# Or specify different port
+claudish --port 8080 --model grok "task"
+```
+
+## Best Practices
+
+### 1. ✅ Use File-Based Instructions
+
+**Why:** Avoids context window pollution
+
+**How:**
+```bash
+# Write instruction to file
+echo "Implement feature X" > /tmp/task.md
+
+# Run with stdin
+claudish --stdin --model grok < /tmp/task.md > /tmp/result.md
+
+# Read result
+cat /tmp/result.md
+```
+
+### 2. ✅ Choose Right Model for Task
+
+**Fast Coding:** `x-ai/grok-code-fast-1`
+**Complex Reasoning:** `google/gemini-2.5-flash` or `openai/gpt-5`
+**Vision/UI:** `qwen/qwen3-vl-235b-a22b-instruct`
+
+### 3. ✅ Use --json for Automation
+
+**Why:** Structured output, easier parsing
+
+**How:**
+```bash
+RESULT=$(claudish --json "task" | jq -r '.result')
+COST=$(claudish --json "task" | jq -r '.total_cost_usd')
+```
+
+### 4. ✅ Delegate to Sub-Agents
+
+**Why:** Keeps main conversation context clean
+
+**How:**
+```typescript
+await Task({
+  subagent_type: "general-purpose",
+  description: "Task with Claudish",
+  prompt: "Use claudish --model grok '...' and return summary only"
+});
+```
+
+### 5. ✅ Update Models Regularly
+
+**Why:** Get latest model recommendations
+
+**How:**
+```bash
+# Auto-updates every 2 days
+claudish --models
+
+# Search for specific models
+claudish --models deepseek
+
+# Force update now
+claudish --models --force-update
+```
+
+### 6. ✅ Use --stdin for Large Prompts
+
+**Why:** Avoid command line length limits
+
+**How:**
+```bash
+git diff | claudish --stdin --model grok "Review changes"
+```
+
+## Anti-Patterns (Avoid These)
+
+### ❌❌❌ NEVER Run Claudish Directly in Main Conversation (CRITICAL)
+
+**This is the #1 mistake. Never do this unless user explicitly requests it.**
+
+**WRONG - Destroys context window:**
+```typescript
+// ❌ NEVER DO THIS - Pollutes main context with 10K+ tokens
+await Bash("claudish --model grok 'implement feature'");
+
+// ❌ NEVER DO THIS - Full conversation in main context
+await Bash("claudish --model gemini 'review code'");
+
+// ❌ NEVER DO THIS - Even with --json, output is huge
+const result = await Bash("claudish --json --model gpt-5 'refactor'");
+```
+
+**RIGHT - Always use sub-agents:**
+```typescript
+// ✅ ALWAYS DO THIS - Delegate to sub-agent
+const result = await Task({
+  subagent_type: "general-purpose", // or specific agent
+  description: "Implement feature with Grok",
+  prompt: `
+Use Claudish to implement the feature with Grok model.
+
+CRITICAL INSTRUCTIONS:
+1. Create instruction file: /tmp/claudish-task-${Date.now()}.md
+2. Write detailed task requirements to file
+3. Run: claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-task-*.md
+4. Read result file and return ONLY a 2-3 sentence summary
+
+DO NOT return full implementation or conversation.
+Keep response under 300 tokens.
+  `
+});
+
+// ✅ Even better - Use specialized agent if available
+const result = await Task({
+  subagent_type: "backend-developer", // or frontend-dev, etc.
+  description: "Implement with external model",
+  prompt: `
+Use Claudish with x-ai/grok-code-fast-1 model to implement authentication.
+Follow file-based instruction pattern.
+Return summary only.
+  `
+});
+```
+
+**When you CAN run directly (rare exceptions):**
+```typescript
+// ✅ Only when user explicitly requests
+// User: "Run claudish directly in main context for debugging"
+if (userExplicitlyRequestedDirect) {
+  await Bash("claudish --model grok 'task'");
+}
+```
+
+### ❌ Don't Ignore Model Selection
+
+**Wrong:**
+```bash
+# Always using default model
+claudish "any task"
+```
+
+**Right:**
+```bash
+# Choose appropriate model
+claudish --model x-ai/grok-code-fast-1 "quick fix"
+claudish --model google/gemini-2.5-flash "complex analysis"
+```
+
+### ❌ Don't Parse Text Output
+
+**Wrong:**
+```bash
+OUTPUT=$(claudish --model grok "task")
+COST=$(echo "$OUTPUT" | grep cost | awk '{print $2}')
+```
+
+**Right:**
+```bash
+# Use JSON output
+COST=$(claudish --json --model grok "task" | jq -r '.total_cost_usd')
+```
+
+### ❌ Don't Hardcode Model Lists
+
+**Wrong:**
+```typescript
+const MODELS = ["x-ai/grok-code-fast-1", "openai/gpt-5"];
+```
+
+**Right:**
+```typescript
+// Query dynamically
+const { stdout } = await Bash("claudish --models --json");
+const models = JSON.parse(stdout).models.map(m => m.id);
+```
+
+### ✅ Do Accept Custom Models From Users
+
+**Problem:** User provides a custom model ID that's not in --top-models
+
+**Wrong (rejecting custom models):**
+```typescript
+const availableModels = ["x-ai/grok-code-fast-1", "openai/gpt-5"];
+const userModel = "custom/provider/model-123";
+
+if (!availableModels.includes(userModel)) {
+  throw new Error("Model not in my shortlist"); // ❌ DON'T DO THIS
+}
+```
+
+**Right (accept any valid model ID):**
+```typescript
+// Claudish accepts ANY valid OpenRouter model ID, even if not in --top-models
+const userModel = "custom/provider/model-123";
+
+// Validate it's a non-empty string with provider format
+if (!userModel.includes("/")) {
+  console.warn("Model should be in format: provider/model-name");
+}
+
+// Use it directly - Claudish will validate with OpenRouter
+await Bash(`claudish --model ${userModel} "task"`);
+```
+
+**Why:** Users may have access to:
+- Beta/experimental models
+- Private/custom fine-tuned models
+- Newly released models not yet in rankings
+- Regional/enterprise models
+- Cost-saving alternatives
+
+**Always accept user-provided model IDs** unless they're clearly invalid (empty, wrong format).
+
+### ✅ Do Handle User-Preferred Models
+
+**Scenario:** User says "use my custom model X" and expects it to be remembered
+
+**Solution 1: Environment Variable (Recommended)**
+```typescript
+// Set for the session
+process.env.CLAUDISH_MODEL = userPreferredModel;
+
+// Or set permanently in user's shell profile
+await Bash(`echo 'export CLAUDISH_MODEL="${userPreferredModel}"' >> ~/.zshrc`);
+```
+
+**Solution 2: Session Cache**
+```typescript
+// Store in a temporary session file
+const sessionFile = "/tmp/claudish-user-preferences.json";
+const prefs = {
+  preferredModel: userPreferredModel,
+  lastUsed: new Date().toISOString()
+};
+await Write({ file_path: sessionFile, content: JSON.stringify(prefs, null, 2) });
+
+// Load in subsequent commands
+const { stdout } = await Read({ file_path: sessionFile });
+const prefs = JSON.parse(stdout);
+const model = prefs.preferredModel || defaultModel;
+```
+
+**Solution 3: Prompt Once, Remember for Session**
+```typescript
+// In a multi-step workflow, ask once
+if (!process.env.CLAUDISH_MODEL) {
+  const { stdout } = await Bash("claudish --models --json");
+  const models = JSON.parse(stdout).models;
+
+  const response = await AskUserQuestion({
+    question: "Select model (or enter custom model ID):",
+    options: models.map((m, i) => ({ label: m.name, value: m.id })).concat([
+      { label: "Enter custom model...", value: "custom" }
+    ])
+  });
+
+  if (response === "custom") {
+    const customModel = await AskUserQuestion({
+      question: "Enter OpenRouter model ID (format: provider/model):"
+    });
+    process.env.CLAUDISH_MODEL = customModel;
+  } else {
+    process.env.CLAUDISH_MODEL = response;
+  }
+}
+
+// Use the selected model for all subsequent calls
+const model = process.env.CLAUDISH_MODEL;
+await Bash(`claudish --model ${model} "task 1"`);
+await Bash(`claudish --model ${model} "task 2"`);
+```
+
+**Guidance for Agents:**
+1. ✅ **Accept any model ID** user provides (unless obviously malformed)
+2. ✅ **Don't filter** based on your "shortlist" - let Claudish handle validation
+3. ✅ **Offer to set CLAUDISH_MODEL** environment variable for session persistence
+4. ✅ **Explain** that --top-models shows curated recommendations, --models shows all
+5. ✅ **Validate format** (should contain "/") but not restrict to known models
+6. ❌ **Never reject** a user's custom model with "not in my shortlist"
+
+### ❌ Don't Skip Error Handling
+
+**Wrong:**
+```typescript
+const result = await Bash("claudish --model grok 'task'");
+```
+
+**Right:**
+```typescript
+try {
+  const result = await Bash("claudish --model grok 'task'");
+} catch (error) {
+  console.error("Claudish failed:", error.message);
+  // Fallback to embedded Claude or handle error
+}
+```
+
+## Agent Integration Examples
+
+### Example 1: Code Review Agent
+
+```typescript
+/**
+ * Agent: code-reviewer (using Claudish with multiple models)
+ */
+async function reviewCodeWithMultipleModels(files: string[]) {
+  const models = [
+    "x-ai/grok-code-fast-1",      // Fast initial scan
+    "google/gemini-2.5-flash",    // Deep analysis
+    "openai/gpt-5"                // Final validation
+  ];
+
+  const reviews = [];
+
+  for (const model of models) {
+    const timestamp = Date.now();
+    const instructionFile = `/tmp/review-${model.replace('/', '-')}-${timestamp}.md`;
+    const resultFile = `/tmp/review-result-${model.replace('/', '-')}-${timestamp}.md`;
+
+    // Create instruction
+    const instruction = createReviewInstruction(files, resultFile);
+    await Write({ file_path: instructionFile, content: instruction });
+
+    // Run review with model
+    await Bash(`claudish --model ${model} --stdin < ${instructionFile}`);
+
+    // Read result
+    const result = await Read({ file_path: resultFile });
+
+    // Extract summary
+    reviews.push({
+      model,
+      summary: extractSummary(result),
+      issueCount: extractIssueCount(result)
+    });
+
+    // Clean up
+    await Bash(`rm ${instructionFile} ${resultFile}`);
+  }
+
+  return reviews;
+}
+```
+
+### Example 2: Feature Implementation Command
+
+```typescript
+/**
+ * Command: /implement-with-model
+ * Usage: /implement-with-model "feature description"
+ */
+async function implementWithModel(featureDescription: string) {
+  // Step 1: Get available models
+  const { stdout } = await Bash("claudish --models --json");
+  const models = JSON.parse(stdout).models;
+
+  // Step 2: Let user select model
+  const selectedModel = await promptUserForModel(models);
+
+  // Step 3: Create instruction file
+  const timestamp = Date.now();
+  const instructionFile = `/tmp/implement-${timestamp}.md`;
+  const resultFile = `/tmp/implement-result-${timestamp}.md`;
+
+  const instruction = `# Feature Implementation
+
+## Description
+${featureDescription}
+
+## Requirements
+- Write clean, maintainable code
+- Add comprehensive tests
+- Include error handling
+- Follow project conventions
+
+## Output
+Write implementation details to: ${resultFile}
+
+Include:
+- Files created/modified
+- Code snippets
+- Test coverage
+- Documentation updates
+`;
+
+  await Write({ file_path: instructionFile, content: instruction });
+
+  // Step 4: Run implementation
+  await Bash(`claudish --model ${selectedModel} --stdin < ${instructionFile}`);
+
+  // Step 5: Read and present results
+  const result = await Read({ file_path: resultFile });
+
+  // Step 6: Clean up
+  await Bash(`rm ${instructionFile} ${resultFile}`);
+
+  return result;
+}
+```
+
+## Troubleshooting
+
+### Issue: Slow Performance
+
+**Symptoms:** Claudish takes long time to respond
+
+**Solutions:**
+1. Use faster model: `x-ai/grok-code-fast-1` or `minimax/minimax-m2`
+2. Reduce prompt size (use --stdin with concise instructions)
+3. Check internet connection to OpenRouter
+
+### Issue: High Costs
+
+**Symptoms:** Unexpected API costs
+
+**Solutions:**
+1. Use budget-friendly models (check pricing with `--models` or `--top-models`)
+2. Enable cost tracking: `--cost-tracker`
+3. Use --json to monitor costs: `claudish --json "task" | jq '.total_cost_usd'`
+
+### Issue: Context Window Exceeded
+
+**Symptoms:** Error about token limits
+
+**Solutions:**
+1. Use model with larger context (Gemini: 1000K, Grok: 256K)
+2. Break task into smaller subtasks
+3. Use file-based pattern to avoid conversation history
+
+### Issue: Model Not Available
+
+**Symptoms:** "Model not found" error
+
+**Solutions:**
+1. Update model cache: `claudish --models --force-update`
+2. Check OpenRouter website for model availability
+3. Use alternative model from same category
+
+## Additional Resources
+
+**Documentation:**
+- Full README: `mcp/claudish/README.md` (in repository root)
+- AI Agent Guide: Print with `claudish --help-ai`
+- Model Integration: `skills/claudish-integration/SKILL.md` (in repository root)
+
+**External Links:**
+- Claudish GitHub: https://github.com/MadAppGang/claude-code
+- OpenRouter: https://openrouter.ai
+- OpenRouter Models: https://openrouter.ai/models
+- OpenRouter API Docs: https://openrouter.ai/docs
+
+**Version Information:**
+```bash
+claudish --version
+```
+
+**Get Help:**
+```bash
+claudish --help        # CLI usage
+claudish --help-ai     # AI agent usage guide
+```
+
+---
+
+**Maintained by:** MadAppGang
+**Last Updated:** November 25, 2025
+**Skill Version:** 1.1.0
diff --git a/skills/deep-analysis/SKILL.md b/skills/deep-analysis/SKILL.md
new file mode 100644
index 0000000..e6ff794
--- /dev/null
+++ b/skills/deep-analysis/SKILL.md
@@ -0,0 +1,277 @@
+---
+name: deep-analysis
+description: Proactively investigates codebases to understand complex patterns, trace multi-file flows, analyze architecture decisions, and provide comprehensive code insights. Use when users ask about code structure, implementation details, or need to understand how features work.
+allowed-tools: Task
+---
+
+# Deep Code Analysis
+
+This Skill provides comprehensive codebase investigation capabilities using the codebase-detective agent with semantic search and pattern matching.
+
+## When to use this Skill
+
+Claude should invoke this Skill when:
+
+- User asks "how does [feature] work?"
+- User wants to understand code architecture or patterns
+- User is debugging and needs to trace code flow
+- User asks "where is [functionality] implemented?"
+- User needs to find all usages of a component/service
+- User wants to understand dependencies between files
+- User mentions: "investigate", "analyze", "find", "trace", "understand"
+- User is exploring an unfamiliar codebase
+- User needs to understand complex multi-file functionality
+
+## Instructions
+
+### Phase 1: Determine Investigation Scope
+
+Understand what the user wants to investigate:
+
+1. **Specific Feature**: "How does user authentication work?"
+2. **Find Implementation**: "Where is the payment processing logic?"
+3. **Trace Flow**: "What happens when I click the submit button?"
+4. **Debug Issue**: "Why is the profile page showing undefined?"
+5. **Find Patterns**: "Where are all the API calls made?"
+6. **Analyze Architecture**: "What's the structure of the data layer?"
+
+### Phase 2: Invoke codebase-detective Agent
+
+Use the Task tool to launch the codebase-detective agent with comprehensive instructions:
+
+```
+Use Task tool with:
+- subagent_type: "code-analysis:detective"
+- description: "Investigate [brief summary]"
+- prompt: [Detailed investigation instructions]
+```
+
+**Prompt structure for codebase-detective**:
+
+```markdown
+# Code Investigation Task
+
+## Investigation Target
+[What needs to be investigated - be specific]
+
+## Context
+- Working Directory: [current working directory]
+- Purpose: [debugging/learning/refactoring/etc]
+- User's Question: [original user question]
+
+## Investigation Steps
+
+1. **Initial Search**:
+   - Use semantic search (claude-context MCP) if available
+   - Otherwise use grep/ripgrep/find for patterns
+   - Search for: [specific terms, patterns, file names]
+
+2. **Code Location**:
+   - Find exact file paths and line numbers
+   - Identify entry points and main implementations
+   - Note related files and dependencies
+
+3. **Code Flow Analysis**:
+   - Trace how data/control flows through the code
+   - Identify key functions and their roles
+   - Map out component/service relationships
+
+4. **Pattern Recognition**:
+   - Identify architectural patterns used
+   - Note code conventions and styles
+   - Find similar implementations for reference
+
+## Deliverables
+
+Provide a comprehensive report including:
+
+1. **📍 Primary Locations**:
+   - Main implementation files with line numbers
+   - Entry points and key functions
+   - Configuration and setup files
+
+2. **🔍 Code Flow**:
+   - Step-by-step flow explanation
+   - How components interact
+   - Data transformation points
+
+3. **🗺️ Architecture Map**:
+   - High-level structure diagram
+   - Component relationships
+   - Dependency graph
+
+4. **📝 Code Snippets**:
+   - Key implementations (show important code)
+   - Patterns and conventions used
+   - Notable details or gotchas
+
+5. **🚀 Navigation Guide**:
+   - How to explore the code further
+   - Related files to examine
+   - Commands to run for testing
+
+6. **💡 Insights**:
+   - Why the code is structured this way
+   - Potential issues or improvements
+   - Best practices observed
+
+## Search Strategy
+
+**With MCP Claude-Context Available**:
+- Index the codebase if not already indexed
+- Use semantic queries for concepts (e.g., "authentication logic")
+- Use natural language to find functionality
+
+**Fallback (No MCP)**:
+- Use ripgrep (rg) or grep for pattern matching
+- Search file names with find
+- Trace imports manually
+- Use git grep for repository-wide search
+
+## Output Format
+
+Structure your findings clearly with:
+- File paths using backticks: `src/auth/login.ts:45`
+- Code blocks for snippets
+- Clear headings and sections
+- Actionable next steps
+```
+
+### Phase 3: Present Analysis Results
+
+After the agent completes, present results to the user:
+
+1. **Executive Summary** (2-3 sentences):
+   - What was found
+   - Where it's located
+   - Key insight
+
+2. **Detailed Findings**:
+   - Primary file locations with line numbers
+   - Code flow explanation
+   - Architecture overview
+
+3. **Visual Structure** (if complex):
+   ```
+   EntryPoint (file:line)
+     ├── Validator (file:line)
+     ├── BusinessLogic (file:line)
+     │   └── DataAccess (file:line)
+     └── ResponseHandler (file:line)
+   ```
+
+4. **Code Examples**:
+   - Show key code snippets inline
+   - Highlight important patterns
+
+5. **Next Steps**:
+   - Suggest follow-up investigations
+   - Offer to dive deeper into specific parts
+   - Provide commands to test/run the code
+
+### Phase 4: Offer Follow-up
+
+Ask the user:
+- "Would you like me to investigate any specific part in more detail?"
+- "Do you want to see how [related feature] works?"
+- "Should I trace [specific function] further?"
+
+## Example Scenarios
+
+### Example 1: Understanding Authentication
+
+```
+User: "How does login work in this app?"
+
+Skill invokes codebase-detective agent with:
+"Investigate user authentication and login flow:
+1. Find login API endpoint or form handler
+2. Trace authentication logic
+3. Identify token generation/storage
+4. Find session management
+5. Locate authentication middleware"
+
+Agent provides:
+- src/api/auth/login.ts:34-78 (login endpoint)
+- src/services/authService.ts:12-45 (JWT generation)
+- src/middleware/authMiddleware.ts:23 (token validation)
+- Flow: Form → API → Service → Middleware → Protected Routes
+```
+
+### Example 2: Debugging Undefined Error
+
+```
+User: "The dashboard shows 'undefined' for user name"
+
+Skill invokes codebase-detective agent with:
+"Debug undefined user name in dashboard:
+1. Find Dashboard component
+2. Locate where user name is rendered
+3. Trace user data fetching
+4. Check data transformation/mapping
+5. Identify where undefined is introduced"
+
+Agent provides:
+- src/components/Dashboard.tsx:156 renders user.name
+- src/hooks/useUser.ts:45 fetches user data
+- Issue: API returns 'full_name' but code expects 'name'
+- Fix: Map 'full_name' to 'name' in useUser hook
+```
+
+### Example 3: Finding All API Calls
+
+```
+User: "Where are all the API calls made?"
+
+Skill invokes codebase-detective agent with:
+"Find all API call locations:
+1. Search for fetch, axios, http client usage
+2. Identify API client/service files
+3. List all endpoints used
+4. Note patterns (REST, GraphQL, etc)
+5. Find error handling approach"
+
+Agent provides:
+- 23 API calls across 8 files
+- Centralized in src/services/*
+- Using axios with interceptors
+- Base URL in src/config/api.ts
+- Error handling in src/utils/errorHandler.ts
+```
+
+## Success Criteria
+
+The Skill is successful when:
+
+1. ✅ User's question is comprehensively answered
+2. ✅ Exact code locations provided with line numbers
+3. ✅ Code relationships and flow clearly explained
+4. ✅ User can navigate to code and understand it
+5. ✅ Architecture patterns identified and explained
+6. ✅ Follow-up questions anticipated
+
+## Tips for Optimal Results
+
+1. **Be Comprehensive**: Don't just find one file, map the entire flow
+2. **Provide Context**: Explain why code is structured this way
+3. **Show Examples**: Include actual code snippets
+4. **Think Holistically**: Connect related pieces across files
+5. **Anticipate Questions**: Answer follow-up questions proactively
+
+## Integration with Other Tools
+
+This Skill works well with:
+
+- **MCP claude-context**: For semantic code search
+- **MCP gopls**: For Go-specific analysis
+- **Standard CLI tools**: grep, ripgrep, find, git
+- **Project-specific tools**: Use project's search/navigation tools
+
+## Notes
+
+- The codebase-detective agent uses extended thinking for complex analysis
+- Semantic search (MCP) is preferred but not required
+- Agent automatically falls back to grep/find if needed
+- Results are actionable and navigable
+- Great for onboarding to new codebases
+- Helps prevent incorrect assumptions about code
diff --git a/skills/semantic-code-search/SKILL.md b/skills/semantic-code-search/SKILL.md
new file mode 100644
index 0000000..fc784c7
--- /dev/null
+++ b/skills/semantic-code-search/SKILL.md
@@ -0,0 +1,878 @@
+---
+name: semantic-code-search
+description: Expert guidance on using the claude-context MCP for semantic code search. Provides best practices for indexing large codebases, formulating effective search queries, optimizing performance, and integrating vector-based code retrieval into investigation workflows. Use when working with large codebases, optimizing token usage, or when grep/ripgrep searches are insufficient.
+allowed-tools: Task
+---
+
+# Semantic Code Search Expert
+
+This Skill provides comprehensive guidance on leveraging the claude-context MCP server for efficient, semantic code search across large codebases using hybrid vector retrieval (BM25 + dense embeddings).
+
+## When to use this Skill
+
+Claude should invoke this Skill when:
+
+- Working with large codebases (10k+ lines of code)
+- Need semantic understanding beyond keyword matching
+- Want to optimize token consumption (reduce context usage by ~40%)
+- Traditional grep/ripgrep searches return too many false positives
+- Need to find functionality by concept rather than exact keywords
+- User asks: "index this codebase", "search semantically", "find where authentication is handled"
+- Before launching codebase-detective for large-scale investigations
+- User mentions: "claude-context", "vector search", "semantic search", "index code"
+- Token budget is constrained and need efficient code retrieval
+
+## Core Capabilities of Claude-Context MCP
+
+### Available Tools
+
+1. **mcp__claude-context__index_codebase** - Index a directory with configurable splitter
+2. **mcp__claude-context__search_code** - Natural language semantic search
+3. **mcp__claude-context__clear_index** - Remove search indexes
+4. **mcp__claude-context__get_indexing_status** - Check indexing progress
+
+### Key Benefits
+
+- **40% Token Reduction**: Retrieve only relevant code snippets vs loading entire directories
+- **Semantic Understanding**: Find code by what it does, not just what it's named
+- **Scale**: Handle millions of lines of code efficiently
+- **Hybrid Search**: Combines BM25 keyword matching with dense vector embeddings
+- **Multi-Round Avoidance**: Get relevant results in one query vs multiple grep attempts
+
+## Instructions
+
+### Phase 1: Decide If Claude-Context Is Appropriate
+
+**Use Claude-Context When:**
+
+✅ Codebase is large (10k+ lines)
+✅ Need to find functionality by concept ("authentication logic", "payment processing")
+✅ Working with unfamiliar codebase
+✅ Token budget is limited
+✅ Need to search across multiple languages/frameworks
+✅ grep returns hundreds of matches and you need the most relevant ones
+✅ Investigation requires understanding semantic relationships
+
+**DON'T Use Claude-Context When:**
+
+❌ Searching for exact string matches (use grep/ripgrep instead)
+❌ Codebase is small (<5k lines) - overhead not worth it
+❌ Looking for specific file names (use find/glob instead)
+❌ Searching within 2-3 known files (use Read tool instead)
+❌ Need regex pattern matching (use grep/ripgrep instead)
+❌ Time-sensitive quick lookup (indexing takes time)
+
+### Phase 2: Indexing Best Practices
+
+#### 2.1 Initial Indexing
+
+**Standard Indexing (Recommended):**
+
+```typescript
+mcp__claude-context__index_codebase with:
+{
+  path: "/absolute/path/to/project",
+  splitter: "ast",  // Syntax-aware with automatic fallback
+  force: false       // Don't re-index if already indexed
+}
+```
+
+**Why AST Splitter?**
+- Preserves code structure (functions, classes stay intact)
+- Automatically falls back to character-based for non-code files
+- Better semantic coherence in search results
+
+**When to Use LangChain Splitter:**
+
+```typescript
+mcp__claude-context__index_codebase with:
+{
+  path: "/absolute/path/to/project",
+  splitter: "langchain",  // Character-based splitting
+  force: false
+}
+```
+
+Use LangChain when:
+- Codebase has many configuration/data files (JSON, YAML, XML)
+- Documentation-heavy projects (Markdown, text files)
+- AST parsing fails frequently for your languages
+
+#### 2.2 Custom File Extensions
+
+**Include Additional Extensions:**
+
+```typescript
+mcp__claude-context__index_codebase with:
+{
+  path: "/absolute/path/to/project",
+  splitter: "ast",
+  customExtensions: [".vue", ".svelte", ".astro", ".prisma", ".proto"]
+}
+```
+
+**Common Custom Extensions by Framework:**
+
+- Vue.js: `[".vue"]`
+- Svelte: `[".svelte"]`
+- Astro: `[".astro"]`
+- Prisma: `[".prisma"]`
+- GraphQL: `[".graphql", ".gql"]`
+- Protocol Buffers: `[".proto"]`
+- Terraform: `[".tf", ".tfvars"]`
+
+#### 2.3 Ignore Patterns
+
+**Default Ignored (Automatic):**
+- `node_modules/`, `dist/`, `build/`, `.git/`
+- `vendor/`, `target/`, `__pycache__/`
+
+**Add Custom Ignore Patterns:**
+
+```typescript
+mcp__claude-context__index_codebase with:
+{
+  path: "/absolute/path/to/project",
+  splitter: "ast",
+  ignorePatterns: [
+    "generated/**",      // Generated code
+    "*.min.js",          // Minified files
+    "*.bundle.js",       // Bundled files
+    "test-data/**",      // Large test fixtures
+    "docs/api/**",       // Auto-generated docs
+    ".storybook/**",     // Storybook config
+    "*.lock",            // Lock files
+    "static/vendor/**"   // Third-party static files
+  ]
+}
+```
+
+**When to Use ignorePatterns:**
+- Generated code clutters search results
+- Large static assets slow indexing
+- Third-party code isn't relevant to your investigation
+- Test fixtures create noise
+
+⚠️ **IMPORTANT**: Only use `ignorePatterns` when user explicitly requests custom filtering. Don't add it by default.
+
+#### 2.4 Force Re-Indexing
+
+**When to Force Re-Index:**
+
+```typescript
+mcp__claude-context__index_codebase with:
+{
+  path: "/absolute/path/to/project",
+  splitter: "ast",
+  force: true  // ⚠️ Overwrites existing index
+}
+```
+
+Use `force: true` when:
+- Codebase has changed significantly
+- Previous indexing was interrupted
+- Switching between splitters (ast ↔ langchain)
+- Search results seem outdated
+- Adding/removing custom extensions or ignore patterns
+
+**Conflict Handling:**
+If indexing is attempted on an already indexed path, ALWAYS:
+1. Inform the user that the path is already indexed
+2. Ask if they want to force re-index
+3. Explain the trade-off (time vs freshness)
+4. Only proceed with `force: true` if user confirms
+
+#### 2.5 Monitor Indexing Progress
+
+**Check Status:**
+
+```typescript
+mcp__claude-context__get_indexing_status with:
+{
+  path: "/absolute/path/to/project"
+}
+```
+
+**Status Indicators:**
+- `Indexing... (45%)` - Still processing
+- `Indexed: 1,234 chunks from 567 files` - Complete
+- `Not indexed` - Never indexed or cleared
+
+**Best Practice:**
+For large codebases (100k+ lines), check status every 30 seconds to provide user updates.
+
+### Phase 3: Search Query Formulation
+
+#### 3.1 Effective Query Patterns
+
+**Concept-Based Queries (Best for Claude-Context):**
+
+```typescript
+// ✅ GOOD - Semantic concepts
+search_code with query: "user authentication login flow with JWT tokens"
+search_code with query: "database connection pooling initialization"
+search_code with query: "error handling middleware for HTTP requests"
+search_code with query: "WebSocket connection establishment and message handling"
+search_code with query: "payment processing with Stripe integration"
+```
+
+**Why These Work:**
+- Natural language describes WHAT the code does
+- Multiple related concepts improve relevance ranking
+- Captures intent, not just syntax
+
+**Keyword Queries (Better for grep):**
+
+```typescript
+// ⚠️ OKAY - Works but not optimal
+search_code with query: "authenticateUser function"
+search_code with query: "UserRepository class"
+```
+
+**Why Less Optimal:**
+- Assumes you know exact naming
+- Misses semantically similar code with different names
+- Better handled by grep if you know the exact term
+
+**Avoid These:**
+
+```typescript
+// ❌ BAD - Too generic
+search_code with query: "user"
+search_code with query: "function"
+
+// ❌ BAD - Too specific/technical
+search_code with query: "express.Router().post('/api/users')"
+search_code with query: "class UserService extends BaseService implements IUserService"
+
+// ❌ BAD - Regex patterns (use grep instead)
+search_code with query: "func.*Handler|HandlerFunc"
+```
+
+#### 3.2 Query Templates by Use Case
+
+**Finding Authentication/Authorization:**
+```typescript
+"user login authentication with password validation and session creation"
+"JWT token generation and validation middleware"
+"OAuth2 authentication flow with Google provider"
+"role-based access control permission checking"
+"API key authentication verification"
+```
+
+**Finding Database Operations:**
+```typescript
+"user data persistence save to database"
+"SQL query execution with prepared statements"
+"MongoDB collection find and update operations"
+"database transaction commit and rollback handling"
+"ORM model definition for user entity"
+```
+
+**Finding API Endpoints:**
+```typescript
+"HTTP POST endpoint for creating new users"
+"GraphQL resolver for user queries and mutations"
+"REST API handler for updating user profile"
+"WebSocket event handler for chat messages"
+```
+
+**Finding Business Logic:**
+```typescript
+"shopping cart calculation with tax and discounts"
+"email notification sending after user registration"
+"file upload processing with virus scanning"
+"report generation with PDF export"
+```
+
+**Finding Configuration:**
+```typescript
+"environment variable configuration loading"
+"database connection string setup"
+"API rate limiting configuration"
+"CORS policy definition for cross-origin requests"
+```
+
+**Finding Error Handling:**
+```typescript
+"global error handler for uncaught exceptions"
+"validation error formatting for API responses"
+"retry logic for failed HTTP requests"
+"logging critical errors to monitoring service"
+```
+
+#### 3.3 Extension Filtering
+
+**Filter by File Type:**
+
+```typescript
+// Only search TypeScript files
+search_code with:
+{
+  path: "/absolute/path/to/project",
+  query: "user authentication",
+  extensionFilter: [".ts", ".tsx"]
+}
+
+// Only search Go files
+search_code with:
+{
+  path: "/absolute/path/to/project",
+  query: "HTTP handler implementation",
+  extensionFilter: [".go"]
+}
+
+// Search configs only
+search_code with:
+{
+  path: "/absolute/path/to/project",
+  query: "database connection settings",
+  extensionFilter: [".json", ".yaml", ".env"]
+}
+```
+
+**When to Use Extension Filters:**
+- Multi-language projects (frontend + backend)
+- Avoid irrelevant results from wrong language
+- Focus on specific layer (e.g., only database layer .go files)
+- Search configuration vs code separately
+
+#### 3.4 Result Limiting
+
+**Default Limit:**
+```typescript
+search_code with:
+{
+  path: "/absolute/path/to/project",
+  query: "authentication logic",
+  limit: 10  // Default: 10 results
+}
+```
+
+**Adjust Based on Use Case:**
+
+```typescript
+// Quick overview - fewest results
+limit: 5
+
+// Standard investigation - balanced
+limit: 10  // Recommended default
+
+// Comprehensive search - more results
+limit: 20
+
+// Exhaustive - find everything
+limit: 50  // Maximum allowed
+```
+
+**Guideline:**
+- Start with 10 results
+- If too many false positives → refine query
+- If missing relevant code → increase limit
+- Never go below 5 (might miss important code)
+
+### Phase 4: Performance Optimization Strategies
+
+#### 4.1 Token Optimization
+
+**Technique 1: Targeted Searches vs Full Directory Reads**
+
+```typescript
+// ❌ WASTEFUL - Loads entire directory into context
+Read with path: "/project/src/**/*.ts"
+
+// ✅ EFFICIENT - Returns only relevant snippets
+search_code with:
+{
+  query: "user authentication flow",
+  extensionFilter: [".ts"],
+  limit: 10
+}
+```
+
+**Token Savings:**
+- Full directory: ~50,000 tokens
+- Semantic search: ~5,000 tokens (10 snippets × ~500 tokens each)
+- **Savings: 90%**
+
+**Technique 2: Iterative Refinement**
+
+```typescript
+// First search - broad
+search_code with query: "user authentication"
+// Returns 10 results, review them
+
+// Second search - refined based on findings
+search_code with query: "JWT token generation in authentication service"
+// Returns more specific results
+```
+
+**Why This Works:**
+- First search gives context
+- Second search uses insights from first search
+- Total tokens < loading entire codebase
+
+**Technique 3: Combine with Targeted Reads**
+
+```typescript
+// 1. Semantic search to find relevant files
+search_code with query: "payment processing logic"
+// Returns: src/services/paymentService.ts:45-89
+
+// 2. Read specific file for full context
+Read with path: "/project/src/services/paymentService.ts"
+```
+
+**Workflow:**
+1. Search semantically → get file locations
+2. Read specific files → get full context
+3. Only load what you need
+
+#### 4.2 Indexing Performance
+
+**Optimize Indexing Time:**
+
+1. **Index Once, Search Many**
+   - Don't re-index unless code changed significantly
+   - Check status before re-indexing
+
+2. **Use Appropriate Splitter**
+   - AST splitter: Slower indexing, better search results
+   - LangChain splitter: Faster indexing, more general results
+
+3. **Strategic Ignore Patterns**
+   - Exclude generated code, vendor files
+   - Reduces indexing time by 30-50%
+
+4. **Incremental Approach**
+   - For massive projects, index subdirectories separately
+   - Example: Index `src/`, `lib/`, `api/` separately
+
+**Indexing Time Expectations:**
+
+| Codebase Size | Splitter | Expected Time |
+|--------------|----------|---------------|
+| 10k lines    | AST      | 30-60 sec     |
+| 50k lines    | AST      | 2-5 min       |
+| 100k lines   | AST      | 5-10 min      |
+| 500k lines   | AST      | 20-30 min     |
+| 10k lines    | LangChain| 15-30 sec     |
+| 100k lines   | LangChain| 2-4 min       |
+
+### Phase 5: Integration with Code Investigation Workflows
+
+#### 5.1 With Codebase-Detective Agent
+
+**Recommended Workflow:**
+
+```markdown
+# When user asks: "How does authentication work?"
+
+## Step 1: Index (if not already indexed)
+mcp__claude-context__index_codebase
+
+## Step 2: Semantic Search
+search_code with query: "user authentication login flow"
+search_code with query: "password validation and hashing"
+search_code with query: "session token generation and storage"
+
+## Step 3: Launch Codebase-Detective
+Task tool with subagent_type: "code-analysis:detective"
+Provide detective with:
+- Search results (file locations)
+- User's question
+- Specific files to investigate
+
+## Step 4: Deep Dive
+Detective uses semantic search results as starting points
+Reads specific files
+Traces code flow
+Provides comprehensive analysis
+```
+
+**Why This Workflow?**
+- Semantic search narrows scope (saves tokens)
+- Detective focuses on relevant files (saves time)
+- Combined approach: breadth (search) + depth (detective)
+
+#### 5.2 Semantic Search → Grep → Read Pattern
+
+**For Complex Investigations:**
+
+```typescript
+// 1. Semantic search for general area
+search_code with query: "HTTP request middleware authentication"
+// Results: 10 files in middleware/
+
+// 2. Grep for specific patterns in those files
+Grep with pattern: "req\.user|req\.auth" in middleware/
+
+// 3. Read exact implementations
+Read specific files identified above
+```
+
+**When to Use This Pattern:**
+- Need both semantic understanding AND exact syntax
+- Want to verify search results with grep
+- Investigating specific implementation details
+
+### Phase 6: Troubleshooting and Common Pitfalls
+
+#### 6.1 Indexing Issues
+
+**Problem: "Indexing stuck at 0%"**
+
+Solutions:
+1. Check Node.js version (must be 20.x, NOT 24.x)
+2. Verify OPENAI_API_KEY is set
+3. Verify MILVUS_TOKEN is set
+4. Check path is absolute, not relative
+5. Ensure directory exists and is readable
+
+**Problem: "Indexing failed halfway through"**
+
+Solutions:
+1. Clear index: `clear_index`
+2. Re-index with `force: true`
+3. Check for corrupted files in codebase
+4. Try LangChain splitter instead of AST
+
+**Problem: "Already indexed but want to update"**
+
+Solution:
+1. Ask user if they want to force re-index
+2. Explain trade-off: time vs freshness
+3. Use `force: true` if confirmed
+
+#### 6.2 Search Quality Issues
+
+**Problem: "Search returns irrelevant results"**
+
+Solutions:
+1. Make query more specific:
+   - ❌ "user" → ✅ "user login authentication with password"
+2. Add extension filter to narrow scope
+3. Reduce limit to see top results only
+4. Try different query phrasing (synonyms, related concepts)
+
+**Problem: "Search misses relevant code"**
+
+Solutions:
+1. Broaden query:
+   - ❌ "JWT token validation middleware" → ✅ "authentication verification"
+2. Increase limit (try 20 or 30)
+3. Try multiple searches with different keywords
+4. Check if file is actually indexed (might be in ignore patterns)
+
+**Problem: "Too many results, all seem relevant"**
+
+Solutions:
+1. Use extension filters to focus on specific files
+2. Combine with follow-up searches:
+   - First: Broad search
+   - Second: Specific search based on first results
+3. Use limit: 5 to see only top matches
+
+#### 6.3 Performance Issues
+
+**Problem: "Indexing takes too long"**
+
+Solutions:
+1. Add ignore patterns for generated/vendor code
+2. Use LangChain splitter (faster but less accurate)
+3. Index subdirectories separately
+4. Check for very large files (>10MB) and exclude them
+
+**Problem: "Search is slow"**
+
+Solutions:
+1. Reduce limit (fewer results = faster)
+2. Use extension filters (smaller search space)
+3. Check indexing status (still indexing = slow search)
+
+**Problem: "Using too many tokens"**
+
+Solutions:
+1. Reduce search limit
+2. Use extension filters
+3. Make queries more specific (fewer but better results)
+4. Combine search with targeted reads (not full directory reads)
+
+### Phase 7: Real-World Workflow Examples
+
+#### Example 1: Investigating New Codebase
+
+```markdown
+User: "I'm new to this project, help me understand the architecture"
+
+## Workflow:
+
+1. Index the codebase
+mcp__claude-context__index_codebase with path: "/project"
+
+2. Search for entry points
+search_code with query: "application startup initialization main function"
+
+3. Search for architecture patterns
+search_code with query: "dependency injection container service registration"
+search_code with query: "routing configuration API endpoint definitions"
+search_code with query: "database connection setup and migrations"
+
+4. Search for domain models
+search_code with query: "core business entities data models"
+
+5. Launch codebase-detective with findings
+Task tool with all search results as context
+
+6. Provide architecture overview to user
+```
+
+#### Example 2: Finding and Fixing a Bug
+
+```markdown
+User: "Users can't reset their passwords, investigate"
+
+## Workflow:
+
+1. Ensure codebase is indexed
+get_indexing_status with path: "/project"
+
+2. Search for password reset functionality
+search_code with query: "password reset request token generation email"
+search_code with query: "password reset verification token validation"
+search_code with query: "update user password after reset"
+
+3. Find related error handling
+search_code with query: "password reset error handling validation"
+
+4. Narrow down to specific files
+extensionFilter: [".ts", ".tsx"] to focus on TypeScript
+
+5. Read specific implementations
+Read files identified in search
+
+6. Identify bug and propose fix
+
+7. Search for tests
+search_code with query: "password reset test cases" to find where to add tests
+```
+
+#### Example 3: Adding New Feature to Existing System
+
+```markdown
+User: "Add two-factor authentication to login"
+
+## Workflow:
+
+1. Index codebase (if needed)
+
+2. Find existing authentication
+search_code with query: "user login authentication password verification"
+
+3. Find similar security features
+search_code with query: "token generation validation security verification"
+
+4. Find where to integrate
+search_code with query: "login flow user session creation after authentication"
+
+5. Find database models
+search_code with query: "user model schema database table"
+
+6. Find configuration patterns
+search_code with query: "feature flags configuration settings"
+
+7. Launch codebase-detective with context
+Provide all search results to guide implementation
+
+8. Implement 2FA based on existing patterns
+```
+
+#### Example 4: Security Audit
+
+```markdown
+User: "Audit the codebase for security issues"
+
+## Workflow:
+
+1. Index entire codebase
+
+2. Search for authentication weaknesses
+search_code with query: "password storage hashing bcrypt authentication"
+search_code with query: "SQL query construction user input database"
+
+3. Search for authorization issues
+search_code with query: "access control permission checking authorization"
+search_code with query: "API endpoint authentication middleware protection"
+
+4. Search for input validation
+search_code with query: "user input validation sanitization XSS prevention"
+search_code with query: "file upload handling validation security"
+
+5. Search for sensitive data handling
+search_code with query: "environment variables secrets API keys configuration"
+search_code with query: "logging sensitive data personal information"
+
+6. Launch codebase-detective for deep analysis
+Investigate each suspicious finding
+
+7. Generate security report
+```
+
+#### Example 5: Migration Planning
+
+```markdown
+User: "Plan migration from Express to Fastify"
+
+## Workflow:
+
+1. Index codebase
+
+2. Find all Express usage
+search_code with query: "Express router middleware application setup"
+search_code with extensionFilter: [".ts", ".js"], limit: 50
+
+3. Find route definitions
+search_code with query: "HTTP route handlers GET POST PUT DELETE endpoints"
+
+4. Find middleware usage
+search_code with query: "middleware authentication error handling CORS"
+
+5. Find specific Express features
+search_code with query: "express static file serving"
+search_code with query: "express session management"
+search_code with query: "express body parser request parsing"
+
+6. Document all findings
+Create migration checklist with file locations
+
+7. Estimate effort
+Count occurrences, identify complex migrations
+```
+
+### Phase 8: Best Practices Summary
+
+#### Indexing Best Practices
+
+✅ **DO:**
+- Use AST splitter for better semantic coherence
+- Index once, search many times
+- Check status before re-indexing
+- Use absolute paths
+- Add custom extensions for framework-specific files
+- Use ignore patterns to exclude generated/vendor code
+
+❌ **DON'T:**
+- Re-index unnecessarily (wastes time)
+- Use relative paths (causes errors)
+- Index without checking Node.js version (v20.x required)
+- Include minified/bundled files (creates noise)
+- Force re-index without user confirmation
+
+#### Search Best Practices
+
+✅ **DO:**
+- Use natural language concept queries
+- Start with limit: 10, adjust as needed
+- Use extension filters for multi-language projects
+- Refine queries based on results
+- Combine semantic search with targeted file reads
+
+❌ **DON'T:**
+- Use overly generic queries ("user", "function")
+- Use regex patterns (use grep instead)
+- Assume exact naming (defeats semantic search purpose)
+- Set limit too low (<5) or too high (>30 usually)
+- Load entire directories when search would suffice
+
+#### Performance Best Practices
+
+✅ **DO:**
+- Use semantic search to reduce token usage
+- Combine search → read specific files
+- Monitor indexing progress for large codebases
+- Use extension filters to narrow search space
+- Clear old indexes when project structure changes significantly
+
+❌ **DON'T:**
+- Read entire directories when searching would work
+- Index multiple times for the same investigation
+- Use limit: 50 when 10 would suffice
+- Search without specifying path (searches everything)
+
+#### Workflow Best Practices
+
+✅ **DO:**
+- Index at start of investigation
+- Use semantic search before launching agents
+- Provide search results to codebase-detective
+- Combine semantic search with grep for precision
+- Iterate on queries based on results
+
+❌ **DON'T:**
+- Skip indexing for large codebases
+- Launch detective without search context
+- Rely solely on semantic search (combine tools)
+- Give up after first search (iterate and refine)
+
+## Integration with This Plugin
+
+This Skill works seamlessly with:
+
+1. **Codebase-Detective Agent** (`plugins/code-analysis/agents/codebase-detective.md`)
+   - Use semantic search to find starting points
+   - Provide search results as context to detective
+   - Detective does deep dive investigation
+
+2. **Deep Analysis Skill** (`plugins/code-analysis/skills/deep-analysis/SKILL.md`)
+   - Deep analysis invokes detective
+   - Detective uses semantic search (from this skill)
+   - Full workflow: deep-analysis → detective → semantic-search → investigation
+
+3. **Analyze Command** (`plugins/code-analysis/commands/analyze.md`)
+   - Command triggers deep analysis skill
+   - Skill guides semantic search usage
+   - Complete workflow automation
+
+## Success Criteria
+
+This Skill is successful when:
+
+1. ✅ Codebase is indexed efficiently with appropriate settings
+2. ✅ Search queries are formulated semantically for best results
+3. ✅ Token usage is optimized (40% reduction achieved)
+4. ✅ Search results are relevant and actionable
+5. ✅ User understands when to use semantic search vs grep
+6. ✅ Integration with other tools (detective, grep, read) is seamless
+7. ✅ Performance is optimized (indexing time, search speed, token usage)
+
+## Quality Checklist
+
+Before completing a semantic search workflow, ensure:
+
+- ✅ Checked if path is already indexed (avoid unnecessary re-indexing)
+- ✅ Used appropriate splitter (AST for code, LangChain for docs)
+- ✅ Formulated queries using natural language concepts
+- ✅ Set reasonable result limits (10-20 typically)
+- ✅ Used extension filters when appropriate
+- ✅ Provided search results as context to agents
+- ✅ Explained to user why semantic search was beneficial
+- ✅ Documented file locations for follow-up investigation
+
+## Notes
+
+- Claude-Context MCP requires Node.js v20.x (NOT v24.x)
+- Requires OPENAI_API_KEY for embeddings
+- Requires MILVUS_TOKEN for Zilliz Cloud vector database
+- Achieves ~40% token reduction vs full directory reads
+- Uses hybrid search: BM25 (keyword) + dense embeddings (semantic)
+- AST splitter preserves code structure better than character-based
+- Always use absolute paths, never relative paths
+- Semantic search complements grep/ripgrep, doesn't replace it
+- Best for "what does this do?" queries, not "show me line 45"
+- Integration with codebase-detective creates powerful investigation workflow
+
+---
+
+**Maintained by:** Jack Rudenko @ MadAppGang
+**Plugin:** code-analysis v1.0.0
+**Last Updated:** November 5, 2024