# How to Configure Custom Language Support in code-review-graph Using languages.toml

> Easily add custom language support to code-review-graph using languages.toml. Map file extensions to tree-sitter grammars and aliases to enhance your code review analysis.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-07-26

---

**You can extend code-review-graph with new programming languages by placing a [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file inside the `.code-review-graph/` directory at your repository root, defining `[languages.<name>]` tables that map file extensions to custom tree-sitter grammars and optional aliases.**

The `code-review-graph` analyzer supports user-defined language extensions without requiring modifications to the core library. By creating a structured TOML configuration, you instruct the engine to recognize additional file types and parse them using specified grammar definitions. This guide demonstrates the exact schema, file placement, and validation steps based on the implementation in [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) and the test suite in [`tests/test_custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_custom_languages.py).

## Configuration File Location

The engine searches for **[`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml)** relative to the repository root. If present, the `load_custom_languages()` function in [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) reads and validates this file during the initialization phase.

```bash
mkdir -p .code-review-graph
touch .code-review-graph/languages.toml

```

## The languages.toml Schema

Each custom language is defined under a **`[languages.<name>]`** table, where `<name>` is the unique identifier for the language.

### Required Fields

- **`grammar`**: A string path (relative to repository root) pointing to the compiled tree-sitter grammar file (Wasm) or parser module.
- **`extensions`**: A list of file extension strings without the leading dot (e.g., `["foo", "fool"]`).

### Optional Fields

- **`aliases`**: A list of alternative language names used when resolving import statements or language identifiers.
- **`probe_fields`**: A list of attribute names that the engine checks during heuristic symbol detection (e.g., `["service", "endpoint"]`).

A complete example registering a fictional **FooLang** looks like this:

```toml
[languages.foolang]
grammar = "grammars/foolang/tree-sitter-foolang.wasm"
extensions = ["foo", "fool"]
aliases = ["fl"]
probe_fields = ["module", "handler"]

```

## Loading Custom Languages Programmatically

While the CLI automatically detects the configuration file when running `code-review-graph analyze`, you can also load definitions manually using the Python API. The **`load_custom_languages()`** function accepts a `Path` object pointing to the repository root and returns a dictionary mapping language names to configuration objects.

```python
from pathlib import Path
from code_review_graph.custom_languages import load_custom_languages

repo_root = Path(".")
custom_langs = load_custom_languages(repo_root)

for name, config in custom_langs.items():
    print(f"{name}: grammar={config.grammar}, extensions={config.extensions}")

```

## Validating Your Configuration

The test suite in [`tests/test_custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_custom_languages.py) demonstrates how the engine validates TOML syntax and required fields. Missing keys or malformed paths raise descriptive errors preventing analysis with an inconsistent setup. You can verify your configuration by running the project's test suite or by invoking the loader directly in a Python shell as shown above.

## Summary

- Place **[`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml)** inside the **`.code-review-graph/`** directory at your repository root.
- Define each language under **`[languages.<name>]`** with required **`grammar`** and **`extensions`** fields.
- Add optional **`aliases`** and **`probe_fields`** to improve symbol resolution heuristics.
- The **`load_custom_languages()`** function in [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) handles parsing and validation.
- Reference **[`tests/test_custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_custom_languages.py)** for examples of valid and invalid configurations.

## Frequently Asked Questions

### Where exactly should I put the languages.toml file?

Create the file at **[`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml)** relative to your repository root. The `load_custom_languages()` function specifically looks for this path when initializing the analyzer.

### What format should the grammar field use?

The **`grammar`** field must contain a relative path string pointing to a compiled tree-sitter grammar (typically a `.wasm` file) or a custom parser module that the engine can load. Path separators should match your operating system or use forward slashes for cross-platform compatibility.

### Can I define multiple custom languages in a single file?

Yes. The TOML format supports multiple **`[languages.<name>]`** tables within the same file. Each table defines a distinct language with its own grammar, extensions, and optional aliases.

### How does the tool handle configuration errors?

If [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) is missing required fields, contains invalid syntax, or references non-existent grammar files, the **`load_custom_languages()`** function raises a validation error immediately upon loading. This prevents the analysis pipeline from executing with incomplete language definitions.