AnyFS

---
name: AnyFS
description: >
  This skill should be used when the user asks to "share agent state", "capture session",
  "share context", "open shared link", "register agent", "anyfs share", "anyfs open",
  "anyfs register", "resume session", "cross-client resume", "encrypt and share",
  "publish package", "fork package", "export recovery key", "setup anyfs",
  or mentions AnyFS, anyfs CLI, agent identity, agent state management,
  or cross-harness session transfer.
  Provides comprehensive guidance for the AnyFS command-line interface and SDK.
version: 0.6.1
---

# AnyFS

AnyFS is an agent-native filesystem that captures, encrypts, and shares AI agent state across
different agent harnesses (Claude Code, Codex CLI, Gemini CLI, Cursor, Hermes, Nanobot, OpenClaw, OpenCode). It provides
E2E encryption, cryptographic agent identity, and cross-harness session sharing.

## Install / Update

This skill is published as static files under `https://skills.anyfs.ai/`.

Method 1: bootstrap the CLI into `~/.anyfs/.venv`
```bash
curl -fsSL https://skills.anyfs.ai/install.sh | bash
```

This installs the PyPI package `anyfs` into `~/.anyfs/.venv` and links `~/.local/bin/anyfs`
to that virtualenv so `anyfs` can be run from any shell once `~/.local/bin` is on `PATH`.

Method 2: direct files
- `https://skills.anyfs.ai/skill.md`
- `https://skills.anyfs.ai/package.json`
- `https://skills.anyfs.ai/install.sh`
- `https://skills.anyfs.ai/references/cli-commands.md`
- `https://skills.anyfs.ai/references/architecture.md`
- `https://skills.anyfs.ai/examples/quick-share-flow.sh`

Method 3: read the skill directly
```bash
curl -fsSL https://skills.anyfs.ai/skill.md
```

Refresh the skill instructions:
```bash
curl -fsSL https://skills.anyfs.ai/skill.md
```

Manual Codex install:
```bash
mkdir -p ~/.codex/skills/anyfs
curl -fsSL https://skills.anyfs.ai/skill.md -o ~/.codex/skills/anyfs/SKILL.md
curl -fsSL https://skills.anyfs.ai/package.json -o ~/.codex/skills/anyfs/package.json
```

Manual generic install:
```bash
mkdir -p <skills-root>/anyfs
curl -fsSL https://skills.anyfs.ai/skill.md -o <skills-root>/anyfs/SKILL.md
curl -fsSL https://skills.anyfs.ai/package.json -o <skills-root>/anyfs/package.json
```

Version check:
```bash
curl -fsSL https://skills.anyfs.ai/package.json | jq -r .version
cat ~/.codex/skills/anyfs/package.json | jq -r .version
```

Version source of truth:
- `skills/anyfs/package.json`

When updating the skill, bump `version` in both:
- `skills/anyfs/package.json`
- the frontmatter `version:` field in this `SKILL.md`

## Core Concepts

**Agent Identity**: Each agent gets an Ed25519 key pair on registration. The public key
becomes the agent's DID (`did:key:z6Mk...`) — this is the cryptographic identity.
The display name (e.g., `chad-claude-code`) is the human-readable label.
Same user on different harnesses = different agents, different identities, different permissions.

**Namespaces**: Agent state is organized into namespaces:
- `memory` - Agent memory and learned context
- `skills` - Instructions, prompts, rules (e.g., CLAUDE.md)
- `soul` - Identity and core beliefs
- `process` - Session transcripts and logs
- `artifacts` - Final public outputs and deliverables (for example PDFs, videos, reports, generated datasets, exported assets). Do not treat source code, dependency trees, runtime files, or general workspace contents as `artifacts`.

**Encryption**: All private namespaces are E2E encrypted with AES-256-GCM. The server
never sees plaintext. A three-level key hierarchy (wrap key -> root key -> DEK) ensures
each namespace payload has its own encryption key.

## Three Core Commands

Daily usage requires only three commands: **register**, **share**, and **open**.

**Receiving-side rule**: `open` is the primary action. After opening a share, the recipient
can either read the restored context directly or optionally `resume` it into a native
client session. Do not frame `resume` as mandatory.

Use this distinction when explaining collaboration:
- for handoff, review, or understanding, reading the restored session files directly is enough
- for reusing that context inside the target client and continuing to ask follow-up questions there, use `resume`

### `anyfs register`

Register this agent with a display name. Generates an Ed25519 key pair and registers
the public key (DID) on the AnyFS platform. Run once per machine per agent harness type.

```bash
anyfs register --type claude-code
```

Interactive prompt:
```
What should this agent be called? chad-claude-code

Registered!
  Name:  chad-claude-code
  DID:   did:key:z6MkfCyfBq5TFidh24MZbpmiBgNWNH9uNGDcSpL99yMNzqFK
  Type:  claude-code
```

If the agent is not registered and the user runs `anyfs share`, the CLI must stop and
ask the user to register first:
```
Agent not registered for claude-code. Run `anyfs register --type claude-code` first.
```

**Important**: When assisting a user with AnyFS and the agent is not yet registered,
prompt the user for a display name before proceeding. Do not auto-generate a name.
The display name is how the agent appears to collaborators, so the user should choose it.

### `anyfs share`

Capture the current agent state, package the workspace, encrypt both, upload them, and return shareable links.

```bash
anyfs share --type claude-code -m "Restore workspace, then resume process in Codex"
```

Output:
```
Capturing claude-code state...
Encrypting 3 namespaces (memory, skills, process)...
Uploading to IPFS...

Share link:  https://anyfs.ai/s/abc123
Password:    kX9mPqR2vL5n

Send both to your collaborator.
```

Options:
```bash
anyfs share --type claude-code -p MyPassword -m "Handoff note"     # Use a specific password
anyfs share --type claude-code -n memory,skills -m "Review only"   # Share only specific namespaces
anyfs share --type claude-code --workspace-mode full -m "Full repo handoff"
anyfs share --type claude-code --process-scope all -m "Share every workspace session"
anyfs share --type claude-code -w /path/to/project -m "Resume here"
```

By default, `anyfs capture` captures all matching sessions for the selected client scope.
`anyfs share` still defaults to the current session handoff flow. Use `--process-scope current`
when you explicitly want only the current session.

In normal use, you do not need any process-selection environment variables. AnyFS will pick the
current or closest persisted session automatically. Only set a client-specific override when you
need to force one exact session:
- `ANYFS_CLAUDE_SESSION_ID`
- `ANYFS_GEMINI_SESSION_ID`
- `ANYFS_OPENCLAW_SESSION_ID`
- `ANYFS_OPENCLAW_SESSION_KEY`
- `ANYFS_OPENCODE_SESSION_ID`
- `ANYFS_HERMES_SESSION_ID`
- `ANYFS_NANOBOT_SESSION_KEY`
- or the generic `ANYFS_CURRENT_PROCESS_ID`

**Workspace mode** is auto-detected. When the working directory is inside a git repo,
AnyFS defaults to `changed` (only modified files — the receiver clones the repo and
applies the overlay). When there is no git repo, AnyFS automatically escalates to
`full` so the entire working directory is included. You can still override with
`--workspace-mode changed|full|none` if needed.

Under the hood: auto-init -> capture -> snapshot -> encrypt -> upload -> return link.

### `anyfs open`

Decrypt and load a shared context. Works with a password or with the agent's private key
for password-protected share artifacts.

```bash
anyfs open https://storage.anyfs.ai/raw/<cid> -p kX9mPqR2vL5n --type codex-cli
```

Output:
```
Shared by: chad-claude-code (did:key:z6Mk...fCyf)
Decrypting 3 namespaces...

Restored to: /tmp/anyfs-restore/
  workspace/    (restored files)
  process.json  (2 sessions)
```

If the share was encrypted directly to this agent's DID:
```bash
anyfs open https://anyfs.ai/s/abc123
# No password needed — decrypts with agent's private key
```

After `open`, the restored directory contains up to three namespaces. Here is what each
one is for and how you (the agent) should use it:

**process** (`process.json`)
The sender's conversation history — user messages, assistant replies, tool calls. Read
this file to understand the full context of the work that was done, decisions made, and
where the sender left off. This is usually enough for review, summarization, or handoff.
If the receiver wants to *continue* the conversation natively, use `anyfs resume`.

**skills** (`skills.json`)
Project-level guidance, rules, and instructions that the sender's agent was following
(e.g. CLAUDE.md content, Codex `$`-skills, Gemini instructions). Read these to align
your behavior with the sender's setup — they tell you coding conventions, test commands,
deployment procedures, etc.

**workspace** (`workspace/` directory + `workspace.json` metadata)
The sender's working directory state. The `workspace.json` file contains a `binding`
object with `remote` (git URL), `commit_sha`, `branch`, and `cwd`. Use it like this:

- If `binding.remote` is a git URL: clone that repo and checkout `binding.commit_sha`.
  The restored `workspace/` files are an overlay (changed files only by default) — copy
  them onto the checkout to reproduce the sender's exact working state.
- If `binding.remote` is absent: the sender was not in a git repo. The `workspace/`
  directory *is* the full working tree (when `--workspace-mode full` was used) or a
  partial overlay.
- The CLI prints "Next:" steps after open that tell you exactly what to clone and where
  to apply the overlay. Follow those steps.

Use this when the goal is understanding, review, summarization, or continuing work without
modifying the target client's native session store.

#### Before `anyfs open`: register the receiver's client type

`anyfs open` now refuses to proceed when the receiving client type is not registered on
this machine. It prints a stderr error like this:

```
❌ codex-cli is not registered with AnyFS on this machine yet.
   Register this client type before opening the shared context:

       anyfs register --type codex-cli <your-display-name>
```

**When the agent (you) sees this error, do this:**

1. Read the explicit `--type` that the user used for `anyfs open`.
2. Ask the user once for a short display name (e.g. `alice-claude-code`).
   Do not auto-generate the name — the display name is how the user appears
   to collaborators, so the user should choose it.
3. Run `anyfs register --type <open-type> <chosen-name>`.
4. Re-run the same `anyfs open` command after registration succeeds.

For a single-step variant when the user already gave you a name:

```bash
anyfs open <link> -p <password> --type codex-cli --register-as <display-name>
```

This registers the machine-level `codex-cli` agent first, then decrypts the share.

## Cross-Harness Session Resume

Use `resume` only when the recipient wants the target client's native session experience
after `open`:

In other words:
- `open` is enough for collaboration and reading session content
- `resume` is required when the recipient wants to reuse that context inside the target client and keep chatting there

```bash
anyfs open https://anyfs.ai/s/abc123 -p Pass123 --type codex-cli
anyfs resume .anyfs/imports/abc123/process.json --target codex-cli
```

Or as a single step:
```bash
anyfs open https://anyfs.ai/s/abc123 -p Pass123 --type codex-cli --resume
```

Supported resume targets: `claude-code`, `codex-cli`, `gemini-cli`, `cursor`, `openclaw`, `opencode`.
Supported migrate/capture agent types: `claude-code`, `codex-cli`, `gemini-cli`, `hermes`, `nanobot`, `openclaw`, `opencode`.

## Two Usage Scenarios

AnyFS supports two distinct scenarios. Both start with `anyfs register`.

### Scenario 1: Peer-to-Peer Sharing

Direct context sharing between collaborators. One person shares encrypted agent state,
the other opens it. No platform account or marketplace needed.

```
Sender:    anyfs register --type <sender-client> → anyfs share --type <sender-client> → send link + password
Receiver:  anyfs open <link> -p <password> --type <receiver-client> → anyfs resume (optional)
           anyfs register --type <receiver-client> <name>   # only when they want to share/publish back later
```

**When to use**: Handing off work to a teammate, sharing session context across your own
devices, cross-harness continuation (e.g., Claude Code to Codex).

### Scenario 2: Platform Distribution

Package agent knowledge as reusable, forkable artifacts. Publish to the AnyFS registry
so others can discover, fork, and build on your agent's outputs. Creates a Reference DAG
(lineage graph) that tracks provenance across forks.

```
Author:    anyfs register → anyfs capture → anyfs pack → anyfs publish
                                                           ↓
                                              anyfs release create (versioned)
                                                           ↓
Consumer:  anyfs fork <package_id> → anyfs lineage show
```

**When to use**: Distributing curated agent knowledge (prompts, memory, skills) to a team
or community. Building on someone else's published agent outputs. Tracking who derived
what from whom.

**Artifact boundary**: `artifacts` should represent the end result of the work, not the codebase itself.
Good examples: generated PDF, rendered video, exported slide deck, benchmark report, model output bundle.
Bad examples: source files, `node_modules`, lockfiles, build caches, local config, or generic workspace files.

## Command Reference

### Core (both scenarios)

| Command | Purpose |
|---------|---------|
| `anyfs register --type <agent-type>` | Register a machine-level agent identity (Ed25519 key pair + display name) |
| `anyfs doctor` | Run diagnostics |
| `anyfs export-recovery` | Export recovery key bundle |
| `anyfs import-recovery` | Import recovery key bundle |

### 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 for the current receiving client |
| `anyfs resume <file>` | Cross-harness session resume |
| `anyfs backup` | Upload encrypted snapshot to cloud (personal backup) |

### Platform Distribution

| Command | Purpose |
|---------|---------|
| `anyfs capture <agent-type>` | Extract agent state into namespaces |
| `anyfs pack [snapshot_id]` | Build AFPKG archive from a snapshot |
| `anyfs publish [archive]` | Publish package to registry + blob storage |
| `anyfs fork <package_id>` | Fork a published package |
| `anyfs release create <pkg>` | Create a versioned release |
| `anyfs lineage show <pkg>` | View fork/derivation history (Reference DAG) |
| `anyfs snapshot list` | List all snapshots |
| `anyfs restore` | Decrypt and restore a snapshot locally |

## Agent Registration Behavior

When running as a skill inside an agent harness, follow this loop on every AnyFS
command, including `anyfs open`:

1. **Check if agent is registered**: Look for a machine-level AnyFS agent for the explicit current client type.
2. **If not registered**:
   - For `share` / `publish` / `capture` / `pack`: stop, ask the user for a
     display name, then run `anyfs register --type <current-harness> <name>`
     before retrying.
   - For `open`: still let the open finish so the user gets the decrypted
     context, but **immediately afterwards** ask the user for a display name
     and run `anyfs register --type <current-harness> <name>`. This is the
     only way the receiver can share or publish back later. The CLI also
     prints a stderr warning telling you exactly what to run — treat that
     warning as an instruction, not noise.
3. **If registered**: Proceed normally. The agent's DID and private key are
   already available.

Never auto-generate the display name. The display name is how the agent appears
to collaborators, so the user must choose it.

The harness type to pass to `--type` is one of:
`claude-code`, `codex-cli`, `gemini-cli`, `openclaw`, `opencode`, `hermes`, `nanobot`.
Pick the one that matches the client you (the agent) are running in.

## Configuration

AnyFS stores global state in `~/.anyfs/`. Configuration is in `~/.anyfs/config.json`:

```json
{
  "version": 1,
  "default_api_base_url": "https://api.anyfs.ai",
  "storage_gateway_url": "https://storage.anyfs.ai"
}
```

Environment variables override config file values:
- `ANYFS_API_BASE_URL` - API server URL
- `ANYFS_STORAGE_GATEWAY_URL` - Blob storage gateway URL

## Publish Visibility Policy

Visibility policy v1 only affects `pack` and `publish`.

- Default behavior stays the same: `artifacts` are public, everything else is private.
- Policy file path: `.anyfs/visibility.json`
- CLI overrides policy file
- v1 only supports `public` for `artifacts`; all other namespaces must stay private

Example:

```json
{
  "version": 1,
  "publish": {
    "default": "private",
    "namespaces": {
      "artifacts": "private"
    }
  }
}
```

CLI examples:

```bash
anyfs pack -w . --private artifacts
anyfs publish -w . --visibility-policy ./.anyfs/visibility.json
```

Note: `share` and `snapshot create` do not read this policy file. Their behavior is controlled separately.

## Additional Resources

### Reference Files

For detailed documentation, consult:
- **`references/cli-commands.md`** - Complete CLI command reference with all flags and options
- **`references/architecture.md`** - System architecture, encryption model, key hierarchy, and data flow
- **`references/sharing-and-encryption.md`** - Detailed guide on E2E encryption, password sharing, and storage-gateway-backed uploads
- **`references/cross-harness-resume.md`** - Cross-harness session resume: adapters, UASF format, supported agents

### Example Workflows

Working examples in `examples/`:
- **`examples/quick-share-flow.sh`** - End-to-end quick share workflow
- **`examples/cross-client-resume.sh`** - Cross-harness session transfer examples