# How Llama-GitHub Retrieves Repository Structure (First 3 Levels)

> Discover how Llama GitHub retrieves repository structure up to 3 levels using the GitHub Trees API. Learn about optimizing RAG context windows.

- Repository: [Jet Xu/llama-github](https://github.com/jetxu-llm/llama-github)
- Tags: internals
- Published: 2026-03-04

---

**Llama-GitHub fetches the complete repository tree via the GitHub Trees API, converts the flat response into a nested dictionary hierarchy, and recursively truncates the result to the first three directory levels to optimize RAG context windows.**

The `jetxu-llm/llama-github` library streamlines codebase analysis for Retrieval-Augmented Generation (RAG) by providing intelligent **repository structure retrieval** that balances comprehensive file hierarchy awareness with LLM token efficiency. The system implements a three-stage pipeline that transforms raw GitHub API responses into a condensed, JSON-serializable tree structure ideal for downstream AI processing.

## Step 1: Fetching the Full Tree from GitHub

The retrieval process begins in [`llama_github/github_integration/github_auth_manager.py`](https://github.com/jetxu-llm/llama-github/blob/main/llama_github/github_integration/github_auth_manager.py), where the `ExtendedGithub.get_repo_structure` method queries the GitHub Trees API endpoint:

```python
/git/trees/{branch}?recursive=1

```

This returns a flat list where each entry contains a `path` (the full file or directory path), a `type` field indicating `blob` for files or `tree` for directories, and optional metadata such as `size`. According to the source code in lines 66–112, the method handles authentication and pagination to ensure the entire repository structure is captured in a single API response.

## Step 2: Converting the Flat List to a Hierarchical Tree

Once the flat list is retrieved, the internal helper `list_to_tree` processes each item to build a nested dictionary structure. As implemented in [`github_auth_manager.py`](https://github.com/jetxu-llm/llama-github/blob/main/github_auth_manager.py) (lines 66–112), the function:

- Splits every `path` string on the `/` delimiter to determine nesting depth
- Creates directory nodes containing a `children` dictionary for further traversal
- Stores file nodes as leaves containing their full `path` and `size` 
- Strips the `type` field to produce a clean structure requiring no additional type checks during traversal

This transformation converts the GitHub API's linear response into a traversable tree that mirrors the actual filesystem hierarchy.

## Step 3: Reducing to the First Three Levels

The truncation logic resides in [`llama_github/rag_processing/rag_processor.py`](https://github.com/jetxu-llm/llama-github/blob/main/llama_github/rag_processing/rag_processor.py) (lines 60–78). The `RAGProcessor.get_repo_simple_structure` method first obtains the full tree via `repo.get_structure()`, then executes a recursive `simplify_tree` function that:

1. Tracks the current depth during recursion
2. Returns the full node if the depth is less than 3
3. Replaces deeper branches with the placeholder `'...'` when the depth reaches 3
4. Returns a pretty-printed JSON string containing only top-level directories, their immediate subdirectories, and files directly under those first two tiers

This aggressive pruning ensures that RAG processors receive sufficient architectural context without consuming excessive tokens on deep dependency trees or `node_modules` directories.

## Caching Strategy for Performance

The `Repository` class in [`llama_github/data_retrieval/github_entities.py`](https://github.com/jetxu-llm/llama-github/blob/main/llama_github/data_retrieval/github_entities.py) implements a singleton caching pattern through the `get_structure` method (lines 32–48). On first invocation, the method stores the complete hierarchical tree in a private `_structure` attribute. Subsequent calls return the cached version immediately, eliminating redundant API requests and tree-building computations when the same repository is analyzed multiple times during a session.

## Practical Implementation Examples

### Direct API Access

To retrieve the complete repository structure without level limitations:

```python
from llama_github.github_integration.github_auth_manager import ExtendedGithub

gh = ExtendedGithub(login_or_token="YOUR_TOKEN")
full_tree = gh.get_repo_structure("octocat/Hello-World", branch="main")
print(full_tree)  # Nested dict with complete layout

```

### Retrieving the Three-Level Summary

For RAG applications requiring the condensed view:

```python
from llama_github.rag_processing.rag_processor import RAGProcessor
from llama_github.data_retrieval.github_api import GitHubAPIHandler
from llama_github.github_integration.github_auth_manager import RepositoryPool

api_handler = GitHubAPIHandler(token="YOUR_TOKEN")
rag = RAGProcessor(github_api_handler=api_handler)

pool = RepositoryPool(github_instance=api_handler.github_instance)
repo = pool.get_repository("octocat/Hello-World")

simple_structure_json = rag.get_repo_simple_structure(repo)
print(simple_structure_json)

```

### Inspecting Both Structures

To compare the full tree against the simplified version:

```python
full_tree = repo.get_structure()
print("Full tree node count:", len(full_tree))

simple_tree = rag.get_repo_simple_structure(repo)
import json, textwrap
print(textwrap.indent(json.dumps(json.loads(simple_tree), indent=2), "  "))

```

## Summary

- **GitHub Trees API**: `ExtendedGithub.get_repo_structure` fetches the complete flat file list from `/git/trees/{branch}?recursive=1` as implemented in [`github_auth_manager.py`](https://github.com/jetxu-llm/llama-github/blob/main/github_auth_manager.py) lines 66–112.
- **Hierarchy Construction**: The `list_to_tree` helper converts flat paths into nested dictionaries with `children` nodes for directories and leaf nodes for files.
- **Depth Limitation**: `RAGProcessor.get_repo_simple_structure` applies a recursive `simplify_tree` function that halts at level three, substituting deeper content with `'...'` (lines 60–78 in [`rag_processor.py`](https://github.com/jetxu-llm/llama-github/blob/main/rag_processor.py)).
- **Singleton Caching**: The `Repository` class caches the full structure in `_structure` after the first `get_structure()` call, ensuring efficient reuse across multiple RAG operations.

## Frequently Asked Questions

### Why does Llama-GitHub limit repository structure retrieval to three levels?

The three-level restriction optimizes token consumption for Large Language Model prompts while preserving enough hierarchical context for RAG systems to understand codebase architecture. This prevents deep dependency directories like `node_modules` or build artifacts from overwhelming the context window, ensuring the LLM focuses on high-level project organization rather than granular file listings.

### Which GitHub API endpoint powers the repository structure retrieval?

The library utilizes the GitHub Trees API endpoint `/git/trees/{branch}?recursive=1` via the `ExtendedGithub.get_repo_structure` method in [`github_auth_manager.py`](https://github.com/jetxu-llm/llama-github/blob/main/github_auth_manager.py). The `recursive=1` parameter ensures the API returns every file and directory in the repository in a single request, regardless of nesting depth.

### How does the library minimize API calls when analyzing the same repository repeatedly?

The `Repository` class in [`github_entities.py`](https://github.com/jetxu-llm/llama-github/blob/main/github_entities.py) implements singleton-style caching through a private `_structure` attribute. When `get_structure()` is called for the first time, it fetches and stores the complete tree; subsequent invocations return the cached dictionary immediately without additional network requests or tree-building computations.

### Can developers modify the depth limit for repository structure retrieval?

The current implementation hardcodes the three-level limit within the `simplify_tree` function inside `RAGProcessor.get_repo_simple_structure` (lines 60–78 of [`rag_processor.py`](https://github.com/jetxu-llm/llama-github/blob/main/rag_processor.py)). Developers requiring deeper traversal must modify the recursion depth check in the source code, as no configuration parameter currently exposes this threshold through the public API.