ClawCore 🦐

A core version of OpenClaw — an AI assistant with a soul.

English | 中文 | 日本語 | 한국어 | Español

ClawCore extracts the soul of OpenClaw into a minimal, self-contained personal AI assistant. It keeps the personality system that makes AI feel alive, while stripping away the infrastructure complexity.

🎯 Why ClawCore?

OpenClaw is powerful — but it's also complex. ClawCore asks: what if we keep only the soul?

What's Different from OpenClaw

| 🦐 ClawCore | 🦞 OpenClaw | |------------|------------| | Index-based memory — a simple MEMORY_INDEX.md file as table of contents, no vector DB | Hybrid vector search with embedding models and temporal decay | | Lightweight heartbeat — simple setInterval timer with busy-guard | Full cron system with sub-agents and complex scheduling | | Separate human & AI folders — your files (user/) are isolated and read-only | Shared workspace with broader access | | Task workbench — every task gets its own folder with lifecycle tracking | No explicit task-folder concept | | File safety by design — AI can never modify your originals, only copies | Broader file system access | | Runs on your daily computer — no need for a dedicated machine | Designed for always-on server deployment |

🔒 Safe for Your Personal Machine

Most AI assistants with file access make people nervous — what if it deletes something? ClawCore solves this architecturally:

• user/ is read-only. The AI can read your PDFs, Word docs, and spreadsheets, but it physically cannot write to them.
• Processing happens in workbench/. Need to edit a file? The AI copies it to a task folder first.
• Every action is scoped. The permission model is enforced at the tool level — not by trust, but by code.

This means you can run ClawCore on the same laptop you use every day, without worry. No VM, no dedicated server, no sandbox required.

✨ Features

| Feature | Description | |---------|-------------| | 🧬 Soul System | AI develops its own personality via SOUL.md — not a chatbot, a character | | 🪪 Identity Bootstrap | First-run "awakening" ritual where the AI discovers who it is | | 🧠 Index-based Memory | MEMORY_INDEX.md as table of contents — load specific files on demand | | 🔧 Skill System | Extensible skills via SKILL.md with progressive disclosure — AI can create and evolve skills over time | | 📁 User Vault | Read-only folder for your personal files — AI can never modify originals | | 🛠️ Task Workbench | Per-task folders with _TASK.md lifecycle management and archiving | | 💓 Heartbeat Scan | Periodic autonomous scans — AI creates 🤖-prefixed tasks when it spots something |

🚀 Quick Start

git clone https://github.com/dataelement/ClawCore.git
cd ClawCore
npm install
npm run dev

On first run, ClawCore will:

1. Ask for your LLM API key
2. Start a "bootstrap" conversation to discover its identity
3. Create your workspace at ~/Desktop/ClawCore/

⚙️ Configuration

Edit ~/Desktop/ClawCore/config.json:

{
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o"
  },
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 60
  }
}

Compatible Providers

{
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o"
  }
}

{
  "llm": {
    "baseUrl": "https://api.deepseek.com/v1",
    "apiKey": "sk-...",
    "model": "deepseek-chat"
  }
}

{
  "llm": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-...",
    "model": "qwen-plus"
  }
}

{
  "llm": {
    "baseUrl": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "llama3"
  }
}

📂 Workspace Structure

ClawCore creates a visible workspace on your Desktop — no hidden folders:

~/Desktop/ClawCore/
├── config.json             # LLM and heartbeat settings
├── state.json              # Runtime state (last heartbeat time, etc.)
│
├── soul/                   # 🧬 AI's personality
│   ├── SOUL.md             # Core personality & values
│   ├── IDENTITY.md         # Name, vibe, emoji
│   └── BOOTSTRAP.md        # First-run script (auto-deleted after setup)
│
├── user/                   # 📁 Your files (READ-ONLY for AI)
│   ├── USER_PROFILE.md     # Your profile
│   └── ...                 # PDFs, Word docs, spreadsheets, etc.
│
├── memory/                 # 🧠 AI's memory
│   ├── MEMORY_INDEX.md     # Table of contents
│   ├── preferences.md      # Evergreen knowledge
│   └── 2026-02-23.md       # Daily journal entries
│
├── workbench/              # 🛠️ Task workspace
│   ├── 2026-02-23_报告分析/
│   │   ├── _TASK.md        # Task metadata & status
│   │   └── output.md       # Work product
│   ├── 🤖_2026-02-23_资料整理/  # Agent-initiated task
│   └── _archive/           # Archived completed tasks
│
└── skills/                 # 🔧 Skill definitions (AI can create & modify)
    ├── SKILL_LOG.md        # Changelog of all skill changes
    └── my-skill/
        └── SKILL.md

Permission Model

| Directory | AI Permissions | Purpose | |-----------|---------------|---------| | soul/ | Read + Write | AI manages its own personality | | user/ | Read-only | Your files — AI copies to workbench before editing | | memory/ | Read + Write | AI's persistent memory | | workbench/ | Read + Write | Per-task work area | | skills/ | Read + Write | AI can create and evolve skills, logged to SKILL_LOG.md |

🛡️ Security Model

ClawCore enforces safety at the code level, not by trusting the AI to behave:

File Access — All file operations go through assertInsideWorkspace(), which resolves symlinks before checking paths. This prevents a classic attack: if someone creates a shortcut (symlink) inside the workspace that points to /Users/you/.ssh/, the AI would see it as "inside the workspace" — but ClawCore follows the link first and catches that it actually points outside.

Shell Commands — The exec tool uses three layers of protection:

| Layer | What it does | Example | |-------|-------------|---------| | ✅ Whitelist | Safe commands run immediately | ls, cat, grep, wc, open | | 🚫 Blocklist | Dangerous commands are blocked outright | rm, curl, wget, sudo, ssh, chmod | | ⚠️ Confirmation | Unknown commands prompt you to approve | python3 script.py → "Allow? (y/N)" |

🔧 Adding Skills

Create a folder in ~/Desktop/ClawCore/skills/ with a SKILL.md:

---
name: my-skill
description: "When to use: user asks about X. NOT for: Y."
---

# My Skill

Detailed instructions for the AI...

The AI uses progressive disclosure — it sees skill names and descriptions in its prompt, and loads the full SKILL.md content only when needed.

💓 Heartbeat

ClawCore includes a lightweight heartbeat mechanism inspired by OpenClaw:

• Default interval: 60 minutes
• What it does: Scans user/ and workbench/ folders for changes
• Smart scheduling: Won't interrupt active conversations — defers until idle
• Agent tasks: Creates workbench folders prefixed with 🤖 for self-initiated work

📄 Document Support

ClawCore can read various file formats in the user/ folder:

| Format | Library | |--------|---------| | PDF | pdf-parse | | Word (.docx) | mammoth | | Excel (.xlsx) | xlsx | | Markdown, JSON, CSV, TXT | Native |

🏗️ Architecture

CLI (index.ts)
  └── Agent (agent.ts)
        ├── System Prompt Builder ← Soul + Identity + Memory Index + Skills
        ├── LLM Provider (OpenAI-compatible)
        ├── Tool Executor (15 tools with permission enforcement)
        └── Heartbeat Runner (setInterval with busy guard)

Built-in Tools

| Tool | Description | |------|-------------| | read_file | Read files (with document parsing) | | write_file | Write files (memory/ and workbench/ only) | | list_dir | List directory contents | | copy_to_workbench | Copy from user/ to a task folder | | create_task | Create a new task folder | | update_task_status | Update task status | | archive_task | Move task to archive | | memory_read / memory_write / memory_index | Memory operations | | read_skill | Load full skill instructions | | create_skill / update_skill | Create or modify skills (auto-logged to SKILL_LOG.md) | | update_soul / update_identity | Modify personality files | | complete_bootstrap | Finish first-run setup | | exec | Run shell commands |

👥 Contributors

🤝 Acknowledgments

ClawCore is inspired by OpenClaw and its vision of AI assistants with genuine personality. We extracted the soul and made it core.

📜 License

MIT