omnifs mirrors the entire world into your local filesystem. GitHub repos, Hugging Face models, Kubernetes clusters, Slack channels, arXiv papers, and more as paths you can cd, ls, cat, and grep.
Plan 9 was right, just 40 years early. Everything is a file. The world moved to APIs; omnifs moves it back to paths, for humans and agents alike.
🚧 very alpha!
- Node.js and npm for the packaged CLI path
- Docker on Linux, or Docker Desktop on macOS
- SSH agent running with a GitHub key loaded if you want repo clone paths under
/github
The normal user flow is owned by the omnifs CLI. The CLI stores credentials on the host, generates thin mount configs under ~/.omnifs/config/mounts, starts the runtime container, and opens a shell into it.
npm install -g @0xff-ai/omnifs
omnifs init github
omnifs init linear
omnifs status
omnifs up
omnifs shellGitHub uses device-code OAuth with the bundled public client id and no default write scopes. Linear uses browser PKCE OAuth with the bundled public client id and read scope. You do not need to edit configs, copy provider wasm into ~/.omnifs/data/providers, or set OAuth client id environment variables for the bundled providers. omnifs up uses the version-matched runtime image unless you override it with --image or OMNIFS_IMAGE.
The npm package installs only the native host CLI. It does not pull the Docker image during install; omnifs up pulls and starts the matching runtime image. On macOS, the mount is available inside the Docker Desktop Linux container through omnifs shell, not as a native Finder or host-shell mount.
Use omnifs logs, omnifs logs -f, and omnifs down to inspect and stop the container.
omnifs dev is the development workflow for this repo. It captures your gh token, fetches the Chinook SQLite fixture, builds the image tagged at the current commit, synthesizes dev mount configs from the built-in provider manifests, and launches the container directly:
# Clone the repo
git clone https://github.com/raulk/omnifs
cd omnifs
# Build, materialize, and start the dev container
omnifs dev
omnifs shell-y skips the session confirmation prompt.
#####################
## GitHub as files
###################
# List repos in user/org
> cd /github/torvalds
> ls
1590A GuitarPedal libdc-for-dirk linux subsurface-for-dirk uemacs
AudioNoise HunspellColorize libgit2 pesconvert test-tlb
# cd into a repo
> cd /github/ollama/ollama
> ls
_actions _issues _prs _repo
# clone the repo just by listing it
> cd /github/ollama/ollama/_repo
> ls
CMakeLists.txt Makefile.sync cmd go.mod llm openai server x
CMakePresets.json README.md convert go.sum logutil parser template
CONTRIBUTING.md SECURITY.md discover harmony main.go progress thinking
[...]
# list open issues
> cd /github/ollama/ollama/_issues/_open
> ls
10333 10928 11381 11743 12138 12539 12959 13399 13879 14239 14621 15087 15398
10337 10929 11384 11746 12148 12541 12963 13401 13883 14243 14628 15091 15400
## ... and a lot more! play the video above for a walkthrough
###################
## DNS as files
###################
> cd /dns/cloudflare.com
> ls
A AAAA CAA CNAME MX NS SOA SRV TXT _all _raw
> cat A
104.16.133.229
> cat /dns/@8.8.8.8/google.com/AAAA
2a00:1450:4003:804::200e
> cat /dns/_reverse/1.1.1.1
one.one.one.one.
## poke around!Use omnifs logs (-f to follow) and omnifs down to inspect and stop the dev container.
SSH agent troubleshooting
omnifs clones repos over SSH inside the container using your forwarded agent socket. This does not copy your private key into the container, but it does let the container ask your agent to sign while the socket is mounted.
Verify your setup:
echo "$SSH_AUTH_SOCK"
ssh-add -L
ssh -T git@github.qkg1.topAgents should not have to deal with APIs. If you can read a file, you can read the world. No SDK to install, no authentication flow to implement, no pagination to manage. Just open a path and read. Write files, commit, push to sync back. The filesystem is the universal API.
omnifs runs as a FUSE filesystem on Linux (macOS and Windows planned). The architecture has three layers:
┌────────────────┐
┌──────────────┐ ┌────────────────────────────┐ │ github.wasm ├──▶ GitHub
│ your shell │ FUSE │ omnifs host │ callouts │ linear.wasm ├──▶ Linear
│ or agent │ ◀──────▶ │ /github /linear /arxiv │ ◀-──────▶ │ arxiv.wasm ├──▶ arXiv
│ │ files │ ... │ │ ... ├──▶ ...
└──────────────┘ └────────────────────────────┘ │ │
└────────────────┘
Wasm providers are WebAssembly components. Each provider projects a domain (GitHub, Linear, S3, whatever) into the filesystem namespace. Drop a .wasm into ~/.omnifs/data/providers/ and it mounts.
Callout runtime means providers never touch the network or Git directly. They describe what they need ("fetch this API endpoint", "clone this repo"), and the host executes. This keeps providers sandboxed and lets the host manage caching, rate limits, and concurrency.
Git-backed reconciliation (WIP) means writes work through Git. Edit files in a transaction directory, then rename it to commit/ to execute. The provider translates that into API calls. Everything stays auditable, revertible, and familiar.
| Provider | Mount | Description |
|---|---|---|
| GitHub | /github |
Browse repos, issues, PRs, CI runs, and diffs as files |
| DNS | /dns |
Query DNS records via DNS-over-HTTPS |
| arXiv | /arxiv |
Browse arXiv papers by id, category, author, or search; PDFs and source |
| Path | Content |
|---|---|
/github/{owner} |
List repos for a user or org |
/github/{owner}/{repo}/_repo/ |
Browse the repo tree (cloned on demand via SSH) |
/github/{owner}/{repo}/_issues/_open/ |
List open issues |
/github/{owner}/{repo}/_issues/_all/ |
List all issues |
/github/{owner}/{repo}/_issues/{filter}/{n}/title |
Issue title |
/github/{owner}/{repo}/_issues/{filter}/{n}/body |
Issue body (markdown) |
/github/{owner}/{repo}/_issues/{filter}/{n}/state |
Issue state |
/github/{owner}/{repo}/_issues/{filter}/{n}/comments/{i} |
Individual comment |
/github/{owner}/{repo}/_prs/{filter}/{n}/diff |
PR diff |
/github/{owner}/{repo}/_actions/runs/{id}/status |
CI run status |
/github/{owner}/{repo}/_actions/runs/{id}/log |
CI run log |
| Path | Content |
|---|---|
/dns/{domain}/A |
A records |
/dns/{domain}/AAAA |
AAAA records |
/dns/{domain}/MX |
MX records |
/dns/{domain}/NS |
NS records |
/dns/{domain}/TXT |
TXT records |
/dns/{domain}/CNAME |
CNAME records |
/dns/{domain}/SOA |
SOA record |
/dns/{domain}/_all |
All common record types |
/dns/{domain}/_raw |
dig-style output |
/dns/@{resolver}/{domain}/{record} |
Query via a specific resolver (e.g., @google, @1.1.1.1) |
/dns/{ip} |
Reverse DNS lookup (PTR) |
/dns/_reverse/{ip} |
Reverse DNS lookup (alternate path) |
/dns/_resolvers |
List configured resolvers |
Per-paper subtrees under /arxiv/papers/{id}/ are mirrored under every scope (categories, authors, search), so the same paper.pdf, metadata.json, versions/v{n}/... shape works under /arxiv/categories/{cat}/{ym}/{id}/... and friends.
| Path | Content |
|---|---|
/arxiv/papers/{id}/ |
Per-paper subtree (any arXiv id, e.g. 1706.03762) |
/arxiv/papers/{id}/paper.pdf |
Latest version PDF |
/arxiv/papers/{id}/source.tar.gz |
Latest version source bundle |
/arxiv/papers/{id}/metadata.json |
Title, authors, abstract, categories, comment, links |
/arxiv/papers/{id}/links.json |
Resolved arXiv URLs for this paper / version |
/arxiv/papers/{id}/versions/v{n}/{paper.pdf,…} |
Same files for a specific version |
/arxiv/categories/{cat}/{YYYY}/{MM}/{DD}/ |
Papers in cat posted on that UTC day (e.g. cs.AI/2024/01/31) |
/arxiv/categories/{cat}/new/ |
Most-recent papers in cat by submitted date |
/arxiv/categories/{cat}/updated/ |
Most-recent papers in cat by last-updated date |
/arxiv/categories/{cat}/by-author/{author}/ |
Papers in cat by author |
/arxiv/authors/{author}/ |
Papers by author with the same new/updated/by-category axes |
/arxiv/search/{query}/ |
arXiv search results (URL-encoded query) |
- Write-back via git push (mutations through staging transactions)
- Better caching (hot-path memoization, negative caching, smarter invalidation)
- Background indexing for large trees and expensive projections
- Search across projected content, metadata, and repo history
- Tracing and observability for provider calls, cache behavior, and FUSE latency
- Better prefetching and pagination strategies for large orgs and repos
- Persistent inode stability across remounts
- Offline-friendly local snapshots and replayable sync
- Mutation workflows beyond read-only browsing
- macOS and Windows support
| Provider | What it could project |
|---|---|
| GitHub | Commits, branches, reviews, checks, releases, and discussion state |
| Hugging Face | Models, datasets, spaces, cards, files, versions, and download metadata as browsable trees |
| Linear | Teams, projects, issues, cycles, comments, labels, and workflow state with draftable mutations |
| DNS | Zones, records, history, propagation state, and provider-backed change transactions |
| S3 and object stores | Buckets, prefixes, object metadata, versions, lifecycle rules, and event streams |
| OCI registries | Images, tags, manifests, layers, SBOMs, and signature material as mountable content |
| Kubernetes | Clusters, namespaces, workloads, logs, events, and live resource views |
| Postgres and SQLite | Schemas, tables, rows, views, and queryable virtual files for inspection and export |
| Slack and Discord | Channels, threads, message history, attachments, and searchable conversation snapshots |
MIT OR Apache-2.0