ClawCode

README

<h1 align="center">🛸 ClawCode</h1>

<p align="center">
  <strong>Persistent agents for Claude Code — memory, dreaming, and personality.</strong>
</p>

<p align="center">
  <a href="https://github.com/crisandrews/ClawCode/releases"><img src="https://img.shields.io/github/v/release/crisandrews/ClawCode?include_prereleases&style=for-the-badge&color=FF6B35" alt="Release"></a>
  <a href="https://github.com/crisandrews/ClawCode/stargazers"><img src="https://img.shields.io/github/stars/crisandrews/ClawCode?style=for-the-badge&color=blue" alt="Stars"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
  <img src="https://img.shields.io/badge/node-%E2%89%A5%2018-blue?style=for-the-badge&logo=node.js&logoColor=white" alt="Node ≥ 18">
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue?style=for-the-badge" alt="Platform">
</p>

<p align="center">
  <a href="#quick-setup">Quick Setup</a> ·
  <a href="#features">Features</a> ·
  <a href="#skills">Skills</a> ·
  <a href="#going-further">Going further</a> ·
  <a href="#troubleshooting">Troubleshooting</a> ·
  <a href="https://github.com/crisandrews/ClawCode/issues">Issues</a>
</p>

---

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.

## [Highlights](#highlights)

- **[Persistent identity](#quick-setup)** — name, personality, emoji. The agent wakes up as itself on every session.
- **[Active memory](#memory)** — bilingual recall at the start of every turn. Spanish question finds English memory and vice versa.
- **[Dreaming](#dreaming)** — nightly 3-phase memory consolidation with 6 weighted signals.
- **[Voice](#voice)** — TTS via sag, ElevenLabs, OpenAI, macOS `say`. STT via Whisper.
- **[WebChat](#webchat)** — browser-based chat UI with real-time SSE, conversation logging in JSONL + Markdown.
- **[Messaging channels](#messaging-channels)** — WhatsApp, Telegram, Discord, iMessage, Slack via MCP plugins.
- **[Community skills](#community-skills)** — install from GitHub with `owner/repo@branch#subdir`.
- **[Always-on](#always-on-service)** — launchd / systemd service with one command.
- **[Doctor](#diagnostics)** — diagnose and auto-repair agent health.
- **[Terse by design](#features)** — "Guardado. 🍣" not "I will now proceed to save your message to the daily memory log..."

## [Prerequisites](#prerequisites)

- [Node.js](https://nodejs.org/) v18+

## [Quick Setup](#quick-setup)

**1. Create a folder for your agent.**

Each agent lives in its own folder. Create one and open Claude Code there:

```sh
mkdir ~/my-agent && cd ~/my-agent
claude
```

**2. 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.

## [Features](#features)

### [Memory](#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), date-aware ("what did we discuss yesterday?"), and safety-critical (warns about allergies before suggesting food).

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.md) · [`docs/memory-context.md`](docs/memory-context.md) · [`docs/qmd.md`](docs/qmd.md)

### [Dreaming](#dreaming)

Nightly cron (3 AM) runs 3-phase memory consolidation — Light, REM, Deep — using 6 weighted signals to promote important memories to `memory/MEMORY.md`. Run manually with `dream(action='run')`.

Full details: [`docs/dreaming.md`](docs/dreaming.md)

### [Voice](#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`](docs/voice.md)

### [WebChat](#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
```

Full details: [`docs/webchat.md`](docs/webchat.md) · [`docs/http-bridge.md`](docs/http-bridge.md)

### [Messaging channels](#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
```

Full details: [`docs/channels.md`](docs/channels.md)

### [Diagnostics](#diagnostics)

`/agent:doctor` inspects config, identity, memory, SQLite, QMD, crons, HTTP bridge, messaging, and dreaming. Returns a ✅/⚠️/❌ card. Use `--fix` to auto-repair safe issues.

Full details: [`docs/doctor.md`](docs/doctor.md)

## [Skills](#skills)

| 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` | Import crons as local scheduled tasks |
| `/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) |

## [Going further](#going-further)

### [Community skills](#community-skills)

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`](docs/skill-manager.md)

### [Always-on service](#always-on-service)

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`](docs/service.md)

### [Configuration](#configuration)

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`](docs/config-reload.md)

## [Updating, uninstalling, and cache](#updating-uninstalling-and-cache)

**Update to the latest version:**

```
/plugin update agent@clawcode
/reload-plugins
```

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:

```sh
rm -rf ~/.claude/plugins/cache/clawcode
```

Reopen Claude and install again.

### [Multiple agents](#multiple-agents)

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`.

## [Session & data](#session--data)

```
~/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

## [Troubleshooting](#troubleshooting)

Run `/agent:doctor` first — it checks everything in one shot. Add `--fix` to auto-repair sa

... (truncated)