> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Mount a GitHub repository as a read-only Mirage filesystem for agents to list, read, search, and inspect code.

The GitHub VFS uses GitHub's [REST API](https://docs.github.com/en/rest)
to mount a repository as a read-only virtual filesystem. It does not imitate
another CLI.

For token setup, see [GitHub Setup](/home/setup/github).

## Config

```python theme={null}
import os

from mirage import MountMode, Workspace
from mirage.vfs.github import GitHubConfig, GitHubVFS

config = GitHubConfig(token=os.environ["GITHUB_TOKEN"])
vfs = GitHubVFS(
    config=config, owner="my-org", repo="my-repo", ref="main")
ws = Workspace({"/github": vfs}, mode=MountMode.READ)
```

## Filesystem Layout

```text theme={null}
/github/
  README.md
  pyproject.toml
  src/
    __init__.py
    main.py
    utils.py
    models/
      user.py
      item.py
  tests/
    test_main.py
```

The filesystem mirrors the repository tree. No owner/repo/branch in
the path - those are specified at mount time.

## Tree Fetching

The full recursive tree is fetched on the first read, not at mount time, so
constructing the VFS never blocks on the network. For repos with

> 100K entries, it falls back to per-directory fetching.

## Cache

The GitHub VFS uses `IndexCacheStore` with SHA-based fingerprinting. Content is content-addressed - if the SHA matches, the content is identical.

## Example

```python theme={null}
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.github import GitHubConfig, GitHubVFS

load_dotenv(".env.development")


async def main():
    config = GitHubConfig(token=os.environ["GITHUB_TOKEN"])
    vfs = GitHubVFS(
        config=config, owner="my-org", repo="my-repo", ref="main")
    ws = Workspace({"/github": vfs}, mode=MountMode.READ)

    # List repository root
    r = await ws.execute("ls /github/")
    print(await r.stdout_str())

    # Read a file
    r = await ws.execute("cat /github/README.md")
    print(await r.stdout_str())

    # Search for a pattern
    r = await ws.execute('rg "def main" /github/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /github/")
    print(await r.stdout_str())

    # File metadata with SHA
    r = await ws.execute("stat /github/README.md")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())
```

See `examples/code/github.py` for the full working example.

## Finding SHAs

Git blob SHAs are available via the `stat` command:

```bash theme={null}
stat /github/README.md
# -> extra={"sha": "a1b2c3d4e5f6..."}

stat /github/src/main.py
# -> extra={"sha": "f6e5d4c3b2a1..."}
```

## Working with Large Repos

Tips for efficient access on large repositories:

```bash theme={null}
# Find files by name
find /github/ -name "*.py"

# Search with rg (uses GitHub code search API when applicable)
rg "TODO" /github/

# Read only the first lines of a file
head -n 20 /github/src/main.py

# Check file sizes
du /github/src/

# List deeply nested directories
tree -L 3 /github/src/
```

## Shell Commands

Standard commands available on the mounted GitHub tree:

| Command         | Notes                                      |
| --------------- | ------------------------------------------ |
| `ls`            | List files and directories                 |
| `cat`           | Read file contents                         |
| `head` / `tail` | First/last N lines                         |
| `grep` / `rg`   | Pattern search; rg uses code search API    |
| `jq`            | Query JSON files                           |
| `wc`            | Line/word/byte counts                      |
| `stat`          | File metadata including git SHA            |
| `find`          | Recursive search with `-name`, `-maxdepth` |
| `tree`          | Directory tree view                        |
| `diff`          | Compare files                              |
| `du`            | Disk usage / file sizes                    |
| `awk`           | Text processing                            |
| `sed`           | Stream editing                             |
| `sort`          | Sort lines                                 |
| `uniq`          | Deduplicate lines                          |
| `cut`           | Extract columns                            |
| `tr`            | Translate characters                       |
| `nl`            | Number lines                               |
| `md5`           | MD5 checksum                               |
| `sha256sum`     | SHA-256 checksum                           |
| `file`          | Detect file type                           |
| `basename`      | Strip directory from path                  |
| `dirname`       | Strip filename from path                   |
| `realpath`      | Resolve path                               |

## Search Optimization

`rg` uses the GitHub code search API when the search scope exceeds
100 files and the mounted ref is the repository's default branch.
This avoids downloading file contents and returns results significantly
faster for large repositories.