Artifact Fs
Developmentartifact-fsArtifact Fs is an Agent Skill for development published in the cloudflare/artifact-fs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Mounts Git remotes with ArtifactFS as local working trees without a full clone. Use when asked to mount a remote repo, explain committed state versus dirty overlay state, or mount multiple repos under one daemon.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/cloudflare/artifact-fs/blob/HEAD/.agents/skills/artifact-fs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/artifact-fs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
ArtifactFS Usage
Use this skill to operate ArtifactFS as a consumer. Prefer the CLI workflow and mounted repos. Do not inspect ArtifactFS internals unless the task is about developing ArtifactFS itself.
FIRST: Verify Prerequisites
Run from the repo root. If either check fails, STOP and fix the environment first.
test -e /Library/Filesystems/macfuse.fs || test -e /dev/fuse
test -x ./artifact-fs || go build -o artifact-fs ./cmd/artifact-fs
Critical Rules
- Use a dedicated state root. Set
ARTIFACT_FS_ROOT, usually under/tmp, so mounts and caches stay isolated. - Prefer HTTPS remotes. For private repos, use Git credential helpers or SSH auth. Do not embed tokens or passwords in the
--remoteURL because--remoteis a CLI arg and can show up in process listings. add-repodoes not mount. It registers a blobless clone and exits.daemonmounts all registered repos and stays running.- The mounted tree starts from committed Git state. Remote commits, trees, and refs are the base view. Local edits live in an overlay and appear as dirty state until committed.
- One daemon can mount many repos. Register each repo separately, then start one
daemon --root <mount-root>.
Quick Reference
| Task | Command |
|---|---|
| Register one repo | ./artifact-fs add-repo --name <name> --remote <url> --branch <branch> --mount-root /tmp |
| Mount all registered repos | ./artifact-fs daemon --root /tmp |
| Check mount and overlay state | ./artifact-fs status --name <name> |
| List registered repos | ./artifact-fs list-repos |
| Unmount or remove a repo | ./artifact-fs unmount --name <name> or ./artifact-fs remove-repo --name <name> |
Quick Start: One Repo
export ARTIFACT_FS_ROOT=/tmp/artifact-fs-demo
./artifact-fs add-repo \
--name workers-sdk \
--remote https://github.com/cloudflare/workers-sdk.git \
--branch main \
--mount-root /tmp
./artifact-fs daemon --root /tmp &
DAEMON_PID=$!
git -C /tmp/workers-sdk rev-parse HEAD
git -C /tmp/workers-sdk status
./artifact-fs status --name workers-sdk
kill $DAEMON_PID
# If a stale mount remains:
umount /tmp/workers-sdk
Mount Semantics
- Base view = branch
HEADfrom the blobless clone. File contents hydrate on first read. - Dirty files are overlay state, not part of the base commit.
./artifact-fs status --name <repo>reports this asoverlay_dirty=true. git addandgit commitinside the mount are supported. After commit or checkout, the watcher re-indexes the newHEADand reconciles stale overlay entries.
Quick Start: Multiple Repos
export ARTIFACT_FS_ROOT=/tmp/artifact-fs-demo
./artifact-fs add-repo --name repo-a --remote https://github.com/org/repo-a.git --branch main --mount-root /tmp
./artifact-fs add-repo --name repo-b --remote https://github.com/org/repo-b.git --branch main --mount-root /tmp
./artifact-fs daemon --root /tmp &
DAEMON_PID=$!
ls /tmp/repo-a
ls /tmp/repo-b
./artifact-fs list-repos
kill $DAEMON_PID
umount /tmp/repo-a
umount /tmp/repo-b