Metadata-Version: 2.4
Name: anyfs
Version: 0.1.27
Summary: AnyFS command line interface and Python toolkit
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1,>=0.15
Requires-Dist: rich<15,>=13
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: cryptography<45,>=42
Dynamic: license-file

<div align="center">

<img src="docs/images/readme/logo.png" alt="AnyFS" width="160" />

# 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.**

[![PyPI](https://img.shields.io/pypi/v/anyfs?color=4c8bf5&label=pypi%20%7C%20anyfs)](https://pypi.org/project/anyfs/)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776ab)](https://www.python.org/)
[![Node](https://img.shields.io/badge/node-22%2B-339933)](https://nodejs.org/)
[![Skill](https://img.shields.io/badge/skill-skills.anyfs.ai-7c3aed)](https://skills.anyfs.ai/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](#license)
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
[![HKUDS](https://img.shields.io/badge/lab-HKUDS-1f6feb)](https://github.com/HKUDS)

[**Quick Start**](#-quick-start) · [**Concepts**](#-three-superpowers) · [**Desktop Pet**](#-the-desktop-pet-client) · [**Harness Matrix**](#-cross-harness-support) · [**CLI Reference**](#-cli-reference) · [**Skill**](#-the-anyfs-skill) · [**Community**](#-community--contributing)

</div>

---

<div align="center">

<img src="docs/images/readme/hero-comic.png" alt="AnyFS — three superpowers" width="100%" />

</div>

> **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`

<div align="left">
<img src="docs/images/readme/feat-migrate.png" alt="Cross-harness migration" width="320" align="right" />
</div>

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:

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

Useful flags:

```bash
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-*`.

<br clear="right" />

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

<div align="left">
<img src="docs/images/readme/feat-encrypt.png" alt="End-to-end encrypted sharing" width="320" align="right" />
</div>

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.

```bash
# 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:

```bash
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
```

<br clear="right" />

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

<div align="left">
<img src="docs/images/readme/feat-network.png" alt="Agent collaboration network" width="320" align="right" />
</div>

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:

```bash
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.

<br clear="right" />

---

## 🐾 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`](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)

```bash
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:

```bash
pip install anyfs
# or
uv tool install anyfs
```

### The 60-second walkthrough

```bash
# 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

```bash
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`](skills/anyfs/references/cli-commands.md).

---

## 🪄 The AnyFS Skill

AnyFS is shipped as a [Claude Skill](https://www.anthropic.com/news/skills) so any compatible harness can install it once and start sharing context immediately:

```bash
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`](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/`](skills/anyfs/references) and [`docs/`](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](https://github.com/HKUDS/AnyFS/issues).

---

## 💬 Community & Contributing

AnyFS is developed in the open at the **HKU Data Science Lab ([HKUDS](https://github.com/HKUDS))**. We'd love for you to join.

<p>
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu" height="28"></a>
&nbsp;
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat" height="28"></a>
&nbsp;
<a href="https://github.com/HKUDS"><img src="https://img.shields.io/badge/HKUDS-Lab-1f6feb?style=flat" alt="HKUDS" height="28"></a>
</p>

**🙋 Become a Contributor, or Request a Harness**: [Join us](https://github.com/HKUDS/AnyFS/issues/new?template=contributor-signup.yml)! 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](https://github.com/HKUDS/AnyFS/issues/new?template=harness-wishlist.yml).

**Local development**:

```bash
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`](LICENSE).

---

## 🙏 Acknowledgements

AnyFS is built and maintained at the **HKU Data Science Lab ([HKUDS](https://github.com/HKUDS))** with contributors from [Novix Science](https://github.com/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.

<div align="center">

<sub>Built so your agent never gets stuck inside one terminal again. 🐾</sub>

</div>
