codemap_get_related

Get related files (shared imports, shared importers, similar names).

graphrelatedconnections

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	File path or symbol reference
`maxResults`	`number`	❌ Optional	Maximum results to return (default: 20)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_get_related",
  "arguments": {
    "target": "src/utils/helpers.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "file": "src/utils/helpers.ts",
  "imports": [
    "src/types/common.ts",
    "src/config/constants.ts"
  ],
  "importers": [
    "src/features/dashboard.ts",
    "src/api/routes.ts",
    "src/components/Header.vue"
  ],
  "totalRelated": 5
}

ℹ️When to Use This Tool

codemap_get_related

Module exploration - Discover files connected to a module you're working on
Dependency mapping - Build a relationship graph for visualization
Refactoring scope - Identify related files that might need updates
Code discovery - Find components or utilities that work with a specific file
Network analysis - Build file connection networks for metrics
Similarity detection - Find files with shared dependencies (suggest common patterns)
Large codebases - Control result size with maxResults when dealing with heavily connected files

💡Common Patterns

Progressive Exploration

// Start with a small set, expand if needed
let related = await codemap.graph.getRelated({ 
  target: 'src/core/engine.ts',
  maxResults: 5 
});

if (related.totalRelated > 5) {
  console.log('More connections exist, fetching all...');
  related = await codemap.graph.getRelated({ 
    target: 'src/core/engine.ts',
    maxResults: 100 
  });
}

Build Module Map

// Create a relationship map for a directory
const files = await codemap.search({ query: 'src/features/*.ts' });

const moduleMap = new Map();
for (const file of files.files) {
  const related = await codemap.graph.getRelated({ target: file.relativePath });
  moduleMap.set(file.relativePath, {
    imports: related.imports,
    importers: related.importers
  });
}

console.log('Module relationships mapped:', moduleMap.size);

Find Shared Dependencies

// Find files that share common imports
const fileA = 'src/features/auth.ts';
const fileB = 'src/features/users.ts';

const relatedA = await codemap.graph.getRelated({ target: fileA });
const relatedB = await codemap.graph.getRelated({ target: fileB });

const sharedImports = relatedA.imports.filter(imp => 
  relatedB.imports.includes(imp)
);

console.log(Shared dependencies: ${sharedImports.length});
sharedImports.forEach(dep => console.log(  - ${dep}));

Connectivity Heatmap

// Measure connectivity across modules
const modules = await codemap.search({ query: 'src/modules/**/*.ts' });

const connectivity = modules.files.map(file => ({
  file: file.relativePath,
  connections: 0
}));

for (const item of connectivity) {
  const related = await codemap.graph.getRelated({ target: item.file });
  item.connections = related.totalRelated;
}

connectivity.sort((a, b) => b.connections - a.connections);
console.log('Connectivity heatmap:', connectivity);

💡Pro Tips

Use maxResults for performance - In large codebases, limit results to avoid overwhelming output. Start small (5-10), expand as needed.

Compare with get-dependencies - get_related and get_dependencies return similar data, but get_related allows result limiting. Use get_related for exploratory work, get_dependencies for complete analysis.

Build dependency graphs - Use this tool to construct visual dependency graphs by collecting all relationships.

Find common patterns - Files with shared imports often indicate common patterns or feature groupings worth documenting.

Track architectural layers - Files in the same architectural layer often share similar import patterns. Use this to verify layer boundaries.

Combine with search - Use codemap_search to find files, then get_related to explore their connections.

✅Best Practices

Start with small maxResults - Begin with 10-20 results, then increase if you need more detail.

Cache results for graphs - When building dependency graphs, cache get_related results to avoid redundant calls.

Use for discovery, not deletion - Unlike get_dependencies, this tool is optimized for exploration, not safety checks (use get_dependencies for deletion safety).

Document heavily-connected files - Files with >50 total connections deserve architecture documentation.

Track over time - Monitor how totalRelated changes as the codebase evolves to detect coupling growth.

Combine with annotations - Add annotations to files based on their connection count (e.g., 'architectural-hub' for highly connected files).

⚠️Common Mistakes

❌ Mistake: Using get_related when you need complete data

// Wrong tool - need all dependencies for safety check
const related = await codemap.graph.getRelated({ 
  target: 'src/utils/helpers.ts',
  maxResults: 10 
});

if (related.importers.length === 0) {
  // Dangerous - might be missing importers due to maxResults
  await codemap.delete({ target: 'src/utils/helpers.ts' });
}

✅ Instead: Use get_dependencies for complete data

const deps = await codemap.graph.getDependencies('src/utils/helpers.ts');
if (deps.importedByCount === 0) {
  await codemap.delete({ target: 'src/utils/helpers.ts' });
}

---

❌ Mistake: Not accounting for maxResults truncation

const related = await codemap.graph.getRelated({ 
  target: 'src/core/engine.ts',
  maxResults: 5 
});

console.log(Engine has ${related.totalRelated} connections);
// totalRelated shows actual count, but arrays are truncated
console.log(Imports: ${related.imports.length}); // Might be less than totalRelated

✅ Instead: Understand the difference

const related = await codemap.graph.getRelated({ 
  target: 'src/core/engine.ts',
  maxResults: 5 
});

console.log(Total connections: ${related.totalRelated});
console.log(Showing ${related.imports.length + related.importers.length} of ${related.totalRelated});

---

❌ Mistake: Building graphs without deduplication

// Creates duplicate nodes
const graph = { nodes: [], edges: [] };
for (const file of files) {
  const related = await codemap.graph.getRelated({ target: file });
  graph.nodes.push(file, ...related.imports, ...related.importers);
}
// graph.nodes has many duplicates

✅ Instead: Deduplicate nodes

const graph = { nodes: new Set(), edges: [] };
for (const file of files) {
  graph.nodes.add(file);
  const related = await codemap.graph.getRelated({ target: file });
  related.imports.forEach(imp => graph.nodes.add(imp));
  related.importers.forEach(imp => graph.nodes.add(imp));
}
graph.nodes = Array.from(graph.nodes);

---

❌ Mistake: Confusing imports and importers

const related = await codemap.graph.getRelated({ target: 'src/api/client.ts' });

// Wrong - imports are what THIS file imports
console.log('Files that use client.ts:', related.imports);

// Wrong - importers are files that import THIS file
console.log('Dependencies of client.ts:', related.importers);

✅ Instead: Remember the direction

const related = await codemap.graph.getRelated({ target: 'src/api/client.ts' });

console.log('client.ts imports:', related.imports); // Dependencies
console.log('client.ts is imported by:', related.importers); // Dependents