{"id":51223028,"url":"https://github.com/crisandrews/ClawCode","last_synced_at":"2026-07-09T07:00:29.359Z","repository":{"id":350988927,"uuid":"1206364309","full_name":"crisandrews/ClawCode","owner":"crisandrews","description":"Persistent agents for Claude Code as a plugin, not a harness. Memory, personality, messaging across WhatsApp, Telegram, and Discord, plus a service mode for 24/7 runs. Imports from OpenClaw.","archived":false,"fork":false,"pushed_at":"2026-07-03T08:56:25.000Z","size":1166,"stargazers_count":61,"open_issues_count":11,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-03T10:29:16.346Z","etag":null,"topics":["ai-agent","autonomous-agent","claude","claude-code","claude-code-plugin","dreaming","mcp","memory","openclaw","openclaw-compatible","personality","stt","tts","voice","webhooks","whatsapp"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crisandrews.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-09T20:57:18.000Z","updated_at":"2026-07-03T08:56:39.000Z","dependencies_parsed_at":"2026-04-14T07:00:29.948Z","dependency_job_id":"6170a6a6-6553-492d-b7e8-966445edeb1c","html_url":"https://github.com/crisandrews/ClawCode","commit_stats":null,"previous_names":["crisandrews/clawcode"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/crisandrews/ClawCode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisandrews%2FClawCode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisandrews%2FClawCode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisandrews%2FClawCode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisandrews%2FClawCode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crisandrews","download_url":"https://codeload.github.com/crisandrews/ClawCode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisandrews%2FClawCode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35290235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","autonomous-agent","claude","claude-code","claude-code-plugin","dreaming","mcp","memory","openclaw","openclaw-compatible","personality","stt","tts","voice","webhooks","whatsapp"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-09T07:00:29.352Z","avatar_url":"https://github.com/crisandrews.png","language":"TypeScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eClawCode\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/clawcode.png\" alt=\"ClawCode mascot\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTurn Claude Code into a persistent agent — memory, personality, voice, messaging, and more.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/crisandrews/ClawCode/releases\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/crisandrews/ClawCode/main/.github/release.json\u0026style=for-the-badge\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/crisandrews/ClawCode/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/crisandrews/ClawCode/main/.github/stars-count.json\u0026style=for-the-badge\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/crisandrews/ClawCode/main/.github/clone-count.json\u0026style=for-the-badge\" alt=\"Clones\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%E2%89%A5%2018-blue?style=for-the-badge\u0026logo=node.js\u0026logoColor=white\" alt=\"Node ≥ 18\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20%28WSL2%29-blue?style=for-the-badge\" alt=\"Platform\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-setup\"\u003eQuick Setup\u003c/a\u003e ·\n  \u003ca href=\"#why-it-exists\"\u003eWhy\u003c/a\u003e ·\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e ·\n  \u003ca href=\"#skills\"\u003eSkills\u003c/a\u003e ·\n  \u003ca href=\"#going-further\"\u003eGoing further\u003c/a\u003e ·\n  \u003ca href=\"#troubleshooting\"\u003eTroubleshooting\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/crisandrews/ClawCode/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/anthropics/claude-plugins-community\"\u003e\u003cimg src=\"https://img.shields.io/badge/Listed%20on-Anthropic's%20claude--plugins--community-FF6B35?style=for-the-badge\" alt=\"Listed on Anthropic's claude-plugins-community\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## [What this is](#what-this-is)\n\nClawCode 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.\n\nThe agent remembers your dog's name, warns about allergies before suggesting food, and answers in 1 to 2 lines instead of paragraphs.\n\n## [Why it exists](#why-it-exists)\n\nClaude 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.\n\nThere 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.\n\nClawCode 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.\n\nComing from OpenClaw? `/agent:import` brings your agent's personality, memory, skills, and crons across.\n\n## [Highlights](#highlights)\n\n- **[Persistent identity](#how-it-works)** — name, personality, emoji. The agent wakes up as itself on every session via lifecycle hooks that inject SOUL.md + IDENTITY.md at startup.\n- **[Messaging channels](#messaging-channels)** — WhatsApp, Telegram, Discord, iMessage, Slack via MCP plugins. Same agent, every channel, no conflicts.\n- **[Active memory](#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.\n- **[Lifecycle hooks](#hooks)** — SessionStart injects identity + auto-creates crons. PreCompact flushes memory before context compression. Stop writes session summaries. SessionEnd tracks dream events.\n- **[Dreaming](#dreaming)** — nightly 3-phase consolidation (Light → REM → Deep) with 6 weighted signals. Promotes important memories to long-term storage.\n- **[Language adaptation](#how-it-works)** — detects the user's language and responds in kind. Switch mid-conversation and the agent switches too. Commands, status cards, and errors all adapt.\n- **[Voice](#voice)** — TTS via sag, ElevenLabs, OpenAI, macOS `say`. STT via local Whisper or OpenAI API.\n- **[WebChat](#webchat)** — browser chat UI with SSE real-time delivery. Conversation logs in JSONL + Markdown (same format as WhatsApp).\n- **[Slash commands everywhere](#messaging-channels)** — `/status`, `/help`, `/whoami`, `/new`, `/compact` work from CLI, WhatsApp, Telegram, Discord — same commands, formatting adapts per platform.\n- **[Smart import from OpenClaw](#importing-agents)** — 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.\n- **[Community skills](#community-skills)** — install from GitHub with `owner/repo@branch#subdir`. OS + dependency validation.\n- **[Always-on](#always-on-service)** — launchd / systemd service. Enables dreaming + heartbeat 24/7.\n- **[Webhooks](#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.\n- **[Channel scope](#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.\n- **[Execution gate](#channel-scope)** — 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.\n- **[Doctor](#diagnostics)** — 9+ health checks (config, identity, memory, SQLite, QMD, bootstrap, HTTP, messaging, dreaming, scope). `--fix` auto-repairs safe issues.\n- **[Terse by design](#how-it-works)** — the agent acts, doesn't narrate. Confirmations in 1-2 lines, no preambles, no recaps.\n\n## [Prerequisites](#prerequisites)\n\n- [Node.js](https://nodejs.org/) v18+\n- Windows: Claude Code must be run from inside [WSL2](docs/wsl2.md) (not native PowerShell / cmd).\n\n## [Quick Setup](#quick-setup)\n\n**1. Create a folder for your agent.**\n\nEach agent lives in its own folder. Create one and open Claude Code there:\n\n```sh\nmkdir ~/my-agent \u0026\u0026 cd ~/my-agent\nclaude\n```\n\n**2. Install the plugin.**\n\nInside Claude Code, add Anthropic's official community marketplace:\n\n```\n/plugin marketplace add anthropics/claude-plugins-community\n```\n\nThen install the plugin:\n\n```\n/plugin install clawcode@claude-community\n```\n\nWhen prompted for scope, select **\"Install for you, in this repo only (local scope)\"** — this keeps the agent isolated to this folder.\n\nThen reload plugins so the skills become available:\n\n```\n/reload-plugins\n```\n\n\u003e **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:\n\u003e\n\u003e ```\n\u003e /plugin marketplace add crisandrews/ClawCode\n\u003e ```\n\u003e\n\u003e ```\n\u003e /plugin install agent@clawcode\n\u003e ```\n\n**3. Create your agent:**\n\n```\n/agent:create\n```\n\nThis starts the bootstrap ritual — a casual conversation where the agent discovers its name, personality, and emoji. You can also import an existing agent instead:\n\n```\n/agent:import\n```\n\n**4. Reload to apply the personality:**\n\n```\n/mcp\n```\n\nThe agent now wakes up with its identity on every session.\n\n## [How it works](#how-it-works)\n\nClawCode injects personality and behavior at four points in the session lifecycle:\n\n| Hook | When | What happens |\n| --- | --- | --- |\n| **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. |\n| **PreCompact** | Context getting full | Reminds agent to save important facts to `memory/YYYY-MM-DD.md` before compression erases them. |\n| **Stop** | Session closing | Reminds agent to write a session summary (what was discussed, decisions, open items). |\n| **SessionEnd** | Session closed | Logs a `session.end` event for the dreaming system. |\n\nThis means:\n- **Every session starts with personality** — the agent never says \"I'm Claude.\" It knows its name, vibe, and your info.\n- **Memory survives compaction** — PreCompact flushes facts before they're lost.\n- **Sessions are summarized** — the next session knows what happened in the last one.\n- **Dreaming tracks sessions** — knows when you were active, when you paused.\n\nThe 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.\n\nFull details: [`docs/hooks.md`](docs/hooks.md)\n\n## [Features](#features)\n\n### [Memory](#memory)\n\nThe 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.\n\nTwo backends: **builtin** (SQLite + FTS5, works out of the box) and **QMD** (local embeddings for semantic search — install with `bun install -g qmd`).\n\nFull details: [`docs/memory.md`](docs/memory.md) · [`docs/memory-context.md`](docs/memory-context.md) · [`docs/qmd.md`](docs/qmd.md)\n\n### [Dreaming](#dreaming)\n\nNightly cron (3 AM) runs 3-phase memory consolidation:\n\n- **Light** — ingests recall signals from the day, deduplicates candidates\n- **REM** — extracts recurring themes, identifies multi-day patterns, writes reflections to `DREAMS.md`\n- **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`\n\nRun manually: `dream(action='run')` or preview with `dream(action='dry-run')`.\n\nFull details: [`docs/dreaming.md`](docs/dreaming.md)\n\n### [Voice](#voice)\n\nTTS 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')`.\n\nFull details: [`docs/voice.md`](docs/voice.md)\n\n### [WebChat](#webchat)\n\nBrowser-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).\n\n```\nagent_config(action='set', key='http.enabled', value='true')\n/mcp\n```\n\nEvery 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.\n\nFull details: [`docs/webchat.md`](docs/webchat.md) · [`docs/http-bridge.md`](docs/http-bridge.md)\n\n### [Messaging channels](#messaging-channels)\n\nReach your agent from WhatsApp, Telegram, Discord, iMessage, or Slack. Each messaging plugin is an independent MCP server — no conflicts with ClawCode.\n\n```\n/agent:messaging\n```\n\nSlash 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).\n\nFull details: [`docs/channels.md`](docs/channels.md)\n\n### [Channel scope](#channel-scope)\n\nWhen 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.\n\n**Default is off.** Users who don't opt in see no behavior change.\n\nTo opt in:\n\n```\n/agent:scope wizard\n```\n\nThe 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.\n\nImportant caveats:\n\n- **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.\n- The filter covers MCP tools (`memory_search`, `memory_get`, `memory_context`, `dream`, `voice_transcribe`, `chat_inbox_read`).\n- A separate per-chat indexer reads upstream `messages.db` read-only and stores chat-id columns locally so per-chat allowlists work.\n- **Trust files are per-workspace.** As of 1.7.0 the trust file lives under `~/.claude/agent/scope-trust/\u003cworkspace-fingerprint\u003e/\u003cchannel\u003e-\u003csuffix\u003e`, keyed by a fingerprint of the workspace path. Granting trust in workspace A does NOT unlock workspace B — open each workspace and run the wizard to grant trust there. Upgrading from 1.5/1.6: legacy global files are ignored; doctor surfaces them with a cleanup command.\n\n**Execution gate** (independent opt-in, layered on top of read scope) — same wizard adds a separate question that activates a PreToolUse gate. When the current turn was triggered by a non-owner message in a paired channel, destructive tools (`Bash`, `Write`, `Edit`, `Task`, etc.) are blocked per a denylist (recommended) or allowlist policy. Shadow mode logs would-block decisions for review; enforce mode blocks them outright. Always-on protected paths refuse MCP writes to plugin internals, agent-config, scope-trust dir, SSH/credential dirs, shell init files, and persistence mechanisms — even with the gate off, so the agent cannot self-modify the gate. A separate per-workspace `\u003cchannel\u003e-exec` trust file (created via Bash) unlocks the gate for a trusted machine without disabling read scope.\n\nFull details: [`docs/channel-scope-compat.md`](docs/channel-scope-compat.md) · [`PRIVACY.md`](PRIVACY.md#channel-scope-per-channel-opt-in)\n\n### [Importing agents](#importing-agents)\n\nHave an existing OpenClaw agent? `/agent:import` brings it into Claude Code with a step-by-step wizard (clickable options, one question at a time):\n\n1. **Bootstrap files** — copies SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md\n2. **Memory** — imports MEMORY.md + recent daily logs (credentials are never copied)\n3. **Memory backend** — asks: QMD (semantic search) or builtin (SQLite + FTS5)?\n4. **Skills** — classifies each skill as GREEN (portable), YELLOW (needs adaptation), or RED (incompatible). You choose: all, specific ones, or skip.\n5. **Crons** — same 3-tier classification for scheduled tasks. Prompts are adapted for Claude Code tools.\n6. **Messaging** — offers WhatsApp, Telegram, Discord, iMessage setup.\n\nFiles 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.\n\n### [Webhooks](#webhooks)\n\nExternal 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.\n\nUse cases:\n- **[Email catch-all](docs/webhooks.md#cloudflare-email-worker--real-time-email-catch-all)** — Cloudflare Email Worker forwards every incoming email to the agent in real-time\n- **[Gmail push](docs/webhooks.md#gmail--real-time-push-notifications)** — Gmail notifies the agent via Pub/Sub when new emails arrive\n- **[CI/CD](docs/webhooks.md#cicd-github-actions)** — GitHub Actions sends build results → agent summarizes and notifies via WhatsApp\n- **[Scheduled tasks](docs/webhooks.md#cloudflare-worker--scheduled-tasks)** — Cloudflare Workers trigger agent actions on a cron schedule\n- **Monitoring** — uptime checker sends alert → agent investigates and reports\n- **IoT** — sensor data arrives → agent logs to memory and acts on thresholds\n\n```sh\ncurl -X POST http://localhost:18790/v1/webhook \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer your-token\" \\\n  -d '{\"event\": \"deploy\", \"status\": \"success\", \"repo\": \"my-app\"}'\n```\n\n**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.\n\nQueue holds up to 1000 events. Drain with `GET /v1/webhooks` or the `chat_inbox_read` MCP tool.\n\nFull details: [`docs/http-bridge.md`](docs/http-bridge.md)\n\n### [Diagnostics](#diagnostics)\n\n`/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 ✅/⚠️/❌ card. Use `--fix` to auto-repair safe issues (create missing `memory/`, reindex SQLite, remove stale `BOOTSTRAP.md`).\n\nFull details: [`docs/doctor.md`](docs/doctor.md)\n\n### [Cron persistence](#cron-persistence)\n\nReminders (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\".\n\nManage reminders through `/agent:crons` (aliases `/agent:reminders`, `list reminders`, `recordatorios`):\n\n```\n/agent:crons list                       # ✅⚠️⏸ status table\n/agent:crons add \"0 9 * * *\" \"email\"    # add a reminder\n/agent:crons delete 3                   # remove with AskUserQuestion confirm\n/agent:crons pause heartbeat-default    # pause without deleting\n/agent:crons reconcile                  # force sync\n/agent:crons import                     # bring OpenClaw crons into the registry\n```\n\nFull details: [`docs/crons.md`](docs/crons.md)\n\n## [Skills](#skills)\n\n| Skill | Description |\n| --- | --- |\n| `/agent:create` | Create a new agent with bootstrap ritual |\n| `/agent:import [id]` | Import an existing agent (personality + memory + skills + crons) |\n| `/agent:doctor [--fix]` | Diagnose agent health. `--fix` applies safe auto-repairs |\n| `/agent:settings` | View/modify agent config (guided) |\n| `/agent:scope` | Channel-scope opt-in: `wizard`, `status`, `enable`, `disable`, `audit`, `test` |\n| `/agent:skill install\\|list\\|remove` | Install community skills from GitHub |\n| `/agent:channels` | Messaging channel status and launch command |\n| `/agent:service install\\|status\\|uninstall\\|logs` | Always-on background service |\n| `/agent:voice status\\|setup` | TTS / STT backends |\n| `/agent:messaging` | Set up WhatsApp, Telegram, Discord, iMessage, Slack |\n| `/agent:crons` / `/agent:reminders` | Manage reminders: list, add, delete, pause, reconcile, import |\n| `/agent:heartbeat` | Memory consolidation and periodic checks |\n| `/agent:update` | Check for new Claude Code / ClawCode releases and print safe update commands |\n| `/agent:status` | Agent status dashboard |\n| `/agent:usage` | Resource usage |\n| `/agent:new` | Save session and prepare for `/clear` |\n| `/agent:compact` | Save context before compression |\n| `/whoami` | Sender info and agent identity |\n| `/help` | List all available commands (dynamic) |\n\n## [Going further](#going-further)\n\n### [Community skills](#community-skills)\n\nInstall skills from GitHub:\n\n```\n/agent:skill install alice/pomodoro\n/agent:skill install alice/skills@main#weather\n/agent:skill list\n/agent:skill remove pomodoro\n```\n\nFull details: [`docs/skill-manager.md`](docs/skill-manager.md)\n\n### [Always-on service](#always-on-service)\n\nRun the agent as a background service (launchd on macOS, systemd on Linux):\n\n```\n/agent:service install\n/agent:service status\n/agent:service logs\n```\n\nThe service defaults are tuned for 24/7 daemon use: PTY wrap so lifecycle hooks survive graceful shutdown, crash-loop guard, persistent logs under `~/.clawcode/logs/`, a resume-on-restart wrapper so the agent rehydrates its last conversation after a restart, and a self-heal sidecar that recovers from stuck deferred-tool loops automatically. Full details in [`docs/service.md`](docs/service.md).\n\nOptional companion: [`docs/watchdog.md`](docs/watchdog.md) — opt-in external health probe + auto-restart for always-on services.\n\n### [Keeping up to date](#keeping-up-to-date)\n\nRun `/agent:update` to check whether Claude Code or ClawCode has a newer release available. The skill compares installed versions against npm and the upstream git tags, prints the safe update commands for each, and never applies them itself. The heartbeat cron does the same check once per UTC day with per-version dedupe, so a new release pings you once and then stays quiet.\n\n### [Configuration](#configuration)\n\nAll settings in `agent-config.json`. Edit directly or use `agent_config`:\n\n```\nagent_config(action='get')\nagent_config(action='set', key='memory.backend', value='qmd')\n```\n\nNon-critical settings apply live. Critical settings need `/mcp` — the agent tells you which.\n\nFull details: [`docs/config-reload.md`](docs/config-reload.md)\n\n## [Updating, uninstalling, and cache](#updating-uninstalling-and-cache)\n\n**Update to the latest version.** Use the command set that matches how you installed. Run each line one at a time — Claude Code's slash commands don't batch.\n\nIf you installed from the community marketplace (`clawcode@claude-community`):\n\n```\n/plugin marketplace update anthropics/claude-plugins-community\n```\n\n```\n/plugin update clawcode@claude-community\n```\n\n```\n/reload-plugins\n```\n\nIf you installed from this repo's marketplace (`agent@clawcode`):\n\n```\n/plugin marketplace update crisandrews/ClawCode\n```\n\n```\n/plugin update agent@clawcode\n```\n\n```\n/reload-plugins\n```\n\nIf `/plugin update` says \"already at latest version\" but you know there's a new one, use the manual method: type `/plugin`, find your installed plugin in the list, press Enter, and select **Update**.\n\nYour personality, memory, skills, and config are preserved — only the plugin code updates. No data loss.\n\n**Uninstall:**\n\n```\n/plugin uninstall clawcode@claude-community   # if installed from community marketplace\n/plugin uninstall agent@clawcode              # if installed from this repo's marketplace\n```\n\nYour agent files (SOUL.md, IDENTITY.md, memory/, skills/) stay in the folder — they're yours. Only the plugin code is removed.\n\n**Clear cache (if reinstall fails or behaves unexpectedly).** The cache path depends on which marketplace you installed from. Close Claude, then in terminal:\n\n```sh\nrm -rf ~/.claude/plugins/cache/claude-community/clawcode   # community marketplace install\nrm -rf ~/.claude/plugins/cache/clawcode                    # own marketplace install\n```\n\nReopen Claude and install again.\n\n### [Multiple agents](#multiple-agents)\n\nEach agent is its own folder with its own personality, memory, and config:\n\n```\n~/agent-work/      ← Agent #1\n~/agent-personal/  ← Agent #2\n```\n\nInstall the plugin in each folder with local scope. Switch: `cd ~/other-agent \u0026\u0026 claude`.\n\n## [Personality files](#personality-files)\n\nEvery agent has these files in its root. They're injected as context at session start via the SessionStart hook.\n\n| File | What it defines |\n| --- | --- |\n| `SOUL.md` | Core truths, boundaries, philosophy — the agent's deepest identity |\n| `IDENTITY.md` | Name, emoji, creature type, vibe, birth date |\n| `USER.md` | Your info: name, timezone, language, preferences |\n| `AGENTS.md` | Operational rules, safety boundaries, local skill triggers |\n| `TOOLS.md` | Platform-specific formatting (WhatsApp uses `*bold*`, Telegram uses `**bold**`) |\n| `HEARTBEAT.md` | What to check every 30 min (review daily logs, consolidate memory) |\n| `BOOTSTRAP.md` | First-run ritual (deleted after onboarding) |\n\nThe 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.\"\n\n## [Session \u0026 data](#session--data)\n\n```\n~/my-agent/\n├── SOUL.md, IDENTITY.md, USER.md     # Agent personality\n├── AGENTS.md, TOOLS.md, HEARTBEAT.md # Behavioral rules\n├── agent-config.json                 # Settings\n├── memory/\n│   ├── MEMORY.md                     # Long-term curated memory\n│   ├── YYYY-MM-DD.md                 # Daily logs (append-only)\n│   ├── .memory.sqlite                # Search index (auto-generated)\n│   └── .dreams/                      # Dream tracking data\n├── .webchat/logs/conversations/      # WebChat logs (JSONL + MD)\n├── skills/                           # Installed + imported skills\n└── IMPORT_BACKLOG.md                 # Skipped import items (if any)\n```\n\n**Conversation logs** are stored in two formats per channel:\n- **JSONL** — one JSON object per line, ideal for programmatic access and memory indexing\n- **Markdown** — human-readable chat transcript\n\n## [Troubleshooting](#troubleshooting)\n\nRun `/agent:doctor` first — it checks everything in one shot. Add `--fix` to auto-repair safe issues.\n\n- **\"Failed to reconnect to plugin:agent:clawcode\" (or `:clawcode:clawcode` on community installs)** — Dependencies didn't install. Check Node.js v18+ (`node --version`). Then try manually depending on where you installed from: close Claude, run `cd ~/.claude/plugins/cache/clawcode/agent/*/  \u0026\u0026 npm install` (own marketplace) or `cd ~/.claude/plugins/cache/claude-community/clawcode/*/  \u0026\u0026 npm install` (community), then reopen Claude.\n- **Agent has no personality** — Run `/mcp` to reload. The SessionStart hook injects identity from SOUL.md + IDENTITY.md.\n- **Memory search returns nothing** — Index builds on first search. For QMD: `agent_config(action='set', key='memory.backend', value='qmd')`.\n- **Agent doesn't remember things** — The active memory reflex uses bilingual synonyms but not everything. Try different keywords.\n- **Config change didn't take effect** — Non-critical settings apply live. Critical ones need `/mcp`. The agent tells you which.\n- **Messaging channels** — Run `/agent:channels status` for installed/authenticated/active status.\n- **Crons don't persist across restarts** — Known limitation: `durable: true` is 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`.\n- **`/plugin update clawcode@agent` stays silent for minutes** — Not hung. Claude Code is downloading and installing the new version in the background; no progress indicator is shown during the fetch. Wait; a status line should appear when it's ready (can take a few minutes on the first update). Once it finishes, `/plugins-reload` is a good follow-up to make sure the running session picks up the new cache before the next turn.\n\n## [Important](#important)\n\n- **Crons only run while Claude Code is open** — for 24/7, use `/agent:service install`.\n- **WebChat + WhatsApp logs** are indexable via `memory.extraPaths` in config.\n- **Each agent folder is fully self-contained** — portable, backupable, deletable.\n\n## [Further reading](#further-reading)\n\nPer-feature documentation in [`docs/`](docs/INDEX.md).\n\n## [Philosophy](#philosophy)\n\nBuild within Claude Code's limits. Use its plugin system, its hooks, its MCP servers. Don't patch Claude Code's internals; don't disable its features from the outside. If a feature needs restraint (the in-process auto-updater during daemon mode, for example), reach for the environment variable Claude Code itself documents, not a workaround. Respect the terms of service. The platform is where the agent lives, not something to work around.\n\n## [Thanks](#thanks)\n\nMost of v1.4.0 and v1.4.1 came from [@JD2005L](https://github.com/JD2005L), running ClawCode as a 24/7 systemd service and sending back a dozen PRs of fixes, hardening, and features from the front lines: the WORKSPACE resolution fix, the service crash-loop PTY wrap, the resume-on-restart wrapper, the hardening defaults, the `/agent:update` skill, cross-user import discovery, the reconcile fast-path, and the self-heal sidecar. Thank you.\n\n## [Disclaimer](#disclaimer)\n\nClawCode is an independent, open-source project. Claude is a trademark of Anthropic, PBC. ClawCode is not affiliated with or endorsed by Anthropic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrisandrews%2FClawCode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrisandrews%2FClawCode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrisandrews%2FClawCode/lists"}