Introduction
ClawJS is an open-source Node.js SDK and CLI for building local applications on top of multiple runtimes through one runtime-adapter contract.
Support note: adapter maturity differs. Check the support matrix before picking a runtime for production use.
Why ClawJS?
ClawJS gives you one place to solve the hard parts that show up across runtimes:
- runtime detection, install, repair, and compat tracking
- workspace initialization with adapter-specific file layouts
- auth, provider catalogs, and model catalogs
- normalized streaming and transport fallback
- state snapshots for scheduler, memory, skills, and channels
Architecture
| Package | Description |
|---|---|
@clawjs/core |
Shared types, schemas, capability maps, manifests, and snapshot shapes. |
@clawjs/claw |
Runtime adapters, workspace management, conversations, auth, compat, doctor, and state persistence. |
@clawjs/node |
Compatibility wrapper that reexports the primary SDK surface for existing integrations. |
@clawjs/cli |
The official CLI package with the claw and clawjs binaries for adapter-aware runtime, workspace, auth, models, sessions, memory, skills, scheduler, and channels commands. |
Core Concepts
See Terminology for the canonical naming used across ClawJS docs, code, and starter PRDs.
Runtime adapters
A runtime adapter is the boundary between ClawJS and a concrete runtime. It owns probing, locations, workspace contracts, auth, models, conversations, doctor/compat, and optional subsystems.
Workspaces and agents
A workspace is the isolated operational context. An agent is the identity operating inside that workspace. Some scaffolds use the same value for workspaceId and agentId as a convenience default, but those concepts stay separate.
Capability maps
Every runtime status includes a typed capabilityMap. Capabilities are not implicit. They are marked as supported, degraded, or unsupported with a concrete strategy such as cli, gateway, config, native, or bridge.
Stable `.clawjs/` layer
ClawJS keeps a stable internal layer under .clawjs/ even when runtimes disagree on file names or directory structure. Adapter-specific files are managed alongside that stable layer, not mixed into it.
What next
- First Steps for a multi-runtime setup flow.
- Terminology for the canonical product vocabulary.
- Live Demo for a full local-first assistant built with ClawJS.
- Runtime for the adapter contract and capability model.
- API Reference for the public namespaces.