What is WasmClaw?

WasmClaw is a TypeScript / WebAssembly web agent runtime for the Claw ecosystem. It brings browser-native AI agents with:

• Browser-only runtime — no server required, no API keys needed
• Soul Spec native — first-class support for the Soul Spec persona format
• In-browser inference — WebLLM and Transformers.js powered; the user's device does the work
• WebAssembly sandbox (v0.2) — tool execution isolated via WASM
• BYOK fallback — optional OpenAI / Anthropic adapters with a ProviderChain that fails over automatically
• Cross-platform persona — Swarm Memory sync with SoulClaw Mobile

Install

npm install wasmclaw

# Optional peer deps — install only the backends you use:
npm install @mlc-ai/web-llm          # for WebLLMBackend
npm install @huggingface/transformers # for TransformersJsBackend
npm install fflate                    # for ZIP-based persona loading
npm install isomorphic-git @isomorphic-git/lightning-fs # for Swarm Memory (v0.3)

Quick start

The fastest way to see the engine working — no model download required:

import { WasmClawEngine, type ModelBackend } from 'wasmclaw';

const mockBackend: ModelBackend = {
  modelId: 'mock',
  contextLimit: 8192,
  async generateRaw() { return 'Hi! I am Brad, a mock agent.'; },
  countTokens(t) { return Math.ceil(t.length / 4); },
  abort() { /* no-op */ },
};

const engine = new WasmClawEngine({
  persona: {
    version: '0.3',
    identity: { name: 'Brad', type: 'pro-mode-claude' },
    soul: 'Be kind. Be precise.',
    identityMd: 'Name: Brad.',
    custom: new Map(),
    metadata: {},
  },
  backend: mockBackend,
});

const { text } = await engine.run('Hello!');
console.log(text); // "Hi! I am Brad, a mock agent."

Swap mockBackend for new WebLLMBackend({ model: 'Qwen2.5-0.5B-Instruct-q4f32_1-MLC' }) to run a real model in the browser. See examples/basic-browser/ for a runnable demo with both modes.

Swarm Memory (v0.3)

SwarmMemory gives each agent a Git branch for its memory state and syncs them across devices:

import { SwarmMemory, UNION_APPEND } from 'wasmclaw';

const swarm = new SwarmMemory({
  dir: '/swarm',
  remote: 'https://github.com/me/my-swarm.git',
  author: { name: 'Brad', email: '[email protected]' },
  auth: { username: 'token', password: process.env.GITHUB_TOKEN },
  onConflict: UNION_APPEND, // or your own LLM-backed resolver
});

await swarm.init();
await swarm.join({ id: 'brad-web' });
await swarm.commit('note: today I learned…', { 'memory/notes.md': '…' });
await swarm.push();

// Heartbeat pulls remote edits every 5 minutes
const stop = swarm.heartbeat(5 * 60 * 1000);

Install isomorphic-git alongside wasmclaw — it's an optional peer dep, not bundled.

SoulRollback (v0.3)

Hash-stamped checkpoints of agent data + contamination-aware auto-restore:

import {
  CheckpointManager,
  IndexedDBCheckpointStore,
  scanPersonaBundle,
} from 'wasmclaw';

const manager = new CheckpointManager({
  store: new IndexedDBCheckpointStore(),
  scanner: async (files) => {
    // Your multi-layer scan. Any function returning { score, grade, issues }
    // works — SoulScan is the obvious choice.
    return { score: 92 };
  },
  cleanThreshold: 75,
});

// Capture state after each meaningful turn:
await manager.create(currentSoulFiles, { label: 'post-refactor' });

// On suspicious output, auto-restore to last-clean:
const result = await manager.autoRestore(currentSoulFiles);
if (result.restored) {
  await writeFilesBack(result.files!); // your host-side apply
}

CLI (v0.3)

wasmclaw ships a zero-dependency Node CLI for smoke tests, CI scans, and quick persona iteration:

# Interactive REPL with a Soul Spec persona directory.
npx wasmclaw run ./persona --provider=anthropic --model=claude-3-5-haiku-latest

# One-shot turn, print-and-exit. Handy for CI and shell pipelines.
npx wasmclaw run ./persona --message="introduce yourself" --no-interactive

# Run SoulScan over a persona and emit JSON. Exits 2 when the grade is F.
npx wasmclaw scan ./persona

The CLI is BYOK-only — set ANTHROPIC_API_KEY or OPENAI_API_KEY, or pass --api-key. --provider=transformers runs fully offline via the optional @huggingface/transformers peer dep.

Documentation

• Architecture — v0.1 design, runtime abstraction, capability leases
• BYOK Policy — how credentials work (and don't)
• Security Model — threat model + layered defenses

Example

npm install
npm run example:browser

Vite will serve the demo at http://localhost:5173. The page ships with a built-in MockBackend that round-trips a tool call so you can see the agent loop in action without downloading any weights.

Roadmap

• v0.1 — agent loop, Soul Spec loader, WebLLM + Transformers.js + BYOK adapters, provider chain failover, tool registry + coercion + timeout, parser covering Gemma 4 native + JSON + loose fallback formats.
• v0.2 — SoulScan port (53 SEC + 11 QUA + 2 PII rules), IndexedDB-backed memory, capability-lease permission model.
• v0.3 (current) — Swarm Memory (Git-backed cross-device memory sync via isomorphic-git), SoulRollback checkpoints, optional CLI mode.
• v1.0 — ecosystem interop layer, WASM tool sandbox, stable API freeze, Play Store / Chrome Web Store reference agents.

See docs/ARCHITECTURE.md for the full design rationale.

Claw ecosystem

WasmClaw is one of several open agent runtimes in the Claw family:

| Project | Focus | Language | |---------|-------|----------| | OpenClaw | The incumbent agent framework | — | | ZeroClaw | Minimal, Rust-native, cross-platform | Rust | | IronClaw | Privacy-first, security-hardened | Rust | | WasmClaw | WASM + WebLLM + Soul Spec personas | TypeScript / WASM |

Contributing

See CONTRIBUTING.md. Issues, PRs, and design discussions welcome.

License

Apache-2.0 — see LICENSE.

WasmClaw is developed and maintained by the ClawSouls team, with plans to grow into an independent open-source community.