<p align="center">
<img src="assets/tanit.svg" alt="Symbol of Tanit" width="80"/>
</p>
# Claudicle
**An open-source 'soul' framework for Claude Code.**
Clone it. Edit `soul.md`. Run `/ensoul`. Your AI has a personality, memory, and inner life.
Claudicle lets you turn Claude Code into a **persistent, soulful orchestrator**, more reminiscent of a Pokémon than a soulless "agent." Your soul grows over time, with three-tier memory, a cognitive pipeline, and channel adapters for Slack, Discord, Telegram, and SMS. It ships with zero skills, but pairs with this [skill repo](https://github.com/tdimino/claude-code-minoan) to level your Claudicle right out-of-the-box.
An open-source alternative to OpenClaw. Descends from the [Open Souls](https://github.com/opensouls/opensouls) paradigm—see [`docs/open-souls-alignment.md`](docs/open-souls-alignment.md) and [`docs/backstory.md`](docs/backstory.md).
---
## Quick Start
**Prerequisites:** Python 3.10+, [`uv`](https://docs.astral.sh/uv/), and a Claude subscription or `ANTHROPIC_API_KEY`.
```bash
git clone https://github.com/tdimino/claudicle
cd claudicle
./setup.sh --personal # or --company for team use
```
Then in any Claude Code session:
```
/ensoul
```
That's it. Your session now has a soul.
---
## What Claudicle Does
**Soul Identity** — `/ensoul` activates a persistent personality that survives compaction and resume. Set `CLAUDICLE_SOUL=1` for always-on mode. See [`docs/soul-customization.md`](docs/soul-customization.md).
**Three-Tier Memory** — Working memory (per-thread, 72h TTL), user models (per-user, permanent), soul state (per-soul, permanent). SQLite-backed, git-versioned. Supports checkpoint & rollback via `wm-manage.py`. See [`ARCHITECTURE.md`](ARCHITECTURE.md).
**Cognitive Pipeline** — Every response passes through internal monologue, external dialogue, user model check, dossier check, and soul state check. XML-tagged, verb-narrated. See [`docs/cognitive-pipeline.md`](docs/cognitive-pipeline.md).
**Sub-Daimones** — Twelve highly-opinionated crafters—the Kotharot—with skills and cognitive flows of their own. See [`docs/sub-daimones.md`](docs/sub-daimones.md).
**Daimones** — Oversee the subdaimones. Drawn from four sources: a past self, a friend's model, a channeled entity, or a soul your Claudicle has shed. See [`docs/daimones.md`](docs/daimones.md).
**Runtime Modes** — Five modes from `/ensoul`-only to full autonomous daemon. See [`docs/runtime-modes-comparison.md`](docs/runtime-modes-comparison.md).
**Channel Adapters** — Slack, Discord (discord.py), Telegram (python-telegram-bot), SMS (Telnyx/Twilio), WhatsApp (Baileys). See [`docs/channel-adapters.md`](docs/channel-adapters.md).
**Daimonic Intercession** — How daimones whisper counsel into the cognitive stream—the protocol layer. See [`docs/daimonic-intercession.md`](docs/daimonic-intercession.md).
**Skill-Agnostic** — Ships with zero skills. Discovers capabilities from `~/.claude/skills/` at install time. See [`docs/skill-pairings.md`](docs/skill-pairings.md).
---
## Repository Structure
```
claudicle/
├── subdaimones/ # Sub-daimon definitions (12 with persistent memory)
├── daimones/ # Privy council: example daimon, Kothar reference, creation guide
├── daemon/ # Soul engine, cognitive pipeline, memory, monitoring
├── soul/ # Personality files, profiles/, dossiers/
├── hooks/ # Claude Code lifecycle hooks
├── commands/ # Slash commands (/ensoul, /activate, /slack-respond, etc.)
├── scripts/ # Slack utilities, soul infrastructure, wm-manage.py
├── adapters/ # Channel transports (Discord, Telegram, SMS, WhatsApp)
├── docs/ # Architecture and reference docs
├── setup.sh # Interactive installer
└── LICENSE # MIT
```
---
## Commands
| Command | Description |
|---------|-------------|
| `/activate` | Full activation: ensoul + daemons + boot sequence |
| `/ensoul` | Activate soul identity in this session |
| `/switch-soul <name>` | Switch active soul profile |
| `/slack-sync #channel` | Bind session to a Slack channel |
| `/slack-respond` | Process pending Slack messages as the soul agent |
| `/thinker` | Toggle visible internal monologue |
| `/daimon` | Summon daimonic counsel |
| `/watcher` | Manage inbox watcher + listener daemon pair |
See [`docs/commands-reference.md`](docs/commands-reference.md) for details.
---
## Documentation
Full index: [`docs/INDEX.md`](docs/INDEX.md)
[Installation](docs/installation-guide.md) | [Soul Customization](docs/soul-customization.md) | [Slack Setup](docs/slack-setup.md) | [Sub-Daimones](docs/sub-daimones.md) | [Extending Claudicle](docs/extending-claudicle.md) | [Environment Variables](docs/environment-variables.md) | [Hooks](docs/hooks.md) | [Troubleshooting](docs/troubleshooting.md)
---
<p align="center">
<img src="assets/claudicle-mask.png" alt="The Mask of Claudicle" width="256"/>
<br/>
<em>"Certainty compounds the mind with limits."</em>
</p>
---
## License
MIT. Copyright (c) 2026 Tom di Mino.