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

OpenAI

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

DeepSeek

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

Alibaba Qwen (通义千问)

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

Local Ollama

{
  "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