Persistent agents for Claude Code — memory, dreaming, and personality.
Quick Setup · Features · Skills · Going further · Troubleshooting · Issues
Claude Code is stateless by default. Every session starts from zero — no memory of who you are, what you talked about, or how the agent should behave.
ClawCode turns Claude Code into a stateful autonomous agent. It gives Claude a persistent identity, searchable memory with bilingual recall, nightly dreaming that consolidates important memories, and a terse conversational style. The agent remembers your dog's name, warns you about allergies before suggesting food, and responds in 1–2 lines instead of paragraphs.
- Persistent identity — name, personality, emoji. The agent wakes up as itself on every session via lifecycle hooks that inject SOUL.md + IDENTITY.md at startup.
- Active memory — bilingual recall (ES ↔ EN) at the start of every turn. Ask "cómo se llama mi perro?" and it finds "Cookie" from English notes. Warns about allergies before suggesting food.
- Lifecycle hooks — SessionStart injects identity + auto-creates crons. PreCompact flushes memory before context compression. Stop writes session summaries. SessionEnd tracks dream events.
- Dreaming — nightly 3-phase consolidation (Light → REM → Deep) with 6 weighted signals. Promotes important memories to long-term storage.
- Language adaptation — detects the user's language and responds in kind. Switch mid-conversation and the agent switches too. Commands, status cards, and errors all adapt.
- Voice — TTS via sag, ElevenLabs, OpenAI, macOS
say. STT via local Whisper or OpenAI API. - WebChat — browser chat UI with SSE real-time delivery. Conversation logs in JSONL + Markdown (same format as WhatsApp).
- Messaging channels — WhatsApp, Telegram, Discord, iMessage, Slack via MCP plugins. No conflicts.
- Slash commands everywhere —
/status,/help,/whoami,/new,/compactwork from CLI, WhatsApp, Telegram, Discord — same commands, formatting adapts per platform. - Smart import — 3-tier classifier (GREEN/YELLOW/RED) for skills and crons. Step-by-step wizard with clickable options. Skipped items go to a backlog with recovery notes.
- Community skills — install from GitHub with
owner/repo@branch#subdir. OS + dependency validation. - Always-on — launchd / systemd service. Enables dreaming + heartbeat 24/7.
- Webhooks — external systems (Cloudflare Workers, GitHub Actions, CI/CD, IoT) can POST events to the agent via HTTP. The agent processes them like any other message.
- Doctor — 9 health checks (config, identity, memory, SQLite, QMD, bootstrap, HTTP, messaging, dreaming).
--fixauto-repairs safe issues. - Terse by design — the agent acts, doesn't narrate. Confirmations in 1-2 lines, no preambles, no recaps.
- Node.js v18+
1. Create a folder for your agent.
Each agent lives in its own folder. Create one and open Claude Code there:
mkdir ~/my-agent && cd ~/my-agent
claude2. Install the plugin.
Inside Claude Code, add the marketplace:
/plugin marketplace add crisandrews/ClawCode
Then install the plugin:
/plugin install agent@clawcode
When prompted for scope, select "Install for you, in this repo only (local scope)" — this keeps the agent isolated to this folder.
Then reload plugins so the skills become available:
/reload-plugins
3. Create your agent:
/agent:create
This starts the bootstrap ritual — a casual conversation where the agent discovers its name, personality, and emoji. You can also import an existing agent instead:
/agent:import
4. Reload to apply the personality:
/mcp
The agent now wakes up with its identity on every session.
ClawCode injects personality and behavior at four points in the session lifecycle:
| Hook | When | What happens |
|---|---|---|
| SessionStart | Session opens | Reads SOUL.md + IDENTITY.md + USER.md and injects them as context. Checks if heartbeat + dreaming crons exist — creates them if missing. |
| PreCompact | Context getting full | Reminds agent to save important facts to memory/YYYY-MM-DD.md before compression erases them. |
| Stop | Session closing | Reminds agent to write a session summary (what was discussed, decisions, open items). |
| SessionEnd | Session closed | Logs a session.end event for the dreaming system. |
This means:
- Every session starts with personality — the agent never says "I'm Claude." It knows its name, vibe, and your info.
- Memory survives compaction — PreCompact flushes facts before they're lost.
- Sessions are summarized — the next session knows what happened in the last one.
- Dreaming tracks sessions — knows when you were active, when you paused.
The agent also detects your language from each message and responds in kind. Switch from Spanish to English mid-conversation — the agent switches too. Status cards, error messages, and commands all adapt.
Full details: docs/hooks.md
The agent writes to memory/YYYY-MM-DD.md during sessions and searches it automatically at the start of every turn — no need to say "search memory." Bilingual (Spanish ↔ English, 40+ synonym pairs), date-aware ("hoy" resolves to today's date), and safety-critical (warns about allergies before suggesting food). Trivial messages (greetings, "ok", slash commands) skip the search — no wasted context.
Two backends: builtin (SQLite + FTS5, works out of the box) and QMD (local embeddings for semantic search — install with bun install -g qmd).
Full details: docs/memory.md · docs/memory-context.md · docs/qmd.md
Nightly cron (3 AM) runs 3-phase memory consolidation:
- Light — ingests recall signals from the day, deduplicates candidates
- REM — extracts recurring themes, identifies multi-day patterns, writes reflections to
DREAMS.md - Deep — ranks candidates with 6 weighted signals (relevance 0.30, frequency 0.24, query diversity 0.15, recency 0.15, consolidation 0.10, conceptual richness 0.06) and promotes winners to
memory/MEMORY.md
Run manually: dream(action='run') or preview with dream(action='dry-run').
Full details: docs/dreaming.md
TTS via sag, ElevenLabs, OpenAI, or macOS say. STT via local Whisper or OpenAI Whisper API. The agent auto-selects the best available backend. Enable with agent_config(action='set', key='voice.enabled', value='true').
Full details: docs/voice.md
Browser-based chat UI with real-time SSE delivery. Enable the HTTP bridge, open http://localhost:18790. Dark/light mode, conversation logging in JSONL + Markdown (same format as WhatsApp plugin).
agent_config(action='set', key='http.enabled', value='true')
/mcp
Full details: docs/webchat.md · docs/http-bridge.md
Reach your agent from WhatsApp, Telegram, Discord, iMessage, or Slack. Each messaging plugin is an independent MCP server — no conflicts with ClawCode.
/agent:messaging
Slash commands work from any channel — /status, /help, /whoami, /new, /compact all respond whether the user is in the CLI terminal or chatting via WhatsApp. Formatting adapts automatically (*bold* for WhatsApp, **bold** for Telegram, standard markdown for CLI).
Full details: docs/channels.md
/agent:import brings an existing agent into Claude Code with a step-by-step wizard (clickable options, one question at a time):
- Bootstrap files — copies SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md
- Memory — imports MEMORY.md + recent daily logs (credentials are never copied)
- Memory backend — asks: QMD (semantic search) or builtin (SQLite + FTS5)?
- Skills — classifies each skill as GREEN (portable), YELLOW (needs adaptation), or RED (incompatible). You choose: all, specific ones, or skip.
- Crons — same 3-tier classification for scheduled tasks. Prompts are adapted for Claude Code tools.
- Messaging — offers WhatsApp, Telegram, Discord, iMessage setup.
Files are copied clean — no annotations, no comments. Adaptation details go to IMPORT_BACKLOG.md so the user can revisit skipped items later. The import event is logged to memory so the agent remembers what was imported.
External systems can send events to the agent via POST /v1/webhook (requires HTTP bridge enabled). The agent queues them and processes on the next turn.
Use cases:
- Email catch-all — Cloudflare Email Worker forwards every incoming email to the agent in real-time
- Gmail push — Gmail notifies the agent via Pub/Sub when new emails arrive
- CI/CD — GitHub Actions sends build results → agent summarizes and notifies via WhatsApp
- Scheduled tasks — Cloudflare Workers trigger agent actions on a cron schedule
- Monitoring — uptime checker sends alert → agent investigates and reports
- IoT — sensor data arrives → agent logs to memory and acts on thresholds
curl -X POST http://localhost:18790/v1/webhook \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{"event": "deploy", "status": "success", "repo": "my-app"}'Security: when the bridge is exposed to the network (host: "0.0.0.0"), a token is required — the bridge refuses to start without one.
Queue holds up to 1000 events. Drain with GET /v1/webhooks or the chat_inbox_read MCP tool.
Full details: docs/http-bridge.md
/agent:doctor runs 11 health checks: config validity, identity files, memory directory, SQLite integrity, QMD availability, bootstrap state, HTTP bridge, messaging plugins, dreaming, cron registry, jq availability. Returns a ✅/--fix to auto-repair safe issues (create missing memory/, reindex SQLite, remove stale BOOTSTRAP.md).
Full details: docs/doctor.md
Reminders (heartbeat, dreaming, imports, and ad-hoc "remind me in 2h") survive session closes. ClawCode maintains a registry at memory/crons.json and reconciles it against the live harness on every SessionStart: anything missing gets recreated, anything live-but-unknown gets adopted. PostToolUse captures ad-hoc CronCreate/CronDelete automatically — you don't need a special command for "remind me".
Manage reminders through /agent:crons (aliases /agent:reminders, list reminders, recordatorios):
/agent:crons list # ✅⚠️⏸ status table
/agent:crons add "0 9 * * *" "email" # add a reminder
/agent:crons delete 3 # remove with AskUserQuestion confirm
/agent:crons pause heartbeat-default # pause without deleting
/agent:crons reconcile # force sync
/agent:crons import # bring OpenClaw crons into the registry
Full details: docs/crons.md
| Skill | Description |
|---|---|
/agent:create |
Create a new agent with bootstrap ritual |
/agent:import [id] |
Import an existing agent (personality + memory + skills + crons) |
/agent:doctor [--fix] |
Diagnose agent health. --fix applies safe auto-repairs |
/agent:settings |
View/modify agent config (guided) |
/agent:skill install|list|remove |
Install community skills from GitHub |
/agent:channels |
Messaging channel status and launch command |
/agent:service install|status|uninstall|logs |
Always-on background service |
/agent:voice status|setup |
TTS / STT backends |
/agent:messaging |
Set up WhatsApp, Telegram, Discord, iMessage, Slack |
/agent:crons / /agent:reminders |
Manage reminders: list, add, delete, pause, reconcile, import |
/agent:heartbeat |
Memory consolidation and periodic checks |
/agent:status |
Agent status dashboard |
/agent:usage |
Resource usage |
/agent:new |
Save session and prepare for /clear |
/agent:compact |
Save context before compression |
/whoami |
Sender info and agent identity |
/help |
List all available commands (dynamic) |
Install skills from GitHub:
/agent:skill install alice/pomodoro
/agent:skill install alice/skills@main#weather
/agent:skill list
/agent:skill remove pomodoro
Full details: docs/skill-manager.md
Run the agent as a background service (launchd on macOS, systemd on Linux):
/agent:service install
/agent:service status
/agent:service logs
Full details: docs/service.md
Optional companion: docs/watchdog.md — opt-in external health probe + auto-restart for always-on services.
All settings in agent-config.json. Edit directly or use agent_config:
agent_config(action='get')
agent_config(action='set', key='memory.backend', value='qmd')
Non-critical settings apply live. Critical settings need /mcp — the agent tells you which.
Full details: docs/config-reload.md
Update to the latest version:
/plugin marketplace update crisandrews/ClawCode
/plugin update agent@clawcode
/reload-plugins
If /plugin update says "already at latest version" but you know there's a new one, use the manual method: type /plugin, find agent@clawcode in the list, press Enter, and select Update.
Your personality, memory, skills, and config are preserved — only the plugin code updates. No data loss.
Uninstall:
/plugin uninstall agent@clawcode
Your agent files (SOUL.md, IDENTITY.md, memory/, skills/) stay in the folder — they're yours. Only the plugin code is removed.
Clear cache (if reinstall fails or behaves unexpectedly):
Close Claude, then in terminal:
rm -rf ~/.claude/plugins/cache/clawcodeReopen Claude and install again.
Each agent is its own folder with its own personality, memory, and config:
~/agent-work/ ← Agent #1
~/agent-personal/ ← Agent #2
Install the plugin in each folder with local scope. Switch: cd ~/other-agent && claude.
Every agent has these files in its root. They're injected as context at session start via the SessionStart hook.
| File | What it defines |
|---|---|
SOUL.md |
Core truths, boundaries, philosophy — the agent's deepest identity |
IDENTITY.md |
Name, emoji, creature type, vibe, birth date |
USER.md |
Your info: name, timezone, language, preferences |
AGENTS.md |
Operational rules, safety boundaries, local skill triggers |
TOOLS.md |
Platform-specific formatting (WhatsApp uses *bold*, Telegram uses **bold**) |
HEARTBEAT.md |
What to check every 30 min (review daily logs, consolidate memory) |
BOOTSTRAP.md |
First-run ritual (deleted after onboarding) |
The agent never says "I'm Claude" — it uses its name from IDENTITY.md. Even when asked directly "are you Claude?", it answers: "I'm [name] — built on Claude, but with my own memory, personality, and name."
~/my-agent/
├── SOUL.md, IDENTITY.md, USER.md # Agent personality
├── AGENTS.md, TOOLS.md, HEARTBEAT.md # Behavioral rules
├── agent-config.json # Settings
├── memory/
│ ├── MEMORY.md # Long-term curated memory
│ ├── YYYY-MM-DD.md # Daily logs (append-only)
│ ├── .memory.sqlite # Search index (auto-generated)
│ └── .dreams/ # Dream tracking data
├── .webchat/logs/conversations/ # WebChat logs (JSONL + MD)
├── skills/ # Installed + imported skills
└── IMPORT_BACKLOG.md # Skipped import items (if any)
Conversation logs are stored in two formats per channel:
- JSONL — one JSON object per line, ideal for programmatic access and memory indexing
- Markdown — human-readable chat transcript
Run /agent:doctor first — it checks everything in one shot. Add --fix to auto-repair safe issues.
- "Failed to reconnect to plugin:agent:clawcode" — Dependencies didn't install. Check Node.js v18+ (
node --version). Then try manually: close Claude, runcd ~/.claude/plugins/cache/clawcode/agent/*/ && npm install, reopen Claude. - Agent has no personality — Run
/mcpto reload. The SessionStart hook injects identity from SOUL.md + IDENTITY.md. - Memory search returns nothing — Index builds on first search. For QMD:
agent_config(action='set', key='memory.backend', value='qmd'). - Agent doesn't remember things — The active memory reflex uses bilingual synonyms but not everything. Try different keywords.
- Config change didn't take effect — Non-critical settings apply live. Critical ones need
/mcp. The agent tells you which. - Messaging channels — Run
/agent:channels statusfor installed/authenticated/active status. - Crons don't persist across restarts — Known limitation:
durable: trueis currently session-only in Claude Code. Crons are recreated automatically at each session start via the SessionStart hook (default heartbeat + dreaming). For 24/7, use/agent:service install.
- Crons only run while Claude Code is open — for 24/7, use
/agent:service install. - WebChat + WhatsApp logs are indexable via
memory.extraPathsin config. - Each agent folder is fully self-contained — portable, backupable, deletable.
Per-feature documentation in docs/.
ClawCode is an independent, open-source project. Claude is a trademark of Anthropic, PBC. ClawCode is not affiliated with or endorsed by Anthropic.