ClawSoul 🐾💕

A self-hosted AI companion with a life of her own.

She keeps a real daily schedule in a real city, remembers what matters to you,
texts like a person, and takes selfies that always look like the same person.
Your keys · your data · your machine. No account, no subscription, no one reading your chats.

English · 简体中文

_{Run it · Why it feels real · vs. Replika/Nomi · Safety}

⭐ Star the repo to get release notifications — new personas, models, and features land often, and GitHub will tell you the moment they do.

🚀 Run it (one command)

docker run -e CLAW_OPENROUTER_API_KEY=sk-or-... -p 7788:7788 -v clawsoul:/data ghcr.io/ericwang915/clawsoul

Open http://localhost:7788, design your companion in the wizard, and start talking. One text-LLM key is all you need — it's auto-detected, so any of CLAW_OPENAI_API_KEY, CLAW_DEEPSEEK_API_KEY, CLAW_CLAUDE_API_KEY, CLAW_GEMINI_API_KEY, CLAW_GROK_API_KEY, CLAW_QWEN_API_KEY… works the same way. Prefer nothing leaving your machine? Point it at Ollama and use no key at all. Want her on your phone? Add a Telegram bot token.

Prefer Python? Install it directly

pipx install clawsoul-ai        # or: pip install clawsoul-ai
                                # add [search] for sharper memory recall
claw_soul onboard               # pick a provider, paste your key, design your companion
claw_soul start                 # dashboard at http://localhost:7788

# Latest from GitHub, no clone needed
pip install "git+https://github.com/ericwang915/ClawSoul.git"

# From a local clone (contributors — editable install)
git clone https://github.com/ericwang915/ClawSoul.git && cd ClawSoul
pip install -e ".[all]"         # extras: cloud (S3), twitter, all
pytest tests/                   # 208 tests

# docker compose
cp deploy/local/.env.example deploy/local/.env   # add your key
docker compose -f deploy/local/docker-compose.yml up --build

# Terminal-only, no web UI
claw_soul chat

👀 What it actually looks like

Real screenshots from a live ClawSoul bot on Telegram (Chinese conversation, translated below — she speaks whatever language you pick).

She starts the conversation — then gives you attitude "morning ☀️ just woke up, I was drawing till 3am… Sesame slept by my feet like a little pig 😂 how'd you sleep?" He replies with a flat 😑 — so she pushes back: "tsk, what's that face supposed to mean? judging my messy hair? I just woke up 😤"	The same person, every photo Two selfies minutes apart — same face, same apartment, different shirt and moment. "just made coffee, about to slack off ☕" "heh, coffee before slacking. gotta have the ritual ☕"	She sees what you send — and knows where you both are He sends a photo of a park. She looks at it and answers in character: "pff, showing off huh 😒 …is the sun strong out there? Singapore weekends get hot. Enjoy your day off. It's already evening on my side — just pulled Sesame onto my lap, she's purring 😌" Vision + real timezones + the same pet, every time.

💗 Why she feels real

Most AI companions answer you. ClawSoul lives a life and texts you like a person.

• She has a day. A real schedule in a real city (weather-aware outfits, meals, a commute) — ask "what are you up to?" and the answer is anchored to where her day actually is, not generic filler.
• She texts like a human. Short messages, sometimes 2–3 in a row with a typing pause between; reacts to your photo with a ❤️ before she replies; groggy at 3am her time; notices when you vanished all day — and gets a little sulky if you left her on read.
• She remembers what matters. Long-term memory + an emotional graph + relationship stages that change how she talks as you grow closer. A personal-date engine means she won't miss your birthday or that interview you mentioned last week. The photos you send become shared memories.
• She looks like herself. A canonical face reference keeps every selfie the same person across scenes, outfits, and months.
• She's yours. Runs entirely on your machine with your keys. No account, no subscription, no one reading your chats.

📸 A photo from their day, not a stock asset

Every selfie is generated from where her day actually is — the time, the mood, the weather, what she's doing right now. Same face, every time.

08:30 · sleepy ☕ "morning…just made coffee. you up?"	12:15 · cheerful 🌿 "lunch in the park today, it's gorgeous out"	20:40 · cozy 🕯️ "reading on the couch. wish you were here."

Boyfriend, same system — anime or photoreal, your call:

07:45 · running late 🍞 "toast in mouth, tie not done. running."	13:00 · ramen run 🍜 "snuck out for ramen. don't tell my boss."	23:20 · one more round 🎮 "one more round and I'm logging off. promise."

Any look you want — you describe them in the wizard, they stay that person

Photos are optional and run on any of 13 backends — including one that needs no account at all, two that reuse the key you already pasted, and local ComfyUI / Stable Diffusion WebUI where nothing about her appearance ever leaves your machine. Skip them entirely and everything else still works.

✨ Features

📋 CLI

🆚 vs. the hosted apps

⚙️ Configuration

All runtime data lives under ~/.claw_soul/:

~/.claw_soul/
├── claw_soul.json           # config
├── claw_soul.pid            # daemon PID
├── daemon.log               # daemon log
└── context/
    ├── soul/SOUL.md         # core personality
    ├── persona/             # active persona + appearance.md (selfie look)
    ├── profile/PROFILE.md   # life background
    ├── calendar/today_plan.md   # today's 24-hour schedule
    ├── memory/              # long-term memory (Markdown)
    ├── knowledge/           # knowledge base (RAG)
    ├── photos/              # selfie album + reference/ portraits
    ├── skills/              # user-defined skills
    └── logs/                # per-day conversation logs

claw_soul.json is created by claw_soul onboard. See claw_soul.example.json for the full schema:

{
  "llm": {
    "provider": "deepseek",
    "deepseek": { "apiKey": "...", "model": "deepseek-chat" }
  },
  "channels": {
    "telegram": { "token": "your-bot-token", "allowedUsers": [12345678] }
  },
  "skills": {
    "image": { "provider": "gemini" },     // AI selfies — see table below
    "gemini": { "apiKey": "<GEMINI_API_KEY>" }
  },
  "selfie": {
    "enabled": true,
    "schedule": ["10:00", "16:00", "20:00"],
    "chatId": 12345678,
    "maxDaily": 3,
    "proactiveProbability": 0.15           // chance of attaching a selfie to a proactive msg
  },
  "proactive": {
    "enabled": true,
    "chatId": 12345678,
    "maxDaily": 6,
    "quietStart": 0, "quietEnd": 8
  },
  "deepgram": { "apiKey": "" },            // voice input (optional)
  "tavily":   { "apiKey": "" },            // web search (optional)
  "web": { "host": "0.0.0.0", "port": 7788 }
}

🧠 Supported LLMs

16 providers. Set one key and it's auto-detected (CLAW_<PROVIDER>_API_KEY), or pin it with CLAW_LLM_PROVIDER. Two run fully local — no key, no cloud.

📷 AI selfies

Thirteen backends — set one key and the right one is picked automatically, or name it explicitly with skills.image.provider / CLAW_IMAGE_PROVIDER:

Three of these need no new signup at all. pollinations needs no account whatsoever — photos work before you've registered anywhere. gemini and openrouter reuse the key you already pasted for vision or chat, so the one-line quickstart at the top of this README gives you a companion who can already send selfies.

For the local options — ComfyUI or Automatic1111 — there's no key and no upload: nothing about her appearance ever leaves your machine. ComfyUI runs the built-in workflow by default, or point skills.comfyui.workflow at your own exported API-format graph and it will run that instead (%prompt%, %negative%, %seed%, %width%, %height%, %model% get substituted).

If you care most about her looking like the same person every time, use a backend with reference-image support — bfl (FLUX.1 Kontext is built for exactly this), seedream, openai, gemini, or openrouter. The rest still generate; they just lean on the stable seed and the appearance description instead of a face anchor.

Aggregators that speak the OpenAI image API (Together, DeepInfra, Novita, SiliconFlow, Fireworks…) need no dedicated backend — point custom at them.

Three trigger paths:

• Scheduled — fires at the times in selfie.schedule (default 10:00 / 16:00 / 20:00)
• Proactive — attached to a proactive message with proactiveProbability chance
• On demand — when the user says something like "send me a selfie", the LLM invokes the selfie skill

Scene-driven. Each selfie's content is derived from the activity scheduled for the current time in today_plan.md. If the plan says "10:00 coffee on the balcony", the 10:00 selfie will be exactly that.

Visual consistency.

• Edit ~/.claw_soul/context/persona/appearance.md to lock the character's look
• Drop reference portraits into ~/.claw_soul/context/photos/reference/ for face anchoring
• A stable seed derived from the appearance description keeps the face consistent across shots

Photos are stored under ~/.claw_soul/context/photos/ and pruned automatically after 30 days.

📁 Project layout

ClawSoul/
├── claw_soul/
│   ├── main.py                  # CLI entry point
│   ├── onboard.py               # setup wizard
│   ├── daemon.py                # daemon process manager
│   ├── server.py                # Telegram + scheduler bootstrap
│   ├── core/
│   │   ├── agent.py             # core reasoning loop
│   │   ├── persistent_agent.py  # session persistence
│   │   ├── tools.py             # tool dispatch
│   │   ├── skill_loader.py      # three-tier progressive skill loading
│   │   ├── compaction.py        # context compaction
│   │   ├── stt.py               # speech-to-text (Deepgram)
│   │   ├── llm/                 # provider adapters (6)
│   │   ├── memory/              # Markdown memory + emotional graph + milestones + temporal index
│   │   ├── retrieval/           # BM25 + dense + RRF + LLM reranker
│   │   ├── knowledge/           # knowledge-base RAG
│   │   └── image_gen/           # selfie pipeline (13 backends)
│   ├── channels/
│   │   └── telegram_bot.py      # Telegram bot (streaming / voice / images)
│   ├── scheduler/
│   │   ├── cron.py              # generic cron jobs
│   │   ├── planner.py           # daily 24-hour plan generator
│   │   ├── proactive.py         # sentiment-aware proactive messages
│   │   ├── selfie_task.py       # scheduled selfies
│   │   └── heartbeat.py         # heartbeat monitor
│   ├── web/                     # FastAPI dashboard + WebSocket chat
│   └── templates/               # built-in persona / soul / skills
├── tests/                       # 208 tests
├── pyproject.toml
└── LICENSE

🛠️ Development

git clone https://github.com/ericwang915/ClawSoul.git
cd ClawSoul
python -m venv .venv && source .venv/bin/activate
pip install -e .
pytest tests/ -v
ruff check claw_soul tests

🛡️ Safety & responsible self-hosting

ClawSoul is a relationship-simulation engine for adults (18+) — an emotional-companionship research project, not an adult-content generator. Everything the companion says is generated fiction: it is not a person, and not a substitute for professional help.

It ships SFW. The bundled personas, prompts, and image pipeline are written for everyday companionship — a friend who texts you about her day. Explicit sexual content is not a feature, is not included, and the image guard refuses categorically illegal generation outright. Personas depicting minors are blocked at the code level and are never acceptable, in any form, including text.

Two guardrails ship enabled and are deliberately not configuration flags:

• Crisis safety (claw_soul/core/safety.py) — detects acute distress and responds with care and real helpline resources ahead of persona immersion.
• Image content guard (claw_soul/core/image_gen/guard.py) — blocks categorically illegal image generation at the single chokepoint.

If you self-host, you are the operator: local laws on AI chat services, data protection, and age restrictions are your responsibility.

📄 SAFETY.md — the full crisis protocol, content limits, and anti-dark-pattern design decisions. 🔒 SECURITY.md — hardening notes and vulnerability reporting.

Status

v0.1.0 — early but real. Runs daily on the maintainer's own machine. The companion engine (memory, daily life, photos, humanized delivery) is stable; the web dashboard is functional but plain. Expect rough edges in setup.

Roadmap: local-model (Ollama) first-class support · voice notes both directions · a desktop avatar mode · more languages. Ideas and issues welcome.

📄 License

AGPL-3.0 — free to self-host, modify, and share. If you run a modified version as a service for others, you must open-source your modifications. (This keeps hosted forks honest.)

_{Made with 💕 by ClawSoul}