ClawCode

Turn Claude Code into a persistent agent — memory, personality, voice, messaging, and more.

Quick Setup · Why · Features · Skills · Going further · Troubleshooting · Issues

---

What this is

ClawCode is a plugin for Claude Code. Install it and Claude Code remembers you between sessions: your name, the agent's own name and personality, the notes you and the agent wrote together last week. It adds memory with bilingual recall (Spanish ↔ English), messaging through WhatsApp, Telegram, Discord, iMessage and Slack, a browser chat, nightly memory consolidation, and a background service for 24/7 runs. Everything lives inside Claude Code's plugin system.

The agent remembers your dog's name, warns about allergies before suggesting food, and answers in 1 to 2 lines instead of paragraphs.

Why it exists

Claude Code is stateless by default. Open a new session and the agent starts from zero: no memory of what you were working on yesterday, no name, no feel for who it is. Good agents should not do that. That gap is what ClawCode fills.

There are roughly two ways to build persistence on top of Claude. One is a harness: a separate runtime that wraps Claude's API with its own session, memory, and tool layer. OpenClaw is one example. Harnesses run on Claude's API directly; as of April 2026 they can no longer draw from a Claude subscription, so users need to pay for API usage separately.

ClawCode takes the other route. It extends Claude Code from inside as a plugin, so there's no separate runtime and no separate billing. A ClawCode user is just a Claude Code user with an extra layer on top. ClawCode inherits what Claude Code already does well (its harness, tool system, skills, hooks, MCP plumbing) and adds only what a persistent agent needs.

Coming from OpenClaw? /agent:import brings your agent's personality, memory, skills, and crons across.

Highlights

• 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.
• Messaging channels — WhatsApp, Telegram, Discord, iMessage, Slack via MCP plugins. Same agent, every channel, no conflicts.
• 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).
• Slash commands everywhere — /status, /help, /whoami, /new, /compact work from CLI, WhatsApp, Telegram, Discord — same commands, formatting adapts per platform.
• Smart import from OpenClaw — 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.
• Channel scope — opt-in per-channel privacy layer. When you pair WhatsApp, you can choose: agent acts as owner (sees all chats), guest (sees nothing channel-derived), or auto (owner-only ceiling). Default is off — zero behavior change for users who don't opt in.
• Execution gate — opt-in guardrail (companion to channel scope). When the current Claude Code turn was triggered by a non-owner message in a paired group chat, blocks destructive tools (Bash, Write, Edit, Task, and more) per a denylist/allowlist policy. Always-on protected paths fire even with the gate off — agent cannot self-modify hooks, agent-config, SSH/credential dirs, shell init, or persistence mechanisms. Default off.
• Doctor — 9+ health checks (config, identity, memory, SQLite, QMD, bootstrap, HTTP, messaging, dreaming, scope). --fix auto-repairs safe issues.
• Terse by design — the agent acts, doesn't narrate. Confirmations in 1-2 lines, no preambles, no recaps.

Prerequisites

• Node.js v18+
• Windows: Claude Code must be run from inside WSL2 (not native PowerShell / cmd).

Quick Setup

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
claude

2. Install the plugin.

Inside Claude Code, add Anthropic's official community marketplace:

/plugin marketplace add anthropics/claude-plugins-community

Then install the plugin:

/plugin install clawcode@claude-community

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

Bleeding-edge alternative. The community marketplace syncs nightly from Anthropic's review pipeline, so brand-new fixes can take up to ~24h to land. If you want the absolute latest commit, install from this repo's marketplace instead — same plugin, different identifier. Run them one at a time:

/plugin marketplace add crisandrews/ClawCode

/plugin install agent@clawcode

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.

How it works

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

Features

Memory

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

Dreaming

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

Voice

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

WebChat

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

Every browser tab gets its own sessionId (UUID v4, persisted in localStorage) that partitions per-session chat history and live agent replies — two browsers sharing the same http.token cannot read each other's conversations. sessionId is a privacy partition; http.token remains the auth boundary.

Full details: docs/webchat.md · docs/http-bridge.md

Messaging channels

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

Channel scope

When the agent indexes messaging-channel logs into its memory (WhatsApp via claude-whatsapp), it can apply per-channel scope filtering so the agent only sees what the operator is allowed to see — mirroring the upstream plugin's own access governance.

Default is off. Users who don't opt in see no behavior change.

To opt in:

/agent:scope wizard

The wizard walks through: which channel, mode (shadow = log only, enforce = filter), and identity (owner = sees all, guest = sees nothing channel-derived, auto = owner-only ceiling). owner mode requires an out-of-band trust file you create via Bash — the agent cannot grant itself owner privileges.

Important caveats:

• MCP scope is not a filesystem sandbox. Native Read, Grep, or direct SQLite over channel log files always bypass the scope filter by design. Hard isolation lives at the OS/filesystem layer.
• The filter covers MCP tools (memory_search, memory_get, memory_context, dream, voice_transcribe, chat_inbox_read).
• A separate per-chat indexer reads upstream messages.db read-only and stores chat-id columns locally so per-chat allowlists work.
• Trust files are per-workspace. As of 1.7.0 the trust file lives under `~/.clau