ClawDNA

Version control and sync for your AI agent's identity.

ClawDNA is an open-source CLI that treats your AI agent's personality, skills, config, and memory as a portable, versionable artifact. Snapshot your agent's identity, sync it across machines, and deploy fleet-wide updates -- all without risking the personality you spent weeks building.

The CLI and self-hosted Git sync are fully open source and free forever. ClawDNA Cloud is an optional hosted service for teams that want managed sync, memory distillation, and fleet management without running their own infrastructure.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     clawdna CLI (OSS)                       │
│  snapshot · restore · push · pull · diff · clone · fleet    │
└───────────────────────┬─────────────────────────────────────┘
                        │  speaks to one of:
        ┌───────────────┼───────────────────┐
        │               │                   │
        v               v                   v
  ┌──────────┐   ┌─────────────┐   ┌──────────────────┐
  │ Local FS │   │ Git Remote  │   │ ClawDNA Cloud    │
  │ (no hub) │   │ (self-host) │   │ (hosted, paid)   │
  └──────────┘   └─────────────┘   └──────────────────┘

CLI -- TypeScript + Node.js, published to npm. Runs on your machine, manages identity files, communicates with the hub.

Git Hub -- Any standard Git remote (GitHub, GitLab, Gitea). Free. The CLI handles all Git operations internally via isomorphic-git.

ClawDNA Cloud -- Cloudflare Workers API + R2 storage. Hosted sync hub with memory distillation, fleet management, and team features.

Quick Start

Prerequisites

• Node.js >= 22
• pnpm (recommended) or npm

Install

npm install -g clawdna

First Run

# 1. Initialize ClawDNA in your agent workspace
clawdna init

# 2. Create your first identity snapshot
clawdna snapshot --name "initial-setup"

# 3. Push your identity to the configured hub
clawdna push

The init wizard detects your agent workspace and walks you through hub configuration (Cloud, Git remote, or local-only).

Local Development

git clone https://github.com/triplehelix/clawdna.git
cd clawdna
pnpm install
pnpm build

CLI Commands

Core

| Command | Description | |---------|-------------| | clawdna init | Interactive setup wizard -- detects workspace, configures hub | | clawdna snapshot [--name <name>] | Create a timestamped .dna identity bundle | | clawdna restore <id> [--dry-run] | Restore identity from a snapshot, with optional dry-run preview | | clawdna diff [a] [b] | Show changes between local identity and hub, or between two snapshots | | clawdna log | Display identity change history with timestamps and environment attribution |

Sync

| Command | Description | |---------|-------------| | clawdna push [--message] | Push current identity to the configured hub | | clawdna pull [--dry-run] | Pull latest identity from hub, show diff, apply | | clawdna clone <src> <dest> | Fork an agent -- create a new environment inheriting from source | | clawdna fleet push [--filter <tag>] | Push identity update to all registered environments simultaneously |

Advanced

| Command | Description | |---------|-------------| | clawdna env add\|list\|switch | Manage environment profiles (per-machine overrides, tokens as env var refs) | | clawdna memory distill [--dry-run] | Promote key decisions and preferences from session memory to core identity | | clawdna daemon start\|stop\|status | Background sync daemon -- watches for changes, auto-pushes on debounce | | clawdna doctor | Diagnose sync issues, verify file integrity, check permissions | | clawdna upgrade | Safe wrapper around agent runtime upgrades -- snapshots before, verifies after |

How It Works

Identity Files

ClawDNA manages the files that define your agent's identity:

• SOUL.md -- personality, values, behavioral rules
• AGENTS.md -- workspace conventions and operating rules
• IDENTITY.md -- how the agent presents itself
• MEMORY.md -- accumulated knowledge about the user
• TOOLS.md -- installed skills and tool configurations
• USER.md -- user-specific context and preferences

These files are what make your agent yours. ClawDNA versions and syncs them so they never drift or get lost.

The .dna Bundle

A snapshot produces a .dna bundle: a compressed tarball containing all identity files plus a manifest with metadata (agent runtime version, Node version, timestamp, environment ID). Bundles are the unit of sync -- they get pushed to and pulled from the hub.

Push / Pull Sync

The sync protocol tracks state per environment-hub pair. Each side maintains a content hash (SHA-256 of all identity files). On push, ClawDNA computes the local hash, compares it to the hub, and uploads a sanitized bundle if there are changes. On pull, it downloads the latest bundle, computes a diff, and applies changes after user confirmation. Conflicts (both sides changed) are detected and require resolution before proceeding.

Secrets Sanitization

Every push, export, and distillation operation passes through a secrets sanitizer before any data leaves the machine. The sanitizer detects API key patterns, bot tokens, JWTs, and private key headers. If a secret is found in any identity file, the operation is aborted with a clear error. This is a hard gate -- it cannot be bypassed without an explicit --force-unsafe flag.

Cloud Hub

ClawDNA Cloud is an optional hosted service -- the CLI and self-hosted Git sync are fully open source. Cloud eliminates Git setup friction and adds managed features like memory distillation, fleet management, and team workspaces.

You can use ClawDNA entirely for free with local snapshots or any Git remote you control. The Cloud tiers are for teams and power users who want a managed experience:

Cloud Pricing

| Tier | Price | Environments | What You Get | |------|-------|--------------|--------------| | OSS | Free | Unlimited | CLI, local snapshots, self-hosted Git sync | | Pro | $9/mo | 5 | Hosted cloud hub, memory distillation, daemon | | Fleet | $29/mo | Unlimited | Fleet push, clone/fork, cross-platform export | | Team | $99/mo | Unlimited | Shared workspace, RBAC, client isolation, API access |

Development

Setup

pnpm install
pnpm build

Testing

pnpm test:unit        # Unit tests
pnpm typecheck        # TypeScript type checking
pnpm lint             # ESLint

Cloud Worker

cd packages/cloud
pnpm dev              # Start local Cloudflare Workers dev server

Monorepo Structure

The project uses pnpm workspaces with Turborepo for build orchestration.

| Package | Path | Description | |---------|------|-------------| | clawdna | packages/cli | CLI tool -- published to npm | | @clawdna/cloud | packages/cloud | Cloudflare Workers sync API |

Project Structure

clawdna/
├── packages/
│   ├── cli/
│   │   ├── src/
│   │   │   ├── commands/        # One file per CLI command (14 total)
│   │   │   ├── core/            # Domain logic (identity, memory, sync, crypto)
│   │   │   ├── adapters/        # I/O boundaries (filesystem, git, hub, llm)
│   │   │   ├── config/          # Config schemas, env profiles, syncignore
│   │   │   ├── ui/              # Terminal output (prompts, progress, chalk)
│   │   │   └── index.ts         # CLI entry point
│   │   └── tests/
│   │       ├── unit/
│   │       ├── integration/
│   │       └── fixtures/
│   │
│   └── cloud/
│       └── src/
│           ├── routes/          # API endpoints (bundles, envs, fleet, memory, auth)
│           ├── middleware/       # Auth (JWT) and rate limiting
│           ├── storage/         # R2 and KV adapters
│           └── worker.ts        # Hono app entry point
│
├── schema/                      # claw.dna.yaml JSON Schema (v1)
├── scripts/                     # Release and integration test scripts
├── docs/                        # Guides and documentation
├── turbo.json                   # Turborepo config
├── pnpm-workspace.yaml
└── tsconfig.base.json

Security

Secrets never leave the machine. Bot tokens, API keys, OAuth credentials, session history, and private keys are excluded from every sync operation. The secrets sanitizer runs as a hard gate before any network call.

AES-256-GCM encryption at rest. Identity bundles stored in ClawDNA Cloud are encrypted client-side before upload. Key derivation uses PBKDF2 with HMAC-SHA256 (600,000 iterations). The encryption key never touches ClawDNA servers -- bundles are opaque blobs from the server's perspective.

HMAC-SHA256 webhook signatures. Webhook payloads are signed with a user-configured secret and verified using timing-safe comparison to prevent replay attacks.

Strict file permissions. The CLI enforces 600 on config files and 700 on snapshot directories. clawdna doctor warns if permissions are too open.

License

MIT