How to Add Custom Language Support via languages.toml in Code-Review-Graph

Place a languages.toml file in the .code-review-graph directory at your repository root to register new Tree-sitter grammars without modifying the core library.

The code-review-graph parser supports extensible language definitions through a declarative configuration file. By creating a languages.toml manifest in your project's .code-review-graph folder, you can teach the analyzer to recognize additional file extensions and node types using any Tree-sitter grammar. This approach keeps custom definitions project-local and avoids maintaining a fork of the tirth8205/code-review-graph repository.

Configuration File Location and Discovery

The loader searches for a file named languages.toml inside a .code-review-graph directory at the repository root. As implemented in [code_review_graph/custom_languages.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L47-L49), the path resolution follows standard project-root detection patterns. Place your configuration at the exact relative path .code-review-graph/languages.toml to ensure discovery.

TOML Schema and Validation Rules

Each custom language definition requires a [languages.<name>] table containing specific AST node mappings. According to the validation logic in [code_review_graph/custom_languages.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L53-L68), the schema requires these fields:

• extensions: Array of file extensions (each must match ^\.[a-z0-9_+-]{1,15}$)
• grammar: Name of the Tree-sitter grammar package
• function_node_types: Array of AST node types representing function definitions
• class_node_types: Array of AST node types representing class definitions
• import_node_types: Array of AST node types representing import statements
• call_node_types: Array of AST node types representing function calls

The validator enforces strict constraints according to the code-review-graph source code:

• Language names must match ^[a-z][a-z0-9_-]{0,31}$ and be unique across the project
• Maximum of 20 custom languages per configuration file
• No collision with built-in language names or extensions
• Duplicate extensions are ignored (first definition wins)

Loading and Caching Mechanism

When CodeParser initializes, it invokes load_custom_languages() to parse and validate the configuration. According to the implementation in [code_review_graph/parser.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py#L2101-L2104), the parser merges these definitions during instantiation. This process occurs automatically when you create a new parser instance with your repository root.

The caching layer stores parsed results keyed by file path, modification time, and size. As defined in [code_review_graph/custom_languages.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L92-L98), this cache prevents redundant disk I/O during batch operations. If the languages.toml file changes, the cache invalidates automatically on the next parser initialization.

Runtime Integration

Once loaded, custom languages receive identical treatment to built-in definitions throughout the analysis pipeline. The integration logic in [code_review_graph/custom_languages.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L13081-L13085) ensures that custom definitions populate the internal language map. This enables standard analyses like function extraction, import detection, and call graph construction using your supplied node types.

Practical Implementation Examples

Define your custom languages using static TOML syntax. The following examples demonstrate configurations for Erlang and a hypothetical experimental language.

Create a minimal configuration for Erlang support:

# .code-review-graph/languages.toml

[languages.erlang]
extensions = [".erl", ".hrl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]
comment = "Erlang via the bundled tree-sitter-erlang grammar"

Define a second custom language following the same pattern:

[languages.mylang]
extensions = [".myl"]
grammar = "mylang_grammar"
function_node_types = ["fn"]
class_node_types = ["class"]
import_node_types = ["import"]
call_node_types = ["call"]
comment = "My experimental language"

Initialize the parser in Python to load these definitions automatically:

from pathlib import Path
from code_review_graph.parser import CodeParser

repo_root = Path.cwd()
parser = CodeParser(repo_root)  # Loads custom languages internally

Verify loading by running the CLI with verbose output:

code-review-graph -v build .

Look for diagnostic messages confirming the custom language count and any validation warnings.

Summary

• Place languages.toml in .code-review-graph/ at your repository root to enable discovery
• Define languages using [languages.<name>] tables with required AST node mappings for functions, classes, imports, and calls
• Respect validation constraints: lowercase names matching ^[a-z][a-z0-9_-]{0,31}$, valid extensions, and maximum 20 entries
• The parser caches configurations based on file metadata to optimize performance across multiple runs
• Custom languages integrate seamlessly into the analysis pipeline without modifications to the core library

Frequently Asked Questions

What is the maximum number of custom languages I can define?

You can define up to 20 custom languages in a single languages.toml file. This limit prevents excessive memory usage during parser initialization. If you exceed this limit, the loader ignores additional entries and logs a warning to stderr.

Can I override built-in language definitions?

No, custom language definitions cannot collide with built-in language names or file extensions. The validator in [code_review_graph/custom_languages.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) explicitly checks against the core language map and rejects any configuration attempting to redefine existing entries.

How do I debug why my custom language isn't loading?

Run the build command with the verbose flag (-v) to see diagnostic messages during parser initialization. The loader outputs the number of custom languages detected and specific validation errors if your TOML violates the schema or naming conventions. Verify that your file resides at exactly .code-review-graph/languages.toml relative to the repository root.

Does the configuration support environment variables or interpolation?

No, the languages.toml file uses static TOML only and does not support environment variable interpolation. All values must be literal strings and arrays as documented in [docs/CUSTOM_LANGUAGES.md](https://github.com/tirth8205/code-review-graph/blob/main/docs/CUSTOM_LANGUAGES.md). Dynamic resolution of grammar paths or environment-specific configuration is not supported by the current loader implementation.

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