OpenParable
Skip to content
← Back to skills

Artifact Fs

Development
artifact-fs

Artifact 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 --remote URL because --remote is a CLI arg and can show up in process listings.
  • add-repo does not mount. It registers a blobless clone and exits. daemon mounts 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

TaskCommand
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 HEAD from 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 as overlay_dirty=true.
  • git add and git commit inside the mount are supported. After commit or checkout, the watcher re-indexes the new HEAD and 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