# ghfs
GitHub issues/PRs as filesystem, for offline view and operations in batch. Designed for human and agents.
> [!IMPORTANT]
> Still working in progress, not usable yet.
```bash
pnpm install @ghfs/cli
```
and then run the command inside a repository directory:
```bash
ghfs
```
It will sync the open issues and pull requests to the local filesystem under `.ghfs` directory, like:
```txt
.ghfs/
repo.json # repository basic information
issues.md # index of fetched issues
pulls.md # index of fetched pull requests
execute.md # queued operations
issues/
00134-some-bug.md
closed/
00135-fixed-crash.md
pulls/
00042-add-cache.md
00042-add-cache.patch
closed/
00043-release-cleanup.md
```
Then you can view them offline, or ask your local agent to summarize them for you.
## Web UI
`ghfs` ships a local web UI for browsing and acting on the synced mirror.
### `ghfs ui` — single project
Run inside a repository directory after a sync. Opens a browser tab with a two-pane (list + detail) view of the project's issues and PRs.
```bash
ghfs ui
```
Flags:
- `--port <number>` — port to listen on (default `7710`).
- `--host <addr>` — bind address (default `127.0.0.1`).
- `--cwd <path>` — project directory; defaults to the current working directory.
- `--no-open` — don't auto-open the browser (useful for headless setups).
The UI is read-and-queue: edits made in the interface are queued to `.ghfs/execute.yml` and `.ghfs/execute.md` — you still apply them with `ghfs execute --run`.
### `ghfs hub` — multi-project dashboard
Point at a directory that contains multiple project checkouts and `ghfs hub` scans for git repositories, lets you enable the ones you want, and exposes them all in one dashboard.
```bash
ghfs hub --cwd ~/projects
```
The hub keeps its enabled-project list and auto-sync interval in `~/.config/ghfs/hub.json`, keyed by the hub root. Switching roots remembers each root's selection independently.
Features:
- Project cards with activity sparkline, open issue / PR counts, last updated and last synced badges.
- `/recent` — cross-project list of recently-updated issues and PRs.
- Queue drawer (`q`) — aggregated queue across all enabled projects with per-project execute; press `X` to execute everything.
- Settings dialog (`,`) for hub root and an optional auto-sync interval (1–60 minutes).
Flags mirror `ghfs ui` (`--port`, `--host`, `--cwd`, `--no-open`).
## Saved replies
Insert canned replies into the comment composer with one click — or press <kbd>⌘</kbd> <kbd>.</kbd> (<kbd>Ctrl</kbd> <kbd>.</kbd> on Linux/Windows) when the composer is focused. Replies come from two scopes, surfaced in a single picker with a per-item indicator:
- **This repo** — `.github/replies.yml` in the repository. ghfs supports the [`refined-saved-replies`](https://github.com/JoshuaKGoldberg/refined-saved-replies) convention, so the same file works in the refined-saved-replies browser extension and any other tool that adopts it. Commit the file so the whole team shares them.
- **Global** — per-user replies stored in `~/.config/ghfs/hub.json`.
Edit either set from the **Settings** dialog (<kbd>,</kbd>) under the **Saved replies** tab. Bodies support a small set of placeholders, replaced at insertion time against the issue/PR being viewed:
| Placeholder | Resolves to |
| -------------- | ------------------------------------ |
| `{{author}}` | `@<login>` of the item's author |
| `{{number}}` | The issue / PR number |
| `{{title}}` | The item's title |
Example `.github/replies.yml`:
```yaml
- title: Thanks
body: |
Thanks for the report, {{author}}! We'll take a look at #{{number}}.
- title: Needs reproduction
body: Could you share a minimal reproduction?
```
> GitHub's own user "saved replies" (at github.com/settings/replies) have no public REST API, so ghfs can't sync them — global templates are managed entirely through ghfs.
## Execute operations
`ghfs` also allows you to take actions on the issues and pull requests in batch.
`ghfs execute` merges operations from multiple sources:
1. `execute.md` (human-friendly commands)
2. `per-issue` markdown frontmatter changes (from `.ghfs/issues/**/*.md` and `.ghfs/pulls/**/*.md`)
3. `execute.yml` (explicit YAML operations)
Note: execution merge order is `execute.yml` -> `execute.md` -> `per-issue` generated operations.
### 1) `execute.md` (recommended)
`execute.md` is best for quick/manual batching:
```md
close #123 #234
set-title #125 "New title"
label #125 bug, enhancement
close-comment #126 "Closing this as completed"
```
Action names in both `execute.yml` and `execute.md` are case-insensitive and support aliases, including:
- `closes` -> `close`
- `open` -> `reopen`
- `close-comment` / `comment-close` / `close-and-comment` / `comment-and-close` -> `close-with-comment`
`execute.md` also supports comment lines with `#` and `//`, plus HTML comment blocks using `<!-- ... -->`. These comments are preserved when operations are rewritten.
### 2) Per-issue operations
Edit frontmatter directly in issue/PR markdown files:
- `title`
- `state` (`open` / `closed`)
- `labels`
- `assignees`
- `milestone`
`ghfs execute` will diff these values and generate operations automatically (for example `set-title`, `close`/`reopen`, label updates, assignee updates, milestone updates).
### 3) `execute.yml`
`ghfs sync` or `ghfs execute` will auto-create `.ghfs/execute.yml` and `.ghfs/schema/execute.schema.json` if missing.
Use `execute.yml` for explicit/low-level operations:
```yaml
# close the issue #123
- action: close
number: 123
# change the title of the issue #125 to "New title"
- action: set-title
number: 125
title: New title
# add the labels "bug" and "feature" to the issue #125
- action: add-labels
number: 125
labels: [bug, feature]
```
Then run `ghfs execute` to preview, and `ghfs execute --run` to execute.
```bash
ghfs execute
ghfs execute --run
```
## AI label suggestions
`ghfs label` asks a decision model ([Jev](https://vercel.com/ai-gateway/models/jev) through [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)) which of the repository's labels fit each open, unlabeled item, using the items you already labeled as examples. When the model is unsure, a small tool-using agent reads comments, the patch, linked and similar items, and the model decides again with that context.
Suggestions are drafted into the queue as `add-labels` operations carrying the model's per-label probability. Nothing reaches GitHub until you review and execute them.
Paste a Gateway key under Settings (`,`) → API keys in the UI, or set `AI_GATEWAY_API_KEY`:
```bash
export AI_GATEWAY_API_KEY=vck_xxx
ghfs label # open & unlabeled items
ghfs label 123 456 # specific items
ghfs label --all # also items that already have labels
ghfs execute # review, then --run
```
In the UI the same action is available per item (`⇧L`, "Suggest labels") and for every unlabeled item from the navbar. Tune it in `ghfs.config.ts`:
```ts
export default defineConfig({
ai: {
model: 'typesafe-ai/jev', // decision model
agentModel: 'anthropic/claude-haiku-4.5', // agent for unsure items
labeling: {
threshold: 0.7,
examplesPerLabel: 3,
guidelines: 'Use "bug" only for reproducible defects.',
exclude: ['good first issue'],
},
},
})
```
## Graph view
The graph view (`g v`, or the graph icon in the navbar; `/graph` in `ghfs ui`, `/owner/repo/graph` in the hub) draws open issues and pull requests as a force-directed canvas. Every label is an anchor that pulls its items toward it, so the picture clusters by label; edges come from GitHub itself: cross-references, pull requests that close an issue, items marked as duplicates, and issues closed by the same commit.
- Drag an item onto a label anchor to queue `add-labels` for it.
- "Find duplicates" asks the decision model about title-similar pairs and draws suspected duplicates as orange dashed edges; clicking one queues closing the newer item as a duplicate of the older, attributed to the model with its probability.
- "Show closed" brings in every closed item; by default only closed items linked to an open one appear.
## Agent Skill
This repository ships an [agent skill](https://agentskills.io/home) at [`skills/ghfs/SKILL.md`](skills/ghfs/SKILL.md).
Install with [`skills`](https://github.com/vercel-labs/skills) CLI:
```bash
pnpx skills add antfu/ghfs
```
The `@ghfs/cli` also ship the skills into the npm package that you can have it also installed with [`skills-npm`](https://github.com/antfu/skills-npm):
```bash
pnpm i -D @ghfs/cli
pnpx skills-npm
```
## Configuration
You can configure by creating a `ghfs.config.ts` file in the root of the repository.
```ts
import type { GhfsUserConfig } from '@ghfs/cli'
export default defineConfig({
repo: 'owner/name',
sync: {
issues: true, // set false to skip issue sync
pulls: true, // set false to skip pull request sync
},
// other options...
})
```
## TODOs
- [x] `execute.md` file with human-friendly instructions (`close #123 #234`, `set-title #125 "New title"`).
- [x] Directly editing the `<5-digit-number>-<slug>.md` file to apply the operations.
- [ ] Add a VS Code extension for guided sync/execute.
- [ ] Documentation.
- [x] Index page, and basic repo info
- [x] Agent Skills.
- [x] Local Web UI for managing the local mirror (`ghfs ui` and `ghfs hub`).