GitHubnpm
Tools · v0.10.0

Smart Context

The smart_context tool automatically gathers relevant code context for AI agents. It analyzes your task, question, or refactoring goal and collects the most relevant files, symbols, and code patterns.

✨ New in v0.10.0

Smart Context now supports 3 modes with auto-detection of task type (explain/refactor/debug/add-feature) for optimal context gathering.

Modes

Task Mode

Analyzes impact, finds test files, discovers similar code patterns for a given task.

task: "add rate limiting to the API"

Question Mode

Searches relevant code, gathers context imports, dependents, and symbols for understanding.

question: "how does the auth flow work?"

Refactor Mode

Full impact analysis depth 3 + all affected files + test files + similar patterns.

task: "refactor the user service"

Usage

Task Mode

Provide a task description and let vibe-hnindex gather the relevant context:

smart_context(
  project_name: "my-app",
  task: "add rate limiting to the API"
)

The server will:

  1. Analyze the task for impact scope
  2. Find relevant test files near affected code
  3. Discover similar code patterns for consistency
  4. Auto-detect task type: explain, refactor, debug, or add-feature

Question Mode

Ask a natural language question about your codebase:

smart_context(
  project_name: "my-app",
  question: "how does the auth flow work?"
)

The server will:

  1. Search code related to your question
  2. Gather context imports and dependents
  3. Collect relevant symbols and their definitions
  4. Provide a comprehensive answer context

Refactor Mode

For full impact analysis when refactoring:

smart_context(
  project_name: "my-app",
  task: "refactor the user service"
)

The server will:

  1. Perform impact analysis up to depth 3
  2. Find all files affected by the change
  3. Collect test files for verification
  4. Discover similar patterns for consistent refactoring

Auto-Detection

The server automatically detects the type of task and adjusts its context gathering strategy:

Detected TypeContext Strategy
ExplainGather definitions, callers, and documentation
RefactorDeep impact analysis, test files, similar patterns
DebugError handling, log statements, test coverage
Add FeatureSimilar implementations, interfaces, patterns

Response Format

Smart Context returns a structured response with sections based on the detected task type:

SectionContentModes
Task AnalysisDetected task type, keywords, relevant directoriesAll
Core ContextFile content + imports + definitions for the main filesAll
DependentsFiles that import/use the target codeTask, Refactor
Test FilesRelated .test.ts, .spec.ts, __tests__/Task, Refactor, Debug
Similar PatternsFiles with same extension and similar code structureTask, Add Feature
Impact AnalysisUp to 3 levels deep — files affected by the changeRefactor
Symbol MapExports, types, interfaces in the affected scopeAll
Git HistoryRecent changes to relevant files (if git repo)All

How AI Agents Should Use Smart Context

  1. Before starting a task: Call smart_context with a brief description of what you plan to do. It gathers all relevant files upfront.
  2. Read the task analysis to understand the task type and affected areas.
  3. Check impact analysis (refactor mode) before touching shared utilities to avoid breaking dependents.
  4. Review test files to understand expected behavior and run tests after changes.
  5. Use similar patterns to stay consistent with existing code style.
  • project_briefing — Rule-based project briefing (README, package.json, index stats)
  • onboarding_prompt — Single markdown blob with index freshness, briefing, stats
  • agent_rules_stub — Short copy-paste markdown for AI agent context
  • file_summary — Get imports, exports, dependents, and test files for a specific file
  • symbol_lookup — Look up a symbol (function, class, type) and get all references
  • recent_changes — See what files changed recently in a project