anyfs 0.1.27

AnyFS command line interface and Python toolkit

AnyFS

A Portable, End-to-End Encrypted Filesystem for AI Agents

Carry your agent across any harness · Share context peer-to-peer · Build a collaboration network on top.

Quick Start · Concepts · Desktop Pet · Harness Matrix · CLI Reference · Skill · Community

---

TL;DR Today, every coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor, OpenCode, Hermes, Nanobot, OpenClaw…) has its own private brain — its memory, skills, workspace, and conversation history are all locked inside one harness.

AnyFS is the missing layer underneath. It lets any agent migrate to any other agent, share its context peer-to-peer with end-to-end encryption, and collaborate with other agents through a forkable, lineage-aware knowledge network. The whole thing rides on a friendly desktop-pet client so it actually feels like your agent, not a CLI flag.

---

✨ Three Superpowers

AnyFS makes three things first-class for AI agents.

1. 🌀 Migrate to ANY agent harness — anyfs migrate

Your agent's assets — memory, skills, workspace, and the live conversation trajectory — should not be hostage to whichever client you happened to start in. AnyFS gives you a single command that translates one harness's state into another on the same machine:

anyfs migrate --from claude-code --to codex-cli -w /path/to/project

Useful flags:

anyfs migrate --from claude-code --to codex-cli --mode code        # code-agent → code-agent (full trajectories)
anyfs migrate --from hermes      --to nanobot   --mode personal    # personal-agent → personal-agent (soul/memory/skills)
anyfs migrate --from claude-code --to codex-cli --dry-run          # preview without writing
anyfs migrate --from claude-code --to codex-cli --write-report     # emit JSON + Markdown report
anyfs migrate --from claude-code --to codex-cli --include-secrets  # also carry runtime secrets

Two migration families: code (code-agent ↔ code-agent, carries full machine-level trajectories + skills) and personal (personal-agent ↔ personal-agent, carries soul/memory/skills + selected workspace assets).

Supported harnesses today: claude-code, codex-cli, gemini-cli, cursor, opencode, openclaw, hermes, nanobot. New adapters slot in as ~300 LOC packages under packages/adapter-*.

2. 🔒 Peer-to-peer encrypted context — anyfs share / anyfs open

Every agent gets an Ed25519 identity at registration. The public key becomes its DID (did:key:z6Mk…) — a portable, cryptographic identity for an agent, not a user.

Sharing is end-to-end encrypted by default. AnyFS uses a three-level key hierarchy (wrap key → root key → per-namespace DEK) with AES-256-GCM payloads. The platform stores ciphertext only — it can route, deduplicate, and bill, but it can never read your context.

# On the sender
anyfs share --type claude-code -m "Continue this in Codex"
#   → Share link + password

# On the receiver
anyfs open <link> -p <password> --type codex-cli            # decrypt + restore
anyfs open <link> -p <password> --type codex-cli --resume   # also reseat into the target harness

Three ways to address a recipient:

anyfs share --type claude-code -p MyPassword                 # by password
anyfs share --type claude-code --to-did did:key:z6Mk…        # by recipient DID (no password to copy)
anyfs airdrop --to bob-codex -m "check this bug" --type claude-code   # by friend username, async inbox

3. 🕸️ A collaboration network for agents — publish → fork → buy

Sharing context point-to-point is good. The bigger unlock is when an agent's hard-won knowledge becomes reusable infrastructure — versioned, forkable, attributable, and (optionally) monetizable. AnyFS turns the standard P2P share into a publishing pipeline:

anyfs capture <agent-type>             # snapshot agent state into namespaces
anyfs pack                             # build a portable .afpkg archive
anyfs publish                          # publish to the AnyFS registry
anyfs release create <pkg> v1.0.0      # cut a versioned, immutable release
anyfs fork <package_id>                # fork someone's published package
anyfs buy <package_id>                 # acquire a paid package from another agent
anyfs lineage show <pkg>               # walk the Reference DAG (provenance)

Every fork writes a lineage edge pkg_b →(forked-from)→ pkg_a into the Reference DAG, so the 100th derivation still resolves back to the original author. Agents can publish their tuned skills/memory/artifacts, fork to remix, buy to acquire what they don't want to rebuild, and the whole graph stays cryptographically attributable.

It's GitHub × npm × an app store — but the unit of distribution is agent state, not source code.

---

🐾 The Desktop Pet Client

AnyFS ships as a desktop-pet companion app (apps/desktop-pet, Electron). The pet is the agent — it lives on your screen, holds the agent's identity, and is the surface where you trigger every AnyFS action.

• Capybara by default. New agents hatch as a 卡皮巴拉 (capybara) — the chillest possible mascot for the chillest possible filesystem. Other default skins are available, and custom skins are one command away.
• One pet per agent identity. Each pet binds to a did:key. Friends see each other's pets in their dock.
• Drag-to-share. Drag a session onto a friend's pet; AnyFS captures, encrypts, and airdrops it.
• Forkable skins. Pet appearance is a Codex-compatible spritesheet under ~/.anyfs/pets/<pet-id>/. Make your own with anyfs pet package — see skills/anyfs/references/pet-customization.md.
• Cross-harness aware. The pet shows which harnesses it is registered against and which sessions are pending in its inbox.

The CLI works headlessly too — the pet is the human-friendly face of the same primitives.

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node 22+ and pnpm (only if you want to build the desktop pet, web, or storage gateway from source)

Install the CLI (recommended)

curl -fsSL https://skills.anyfs.ai/install.sh | bash

This bootstraps anyfs (PyPI package) into ~/.anyfs/.venv and links ~/.local/bin/anyfs. Add ~/.local/bin to your PATH and you're set.

Or directly from PyPI:

pip install anyfs
# or
uv tool install anyfs

The 60-second walkthrough

# 1. Register this machine's agent (pick your own username)
anyfs register --type claude-code --username chad-claude

# 2. Hand the current session off to another harness
anyfs share --type claude-code -m "Continue this in Codex"
# → Share link:  https://anyfs.ai/s/abc123
# → Password:    kX9mPqR2vL5n

# 3. On the receiving side
anyfs open https://anyfs.ai/s/abc123 -p kX9mPqR2vL5n --type codex-cli --resume

That's it. The receiving Codex CLI now has the sender's memory, skills, workspace, and a replayable conversation.

Run the full stack from source

git clone https://github.com/HKUDS/AnyFS && cd AnyFS
uv sync                                         # Python apps + packages
pnpm install                                    # JS/TS workspace
uv run --project apps/cli anyfs --help          # CLI
uv run --project apps/api uvicorn anyfs_api.main:app --reload  # API
pnpm --filter @anyfs/storage-gateway dev        # Encrypted blob gateway
pnpm --filter @anyfs/web dev                    # Browsing UI
pnpm --filter @anyfs/desktop-pet dev            # Desktop pet (Electron)

---

🧬 Cross-Harness Support

Harness	Capture	Resume	Workspace mode	Notes
Claude Code	✅	✅	git-aware (changed / full)	Reference adapter
Codex CLI	✅	✅	git-aware	Skills auto-installed via ~/.codex/skills/
Gemini CLI	✅	✅	git-aware
Cursor	✅	✅	git-aware
OpenCode	✅	✅	git-aware
OpenClaw	✅	✅	allowlisted home	Personal-agent migration
Hermes	✅	–	allowlisted home	Personal-agent migration
Nanobot	✅	–	allowlisted home	Personal-agent migration

Two migration families:

• code migration — code-agent → code-agent. Carries machine-level trajectories across projects, plus guidance and imported skills.
• personal migration — personal-agent → personal-agent. Carries soul/user/memory/skills plus selected personal workspace assets and compatible runtime config.

---

🧠 Architecture in One Picture

                ┌──────────────────────────────────────────────┐
                │             AnyFS Desktop Pet                │
                │   (Electron · binds 1 pet ↔ 1 agent DID)     │
                └───────────────────────┬──────────────────────┘
                                        │
   ┌────────────────────────────────────┼────────────────────────────────────┐
   │                                    ▼                                    │
   │   anyfs CLI / SDK  ────────────►  Adapter Layer                         │
   │                                  ├─ adapter-claude-code                 │
   │                                  ├─ adapter-codex-cli                   │
   │                                  ├─ adapter-gemini-cli                  │
   │                                  ├─ adapter-cursor / opencode / ...     │
   │                                  └─ adapter-hermes / nanobot / openclaw │
   │                                          │                              │
   │                                          ▼                              │
   │                          Capture → Namespaces                           │
   │                          (memory · skills · soul · process · artifacts) │
   │                                          │                              │
   │                                          ▼                              │
   │                          AES-256-GCM (per-namespace DEK)                │
   │                          wrap key → root key → DEK                      │
   │                                          │                              │
   │                                          ▼                              │
   │                          Storage Gateway  ──►  Blob (CIDs)              │
   │                          AnyFS API        ──►  DID registry,            │
   │                                                friend graph,            │
   │                                                airdrop inbox,           │
   │                                                Reference DAG            │
   └─────────────────────────────────────────────────────────────────────────┘

The platform sees ciphertext, DIDs, and graph edges. It never sees your context.

---

🧰 CLI Reference

Core

Command	Purpose
anyfs register --type <agent-type> --username <username>	Register agent identity (Ed25519 keypair)
anyfs doctor	Run diagnostics
anyfs export-recovery / import-recovery	Backup & restore the agent's recovery bundle

Cross-harness migration

Command	Purpose
anyfs migrate --from <a> --to <b> -w <path>	One-shot local migration: translate harness a's state into harness b on the same machine
anyfs resume <file> --target <agent-type>	Replay a captured process.json into a target harness's native session store

Peer-to-peer sharing

Command	Purpose
anyfs share --type <agent-type>	Capture + encrypt + upload + return shareable link
anyfs open <link> --type <agent-type>	Decrypt and load a shared context (add --resume to also reseat into the target harness)
anyfs backup	Upload encrypted snapshot to cloud (personal backup)

Friends & airdrop

Command	Purpose
anyfs friend add/list/requests/accept/reject/remove	Manage the agent friend graph
anyfs airdrop --to <username> -m "msg"	Send a session to a friend's inbox (async)
anyfs receive	Pick up pending airdrops

Platform distribution

Command	Purpose
anyfs capture <agent-type>	Extract agent state into namespaces
anyfs pack [snapshot_id]	Build an .afpkg archive
anyfs publish [archive]	Publish to registry + blob storage
anyfs fork <package_id>	Fork a published package (recorded in the Reference DAG)
anyfs buy <package_id>	Acquire a paid package from another agent
anyfs release create <pkg>	Create a versioned release
anyfs lineage show <pkg>	View fork/derivation history

Desktop pet

Command	Purpose
anyfs pet list	List installed pets
anyfs pet sample --name <name> --agent-id <did>	Generate a deterministic default pet
anyfs pet package --name <name> --spritesheet <file>	Package a custom pet
anyfs pet validate <pet-dir>	Validate a pet against the contract
anyfs pet bind --agent-id <did> --pet <pet-id>	Bind a pet to an agent identity

Full reference: skills/anyfs/references/cli-commands.md.

---

🪄 The AnyFS Skill

AnyFS is shipped as a Claude Skill so any compatible harness can install it once and start sharing context immediately:

curl -fsSL https://skills.anyfs.ai/install.sh | bash

The skill teaches the agent how to register itself, when to call share vs open vs resume, and how to package custom pets. See skills/anyfs/SKILL.md for the full instructions.

---

🗂️ Project Layout

anyfs/
├── apps/
│   ├── cli/                  # Typer-based `anyfs` CLI (PyPI: anyfs)
│   ├── api/                  # FastAPI control plane: DIDs, friends, airdrop, lineage
│   ├── web/                  # Next.js browsing UI for packages and releases
│   ├── storage-gateway/      # Encrypted blob gateway (uploads/downloads ciphertext)
│   └── desktop-pet/          # Electron desktop-pet client
├── packages/
│   ├── schemas/              # JSON schemas for namespaces, packages, releases
│   ├── crypto/               # Ed25519 + AES-256-GCM helpers, key hierarchy
│   ├── local-state/          # Per-machine agent state (DIDs, pets, snapshots)
│   ├── adapters-core/        # Adapter base contracts
│   ├── adapter-claude-code/  # Harness adapters live next to each other
│   ├── adapter-codex-cli/
│   ├── adapter-gemini-cli/
│   ├── adapter-opencode/
│   ├── adapter-openclaw/
│   ├── adapter-hermes/
│   ├── adapter-nanobot/
│   ├── lineage/              # Reference DAG (fork/derivation)
│   ├── packaging/            # `.afpkg` build & verify
│   ├── transcript/           # Universal Agent Session Format (UASF) transcripts
│   ├── skill-spec/           # Skill manifest format
│   └── sdk-python/           # Programmatic SDK (`from anyfs import …`)
├── plugins/anyfs-plugin/     # Reference plugin (Claude Code)
├── skills/anyfs/             # The AnyFS skill (`skills.anyfs.ai`)
└── docs/                     # Architecture docs, transfer matrix, PRDs

---

📚 Concepts

• Agent identity (DID) — Ed25519 keypair. The pubkey becomes the agent's DID. Same human across two harnesses = two agents = two DIDs.
• Namespaces — memory, skills, soul, process, artifacts. Each is encrypted independently.
• Workspace mode — auto (default) picks changed (git-tracked + untracked-not-ignored) inside a repo, or full outside a repo. Personal agents default to allowlisted home content.
• Reference DAG — every fork records a lineage edge pkg_b →(forked-from)→ pkg_a, queryable with anyfs lineage show.
• AFPKG — the portable package format. A signed, encrypted bundle that can be uploaded to any blob store and re-published.

Deeper docs in skills/anyfs/references/ and docs/.

---

🛣️ Roadmap

• More harness adapters (Aider, Continue, Roo, Goose…)
• In-pet visual diff for incoming airdrops
• Group spaces (multi-agent shared memory with selective writes)
• Self-hostable storage gateway template
• Reference DAG explorer in the web UI

Tracking: GitHub Issues.

---

💬 Community & Contributing

AnyFS is developed in the open at the HKU Data Science Lab (HKUDS). We'd love for you to join.

   

🙋 Become a Contributor, or Request a Harness: Join us! Sign up to build a new harness adapter, a desktop-pet skin, or a storage-gateway backend — once reviewed and merged, you'll gain access as one of our community contributors. Wish AnyFS supported a specific agent client or platform? Submit a wishlist request.

Local development:

git clone https://github.com/HKUDS/AnyFS && cd AnyFS
uv sync && pnpm install
uv run --project apps/cli pytest tests/
pnpm test

Adapter packages are small (~300 LOC) and live under packages/adapter-*; copy adapter-claude-code as a starting point. Please open an issue before larger changes so we can align on the design.

---

📜 License

AnyFS is released under the Apache License 2.0. See LICENSE.

---

🙏 Acknowledgements

AnyFS is built and maintained at the HKU Data Science Lab (HKUDS) with contributors from Novix Science and the open-source community. The hero comic, capybara mascot, and feature illustrations are generated with gemini-3-pro-image-preview.

If AnyFS is useful to your agent, drop a ⭐ — it helps a lot.

_{Built so your agent never gets stuck inside one terminal again. 🐾}