How to Boost Specific Paths in OpenClaude Repo Map: Complete Guide with Examples

Use the focus_files parameter to boost specific directories or files, or focus_symbols to boost files containing specific functions, classes, or types when calling RepoMapTool.run() or the openclaude repomap CLI command.

The OpenClaude repository (Gitlawb/openclaude) generates a RepoMap—a PageRank-based graph visualization of every source file in your repository. By default, the ranking reflects only import-dependency relationships, which can obscure the files most relevant to your specific inquiry. To solve this, OpenClaude provides a boosting mechanism that lets you weight specific paths and symbols, ensuring they appear higher in the rendered map.

Understanding the RepoMap Boost Mechanism

OpenClaude’s RepoMap constructs a directed graph where nodes represent files and edges represent import/export relationships. According to the source code in src/context/repoMap/pagerank.ts, the boosting algorithm operates post-hoc: it first runs the standard PageRank calculation, then applies additional weight to your selected nodes and their immediate neighbors. This approach preserves the overall graph structure while elevating the relevance of your specified paths.

The boost factor is a constant numeric weight added to the selected nodes and their direct dependency edges. This ensures that files you care about rank higher without destabilizing the underlying topological relationships.

Focus Parameters for Boosting Specific Paths

The RepoMapTool accepts two optional parameters that control which files receive a relevance boost:

Target Files and Directories with focus_files

The focus_files parameter accepts an array of relative paths (files or directories). When you provide paths like ["src/tools/","src/context/repoMap.ts"], the tool matches these against the graph nodes and applies the boost factor to those files and their immediate neighbors. This is ideal for directory-centric queries or when you want to highlight a specific module.

Target Symbols with focus_symbols

The focus_symbols parameter accepts an array of symbol names (functions, classes, or types). Before applying the boost, the tool resolves these symbols to their defining files using the symbol-to-file map built during parsing (in src/context/repoMap/parser.ts). For example, passing ["buildTool","ToolUseContext"] will locate the files containing these symbols and boost those nodes plus their neighbors.

Internal Implementation of Path Boosting

The boosting process follows a four-stage pipeline implemented across the RepoMap subsystem:

1. Graph Construction – The buildRepoMap function reads the entire source tree and parses each file using Tree-Sitter, creating a directed graph of import/export relationships.

2. Focus Resolution –

   • For focus_files, the tool matches supplied paths against graph nodes, including sub-paths for directory entries.
   • For focus_symbols, the tool queries the symbol map from src/context/repoMap/parser.ts to resolve names to file locations.

3. Boost Application – In src/context/repoMap/pagerank.ts, the algorithm iterates over the resolved nodes and adds the boost factor to both the nodes themselves and their directly connected neighbors.

4. Final Ranking – The weighted graph feeds into the PageRank solver, producing a reordered map that emphasizes your focused paths while maintaining dependency accuracy.

Command-Line Usage for Boosting Paths

The openclaude repomap command exposes boosting options as JSON-encoded array flags. Both parameters can be used individually or combined.

Boost a specific directory and its related files:

openclaude repomap --focus_files='["src/tools/"]' --output=repo-map.md

Boost specific symbols across the codebase:

openclaude repomap --focus_symbols='["buildTool","ToolUseContext"]' --output=repo-map.md

Combine both parameters to boost a directory and specific symbols simultaneously:

openclaude repomap \
  --focus_files='["src/context/repoMap/"]' \
  --focus_symbols='["RepoMapResult"]' \
  --output=boosted-map.md

Programmatic API for RepoMap Boosting

You can invoke the RepoMapTool directly from TypeScript to generate boosted maps programmatically. The RepoMapTool.run() method accepts the same focus parameters as the CLI.

import { RepoMapTool } from './src/tools/RepoMapTool/RepoMapTool.js';

async function generateBoostedMap() {
  const result = await RepoMapTool.run({
    focus_files: ['src/context/repoMap/'],
    focus_symbols: ['RepoMapResult'],
  });

  // Access the rendered markdown table
  console.log(result.renderedMarkdown);
  
  // Or access the raw graph data
  console.log(result.graph);
}

generateBoostedMap();

The result object contains both the raw graph structure and a renderedMarkdown property formatted for terminal display (as used in src/components/RepoMap.tsx).

Key Source Files

The boosting functionality spans several critical files in the OpenClaude codebase:

• src/tools/RepoMapTool/RepoMapTool.ts – Main implementation handling focus parameter processing and CLI integration
• src/tools/RepoMapTool/prompt.ts – Documentation of CLI options including focus_files and focus_symbols
• src/context/repoMap/pagerank.ts – PageRank solver with post-hoc boost logic
• src/context/repoMap/parser.ts – Tree-Sitter parser that builds the symbol-to-file resolution map
• src/context/repoMap/index.ts – Public API for RepoMap construction and caching
• src/commands/repomap/repomap.ts – CLI command wrapper that forwards arguments to the tool

Summary

• RepoMap uses PageRank to rank files by dependency relationships, but you can steer results using the focus_files and focus_symbols parameters.
• focus_files boosts specific directories or file paths by relative path strings.
• focus_symbols resolves function, class, or type names to their defining files before applying the boost.
• The boost applies post-hoc in src/context/repoMap/pagerank.ts by adding weight to selected nodes and their direct neighbors.
• Both CLI (openclaude repomap) and programmatic (RepoMapTool.run()) interfaces support JSON-encoded focus arrays.
• The symbol resolution relies on Tree-Sitter parsing in src/context/repoMap/parser.ts to map names to files accurately.

Frequently Asked Questions

What is the difference between focus_files and focus_symbols?

focus_files requires you to know the exact relative path of the file or directory you want to boost, making it ideal when you already know where relevant code lives. focus_symbols lets you boost files by the functions, classes, or types they contain, which is useful when you know the API name but not its file location. The latter requires symbol resolution via the parser's symbol-to-file map in src/context/repoMap/parser.ts.

How does the boost factor affect the PageRank calculation?

The boost applies after the initial PageRank calculation completes. According to the implementation in src/context/repoMap/pagerank.ts, the algorithm adds a constant numeric weight to the selected nodes and their direct dependency edges, then re-normalizes the graph. This ensures your focused paths rank higher without breaking the dependency-based ranking structure of unrelated files.

Can I use both focus parameters simultaneously?

Yes. When you supply both focus_files and focus_symbols, the RepoMapTool resolves both parameter sets and merges the resulting node lists before applying the boost. The CLI accepts both flags in the same command, and the programmatic API accepts both keys in the options object passed to RepoMapTool.run().

Where is the boost logic implemented in the source code?

The core boosting algorithm resides in src/context/repoMap/pagerank.ts, which modifies the graph weights after construction. The parameter handling and symbol resolution occur in src/tools/RepoMapTool/RepoMapTool.ts, which coordinates between the CLI interface in src/commands/repomap/repomap.ts and the graph construction logic in src/context/repoMap/index.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}