hf-claw

An hf CLI extension to back up, publish, install, run, and mount Codex, Claude Code, and Pi/OpenClaw workspaces on the Hugging Face Hub.

Install

hf extensions install hf-claw

Harness Profiles

Flag	Default workspace	Main markers
--codex	CODEX_WORKSPACE or ~/.codex/workspace	AGENTS.md, .codex/
--claude	CLAUDE_WORKSPACE or ~/.claude/workspace	CLAUDE.md, .claude/
--pi	OPENCLAW_WORKSPACE or ~/.openclaw/workspace	SOUL.md, IDENTITY.md, .openclaw/

If you do not pass a harness flag, hf claw tries to detect the workspace from the current directory or known default locations and falls back to --pi.

Backup

Private sync uses HF Buckets.

hf claw init --pi
hf claw push --claude
hf claw pull --codex
hf claw status --codex

Publish

Public sync uses HF model repos. Publishing is harness-aware:

• --codex publishes AGENTS.md, .codex/, TOOLS.md, and skills/ when present
• --claude publishes CLAUDE.md, .claude/, TOOLS.md, and skills/ when present
• --pi publishes the original OpenClaw-style files such as SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, and skills/
• private files such as USER.md, MEMORY.md, memory/, BOOTSTRAP.md, and HEARTBEAT.md are stripped automatically

hf claw publish --claude
hf claw publish username/my-agent --codex --dry-run
hf claw install username/my-agent --pi

Additional files can be whitelisted with .publishinclude:

# .publishinclude
custom-prompts/*.md
my-skill-config.yaml

Run

hf claw run mounts first when a backup bucket is configured, then installs and launches from that workspace. Use --no-mount to keep the old local install-only flow.

hf claw run username/my-agent
hf claw run --claude username/my-agent "Fix the failing tests"
hf claw run --codex --dir /tmp/dave username/my-agent "Review this repo"
hf claw run --no-mount --codex username/my-agent "Stay local"

Launch behavior:

• Codex uses --yolo when the installed CLI supports it, otherwise falls back to the strongest available no-approval mode
• Claude Code uses --dangerously-skip-permissions when available
• Pi launches pi from the target workspace

Mount

hf claw mount wraps the current beta hf-mount helpers so a bucket-backed workspace can be used live.

hf claw mount --backend nfs --codex
hf claw unmount --codex

Default wrapper behavior:

• nfs: hf-mount-nfs bucket <bucket-name> <workspace-path>
• fuse: hf-mount bucket <bucket-name> <workspace-path>

If your local helper uses different flags or command names, override it with HF_CLAW_* mount environment variables. Legacy OPENCLAW_* mount overrides are also accepted.

Commands

Command	Description
`init [--bucket NAME] [--codex	--claude
`push [--delete] [--dry-run] [--codex	--claude
`pull [--delete] [--dry-run] [--codex	--claude
`status [--codex	--claude
`mount [--backend NAME] [--codex	--claude
`unmount [--codex	--claude
`publish [REPO_ID] [--dry-run] [--codex	--claude
`install REPO_ID [--dir DIR] [--merge] [--codex	--claude
`run REPO_ID [PROMPT] [--dir DIR] [--mount	--no-mount] [--codex
`config [--codex	--claude

License

Apache-2.0