Claudeclaw

README

# Claudeclaw

> A persistent personal-agent layer for Claude Code. Built to give Claude the same shape Hermes-Agent and OpenClaw give to their backends — identity files, MD-based skills, cron routines, persistent memory — but using only Claude Code's native plugin system. No daemon, no separate runtime, no second LLM provider.

If you've used [OpenClaw](https://openclaw.ai/) or [Hermes Agent](https://github.com/NousResearch/hermes-agent), this will feel familiar:

| Concept | OpenClaw / Hermes | Claudeclaw |
|---|---|---|
| Persistent identity | `~/.openclaw/workspace/{IDENTITY,SOUL,USER,MEMORY,AGENTS,TOOLS,HEARTBEAT,BOOT}.md` | `~/.claude/plugins/claudeclaw/identity/{IDENTITY,SOUL,USER,MEMORY,AGENTS,TOOLS,HEARTBEAT,BOOT}.md` |
| Skills (procedural memory) | `~/.openclaw/skills/<name>/SKILL.md` | `~/.claude/plugins/claudeclaw/skills/<name>/SKILL.md` |
| Cron routines | `openclaw cron add …` | `/cron add …` — dual backend: local daemon (sub-minute, no quota, needs your machine) or Claude Routines (cloud, fires offline, daily quota). See [`docs/scheduling.md`](docs/scheduling.md). |
| Memory persistence | `MEMORY.md` (single file, capped) | `MEMORY.md` (fast-path) + Claude Code's auto-memory (`~/.claude/projects/<project>/memory/`) |
| Subagent delegation | `agent` registry | Native sub-agents (`~/.claude/plugins/claudeclaw/agents/<name>.md`) |
| Multi-platform messaging | Native (WhatsApp, Telegram, Discord, …) | Built-in **gateway** for Telegram, Slack, WhatsApp — same identity, skills, memory. See [`gateway/README.md`](gateway/README.md). |
| One-line install | `curl …/install.sh \| bash` | `curl …/install.sh \| bash` |

## What this gives you

- **A Claude Code session that boots with context.** Every time you open Claude Code, it loads who you are, what it values, what it remembers, and what's on the schedule — before you say anything.
- **Skills that auto-trigger.** Saying "summarize my inbox" runs the `inbox-summarize` skill instead of Claude reasoning from scratch each time.
- **Memory that persists across sessions.** Two stores: a fast-path `MEMORY.md` for lines you want loaded every prompt, and a long-form auto-memory for per-topic markdown files.
- **Cron routines.** Schedule a morning brief, an inbox sweep, a weekly memory consolidation — all delivered into your next session.
- **Subagents you can delegate to.** A researcher for web work, a coder for focused implementation, a scheduler for cron management, a librarian for memory curation.
- **Identity you can edit.** All of it lives in plain markdown. Open the files, change them, run `/boot` — Claw is now different.

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/leadsblender/claudeclaw/main/install.sh | bash
```

Add `--with-gateway` to also install the messaging gateway (Slack/Telegram/WhatsApp):

```bash
curl -fsSL https://raw.githubusercontent.com/leadsblender/claudeclaw/main/install.sh | bash -s -- --with-gateway
```

Or from a local checkout:

```bash
cd claudeclaw && bash install.sh                 # core only
cd claudeclaw && bash install.sh --with-gateway  # core + messaging
```

The installer:

1. Verifies you have `claude` (Claude Code CLI) installed.
2. Drops the plugin into `~/.claude/plugins/claudeclaw/`.
3. Registers it in `~/.claude/settings.json` (`enabledPlugins.claudeclaw = true`).
4. Tells you what to do next.

## First run

Open Claude Code anywhere:

```bash
claude
```

Because `USER.md` still has placeholder values, the `onboarding` skill runs automatically. It asks you five questions, writes your answers into `USER.md` and `SOUL.md`, and you're personalized. Total time: ~90 seconds.

After that, every session greets you by name, knows what you're working on, and obeys your tone preferences.

## Daily use

| You say | What happens |
|---|---|
| _"morning brief"_ | Calendar + inbox + open PRs + suggested first move, in one screen. |
| _"summarize my inbox"_ | Threads grouped by needs-reply / needs-decision / fyi / noise. |
| _"review this PR"_ or `/review` | Structured review with blockers / should-fix / consider / liked. |
| _"remember that I prefer Vite over webpack"_ | Memory written to the right store automatically. |
| `/cron add summarize my inbox every weekday at 8am` | Scheduled, added to `HEARTBEAT.md`. |
| `/skill list` | Every skill Claw has, with one-line descriptions. |
| `/identity edit SOUL` | Reshape Claw's voice. Run `/boot` after to apply. |

## File map

```
claudeclaw/
├── .claude-plugin/plugin.json    # Manifest
├── identity/                     # Who Claw is — load order: IDENTITY → SOUL → USER → MEMORY → AGENTS → TOOLS → HEARTBEAT
│   ├── IDENTITY.md
│   ├── SOUL.md
│   ├── USER.md                   # ← personalize this
│   ├── MEMORY.md                 # ← Claw writes here over time
│   ├── AGENTS.md
│   ├── TOOLS.md
│   ├── HEARTBEAT.md              # ← schedule view
│   └── BOOT.md
├── skills/                       # Procedural memory — auto-triggered routines
│   ├── identity-loader/SKILL.md
│   ├── onboarding/SKILL.md
│   ├── memory-keeper/SKILL.md
│   ├── morning-brief/SKILL.md
│   ├── inbox-summarize/SKILL.md
│   ├── code-review/SKILL.md
│   ├── web-research/SKILL.md
│   └── cron-routine/SKILL.md
├── commands/                     # Slash commands
│   ├── boot.md
│   ├── identity.md
│   ├── memory.md
│   ├── skill.md
│   ├── cron.md
│   ├── agent.md
│   └── heartbeat.md
├── agents/                       # Subagents
│   ├── researcher.md
│   ├── coder.md
│   ├── scheduler.md
│   └── librarian.md
├── hooks/hooks.json              # SessionStart → boot
├── scripts/                      # Hook helpers
│   ├── session-start.sh
│   └── check-pending-crons.sh
├── docs/
│   ├── architecture.md
│   ├── messaging-gateway.md
│   ├── extending.md
│   └── differences.md
├── install.sh
├── uninstall.sh
└── README.md
```

## Extending

- **Add a skill:** `/skill new <name>` and answer the three questions.
- **Add a slash command:** drop a markdown file in `commands/`. Frontmatter needs `description`. The body is the prompt that runs.
- **Add a subagent:** drop a markdown file in `agents/`. Frontmatter needs `name`, `description`, `tools`, `model`.
- **Add a hook:** edit `hooks/hooks.json`. See [Claude Code hook docs](https://docs.claude.com/claude-code/hooks).
- **Add an MCP-backed tool:** install the MCP server in your Claude Code settings; the new tools are immediately available to skills.

## What's deliberately not here

- **No second LLM.** Claudeclaw rides on Claude Code; you don't pick a provider per skill. If you want multi-provider, run Hermes.
- **No always-on agent loop.** Cron routines fire via Claude Code's `scheduled-tasks` mechanism. The messaging gateway runs as its own daemon and spawns `claude -p` per inbound message — it's reactive, not continuously running an agent in the background.
- **No first-class iMessage / Discord / Signal yet.** The adapter pattern in `gateway/adapters/` makes it ~50 lines per channel — see [`gateway/README.md`](gateway/README.md) and [`docs/extending.md`](docs/extending.md). Telegram, Slack, WhatsApp ship in v0.1.

## License

MIT. See `LICENSE`.