I built a FUSE filesystem that mounts GitHub Issues as local files

#showdev #ai #cli

I usually develop software alongside Generative AI — specifically Claude Code. My workflow revolves around GitHub Issues as units of task management. I have the AI read an issue, investigate the scope, report on the implementation plan, and then proceed with the actual work.

When passing issue content to the AI, I use the gh command. The AI "knows" how to use it. But it frequently uses non-existent options or makes incorrect guesses, leading to errors and retries. These are wasted steps.

This could be addressed with rule files. But rule files should be for project-specific instructions, not for teaching an AI how to use general-purpose CLI tools. That felt like the wrong place to put that effort.

Just Make It a File

I'm skeptical of MCP servers. They add more uncertainty to the already uncertain behavior of Generative AI.

A filesystem is the same on every OS. Reading a file, running grep — these are things even Generative AI can execute reliably.

I also believe that with the advent of Generative AI, there is an advantage to keeping everything in one place. Having all the information necessary for a project contained within that repository or workspace is beneficial for providing context to the AI.

So I thought: what if GitHub Issues were visible as local files? That is why I built ghfs.

What is ghfs?

ghfs is a tool that mounts GitHub Issues as a local filesystem using FUSE. It is written in Go and supports macOS and Linux.

$ ls .ghfs/github/issues/open/
42.md  108.md  215.md

$ cat .ghfs/github/issues/open/42.md
---
number: 42
title: "Fix authentication bug"
state: open
author: username
labels:
  - bug
---

Issue body in Markdown...

## Comments

### username - 2024-01-02T12:00:00Z

Comment content...

I made it read-only. This tool is built on the premise that Generative AI will interact with it. I wanted to avoid situations where the AI might update an issue without permission. Even if you set up guardrails, you never know if they will work perfectly. By making it read-only, I can guarantee at the filesystem level that nothing will be destroyed.

By the way, having issue content show up in an IDE's full-text search is unexpectedly convenient for humans too.

It does not sync in real-time. Just like how code committed by someone else on GitHub doesn't automatically appear on your local machine, ghfs provides a command to fetch updates manually. A daemon can also sync in the background on a schedule.

I chose Go because I wanted it to be multi-platform. If I am going to use Generative AI more in the future, the tool should work on Linux and Windows as well.

Why Is It Paid?

I have long watched the owners of open-source software become exhausted. I felt that because OSS has become so closely tied to social networking, the purpose and means of a product can become messy.

And above all, you cannot live without money.

Who Is It For?

People who work based on issues. Or people who can embrace such a workflow.

It can act as a substitute for a human opening GitHub in a browser, or a substitute for an AI running gh commands. It comes down to whether you find value in that.

I would be happy if ghfs helps you in ways I never expected.