ghfs: GitHub issues as read-only local files, readable from inside Codex's sandbox

[ghfs-dev]

I build ghfs. It keeps a repository's GitHub issues on disk as Markdown files, mounted read-only at .ghfs/ in the repo, so a coding agent reads an issue with cat instead of calling GitHub in the middle of a task. Disclosure up front: it is a paid product and it is not open source. The free tier covers one repository; unlimited repositories are $5/month or $48/year.

The Codex-specific part is the sandbox. Codex CLI's default workspace-write sandbox runs with network access off, so gh issue view 42 mid-task cannot reach GitHub: it fails, or the agent stops to ask you to let it out of the sandbox. I checked this on macOS with Codex CLI 0.155.1, running commands through codex sandbox --permission-profile :workspace in a repo registered with ghfs:

$ gh issue list --limit 1
error connecting to api.github.com
$ cat .ghfs/github/issues/open/*.md > /dev/null && echo readable
readable

The files are fetched before the task starts, so reading them needs neither the network nor an approval.

What goes into AGENTS.md

ghfs rules (or the prompt at the end of ghfs register) appends a section to your existing AGENTS.md, between <!-- ghfs:begin --> and <!-- ghfs:end -->. Running it again replaces only that section and leaves the rest of your file alone. The section describes the layout:

.ghfs/
└── {provider}/           # e.g., "github" or "github-work"
    └── issues/
        ├── open/
        │   └── {number}.md   # e.g., "42.md"
        └── closed/
            └── {number}.md

and tells the agent to pick one way of reading: {number}.md for one to three issues, or the hidden .index.json once for anything cross-cutting, never both in the same task.

The section is about 4 KB, which counts against project_doc_max_bytes (32 KiB by default). Codex also takes at most one instruction file per directory and prefers AGENTS.override.md, so if your repo root has an override, the ghfs section in AGENTS.md is not loaded and belongs in the override instead.

Limits

It does not sync in real time: what is on disk is as recent as the last fetch, by command or by the background sync. Read-only is enforced by ghfs, not by the token. The device flow asks for repo scope, which GitHub treats as write-capable, and https://ghfs.dev/security#read-only covers what that does and does not mean. It is GitHub Issues only, today.

Requirements:

• macOS: Apple Silicon, macOS 26 or later, macFUSE 5.4.0 or later
• Linux: x86_64 or ARM64 with libfuse3
• Windows: inside WSL 2

On macOS, install macFUSE and enable its File System Extension in System Settings before installing ghfs. Then install with curl -fsSL https://ghfs.dev/install.sh | sh. The site is https://ghfs.dev/

If you point Codex at your own issues this way, I would like to hear where it gets in the way, especially with override or fallback-filename setups I have not tried.

[ooocooc]

One fallback-filename case worth testing is whether rule generation preserves the guidance that Codex was already selecting.

In a disposable repository with an isolated test configuration, set project_doc_fallback_filenames = ["TEAM_GUIDE.md"], put a nonempty TEAM_GUIDE.md at the root, and leave both AGENTS.md and AGENTS.override.md absent there. Codex's documented discovery order checks override, then AGENTS.md, then configured fallbacks, selecting at most one file per directory.

If ghfs rules creates a new nonempty AGENTS.md in that fixture, TEAM_GUIDE.md would no longer be selected at that directory, even if its bytes were untouched. Preserving content outside the ghfs markers would not, by itself, detect that change in the effective instruction set.

I haven't installed ghfs or reproduced its behavior when AGENTS.md is absent. If it already refuses or warns in that case, retain that as a regression. Otherwise, a preflight warning and explicit destination choice could prevent silently replacing the selected source.

For the acceptance check, compare the loader-selected source in fresh Codex runs at the same working directory before and after generation, and verify preservation of the pre-existing guidance—not only the presence of ghfs markers. The fallback configuration reference describes the setup and restarting to load it.

[ghfs-dev]

Thanks, this was a real bug. Your fixture reproduced it: ghfs rules created a new AGENTS.md, and Codex stopped selecting TEAM_GUIDE.md in that directory.

It is fixed in v1.1.2 (ghfs update). When there is no AGENTS.md and Codex would read a nonempty fallback file there instead, ghfs rules no longer creates AGENTS.md. It says which file Codex is reading and which config set that, and asks whether to append the ghfs section to that file instead. Declining, or no input at all, writes nothing and points to ghfs rules --print for adding it by hand. Names like docs/GUIDE.md resolve from the working directory the way Codex resolves them, and a file outside the working directory is never written.

Limits: ghfs reads /etc/codex/config.toml, $CODEX_HOME/config.toml, the project .codex/config.toml files and /etc/codex/managed_config.toml. It cannot see --profile, -c, or MDM and cloud-managed values, and it does not evaluate project trust; when the name comes from a project config, the message says Codex uses it only if the project is trusted.

For the acceptance check I did what you described, with Codex CLI 0.155.1 and an isolated CODEX_HOME: a fresh codex exec in the same directory before and after, checking which guidance reached the session rollout. With TEAM_GUIDE.md and a yes, before had TEAM_GUIDE.md, after had TEAM_GUIDE.md plus the ghfs section, and no AGENTS.md existed. With no input, nothing was written and the rollout still had only TEAM_GUIDE.md. docs/GUIDE.md as the fallback name behaved the same way. With an existing AGENTS.md, or no fallback configured, the behavior is unchanged.