GitHub

The GitHub VFS uses GitHub’s REST API to mount a repository as a read-only virtual filesystem. It does not imitate another CLI. For token setup, see GitHub Setup.

Config

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)

Field	Description
`timeout` default `30`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`token` required, secret	GitHub personal access token.
`owner`	Repository owner, a user or an organization. Required unless the `GitHubVFS` constructor is given `owner`.
`repo`	Repository name. Required unless the `GitHubVFS` constructor is given `repo`.
`ref`	Branch, tag or commit SHA the mount reads. Unset follows the repository’s default branch, resolved on the first read.
`base_url`	GitHub API root. Unset uses `https://api.github.com`; set it for GitHub Enterprise.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with GitHub mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`github`, read

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `github` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 5000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `github`, read |

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `github` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 5000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

/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. Under read: fresh, a cached listing is checked against the head commit the ref resolves to: one small check per command (a shallow git/trees/{ref}), after which every cached listing of the mount at that commit is served. A mount whose ref is a full 40- or 64-hex commit sha serves its cached listings with no request: github.com refuses a branch or tag named with 40 or 64 hex characters, so such a ref always names a commit (a GitHub Enterprise host is assumed to do the same). A repository whose recursive tree comes back truncated stores no version, so each folder is re-listed once per command.

Example

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.shell("ls /github/")
    print(await r.stdout_str())

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

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

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

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


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

See examples/python/vfs/github/github.py for the full working example.

Finding SHAs

Git blob SHAs are available via the stat command:

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:

# Find files by name
find /github/ -name "*.py"

# Search whole words with rg (uses GitHub code search on large repos)
rg -w "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; see grep and rg
`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

Integration

What GitHub answers through its own API, so fewer files are read. Integration explains each command.

Command	On GitHub
`grep -r`, `rg`	GitHub code search, for whole words, on the default branch, under a path with more than 100 files. It can miss recent pushes.
`find`, `du`, `ls -R`, `tree`	One recursive tree listing

grep -rw and rg -w read only the files GitHub code search names when:

the scope holds more than 100 files; a smaller one is read directly,
the mounted ref is the default branch, the only one code search indexes,
the repository tree was listed in full,
and the search returns every hit, 100 at most.

Every file is read otherwise. Files code search never indexes are always read. Each file is one request, so grep -r, git grep, find and the other walks stop after walk_limit files (default 5000) and keep what they printed, and a glob matching more, tar -c, cp -r, rm -r and the other whole-tree commands are refused above it:

$ grep -r TODO /github/
/github/src/main.py:# TODO: retry
grep: /github/: stopped after 5000 files (walk_limit); narrow the path

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Tree Fetching

Cache

Example

Finding SHAs

Working with Large Repos

Shell Commands

Integration

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Tree Fetching

​Cache

​Example

​Finding SHAs

​Working with Large Repos

​Shell Commands

​Integration

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Tree Fetching

Cache

Example

Finding SHAs

Working with Large Repos

Shell Commands

Integration