caliclaw 0.3.1

Personal AI assistant that lives in Telegram. Agents with memory, souls, and autonomous loops.

caliclaw

Your own personal AI assistant. Any server. Any task. The claw way. 🔱

The first and only personal AI assistant built for Claude. No API key — just your subscription.

Why caliclaw

Other AI assistants (openclaw, etc.) require API keys, manual configuration, and don't support Claude at all. caliclaw is different:

• Zero config — caliclaw start does everything. Setup, dependencies, pairing — automatic
• No API key — runs on your Claude subscription. No tokens, no billing surprises
• No TOS violations — built on official tools, not reverse engineering
• Agents that actually work — spawn agents on the fly, run them in parallel (swarm), chain them (pipeline), or let them work autonomously (loop) until the task is done
• They remember — persistent memory across sessions. Your assistant learns who you are and how you work
• They have a soul — personality, rules, and behavior defined in simple markdown files, not buried in code
• They know when to stop — anti-hallucination layer, permission levels, human approval for dangerous actions. Type stop and everything halts instantly
• Secure by default — prompt injection protection, input filtering, and encrypted vault built in. No setup needed
• They work while you sleep — cron jobs, scheduled heartbeats, automated checks
• Smart with your limits — tracks usage as % of daily limit, auto-downgrades models when you're running hot
• Sandbox by default — agents work in isolated workspace. Unleash them on real directories only when you need to: /unleash ~/myproject
• Context follows you — switch directories with /unleash, conversation context is preserved automatically. One assistant, infinite places to work

caliclaw vs openclaw

	caliclaw	openclaw
Claude support	Yes	No
API key required	No — subscription only	Yes
Setup time	One command	Manual config
Agents spawn agents	Yes	No
Agents work autonomously	Yes — loops with limits	No
Agents extract knowledge on death	Yes	No
Prompt injection protection	Built in	Manual
Memory across sessions	Yes	Varies
Soul system	Yes	Yes
Scheduled tasks	Built in	Plugin
Voice messages	Built in	No
Open source	Yes	Yes

What you get

• Telegram bot — text, voice, photos, files. Streaming responses. Inline controls
• 20+ commands — agents, tasks, memory, skills, model switching, all from Telegram
• Terminal chat — TUI alternative when you're already in the terminal
• Voice — send voice messages, whisper-cpp transcribes them
• Skills system — enable/disable capabilities. Create your own in markdown. Browse community skills at caliclaw-gym
• Encrypted vault — store secrets your agents can use
• Health dashboard — web UI for monitoring usage and status
• Migration — coming from openclaw/nanoclaw/zeroclaw? One command imports everything

Quick start

From PyPI:

pip install caliclaw
caliclaw start

From source:

git clone https://github.com/califlaw/caliclaw.git
cd caliclaw
source install.sh
caliclaw start

First run triggers setup automatically. Pair with your bot by sending /pair <code> in Telegram.

No YAML configs. No Docker. No environment variables to hunt down.

Need to change something later? Use caliclaw reforge to pick one component (credentials, profile, soul, model, or skills) and re-configure it without touching the rest.

To stay current: caliclaw update checks PyPI and upgrades in place.

Requirements

• Python 3.10+
• Claude Code CLI installed and authenticated
• Telegram bot token from @BotFather

How agents work

When you kill an agent, it doesn't just die — it extracts everything it learned into memory. The next agent picks up where it left off. Knowledge never dies.

You send a message in Telegram
  -> caliclaw loads the agent's soul, memory, and skills
  -> Agent processes your request with full system access
  -> Response streams back to Telegram in real-time
  -> Conversation saved, memory updated

Need parallel work?
  -> /spawn researcher "find all bugs in auth module"
  -> /spawn fixer "fix the bugs researcher found"
  -> They work independently, report back to you

Need autonomous work?
  -> /loop "refactor the entire test suite"
  -> Agent works in iterations until done or you say stop

Need scheduled work?
  -> /cron "0 9 * * *" "check server health and report"
  -> Runs every morning, sends you the result

Skills marketplace — caliclaw-gym 🏋️

caliclaw ships with 13 default skills — a professional dev kit, not a newbie bundle:

Core	Unique	Meta
code read first, minimal diffs	incident-response production fires	self-evolve agent creates new skills
shell bash mastery	code-review review like a senior
git atomic commits, recovery	automation glue scripts, webhooks, cron
ops ssh, systemd, deploy
debug read errors, isolate
research authoritative sources
security secrets, OWASP
testing pyramid, regression
web-access search + fetch

Need more? Browse community-built skills at https://califlaw.github.io/caliclaw-gym/:

caliclaw skills gym                     # browse all community skills
caliclaw skills install stripe-webhooks # install one
caliclaw skills publish my-skill        # share yours with the community

Built your own skill and want to share it? Fork caliclaw-gym, add skills/<name>/SKILL.md, open a PR. After merge it gets a voting issue — community upvotes with 👍 and it ranks by stars. See the contributing guide.

No API, no backend, no auth — just GitHub Issues for voting and GitHub Pages for the browser. Zero infrastructure, fully community-owned.

Choosing the model

By default caliclaw uses sonnet — balanced between speed and reasoning. Change it anytime:

caliclaw model                    # show current default + options
caliclaw model set opus           # switch to opus (more reasoning, heavier)
caliclaw model set haiku          # switch to haiku (fast, cheap)

The CLI persists your choice in .env and auto-restarts the bot if it's running. You can also switch runtime-only via /model in Telegram.

Migration

Coming from another *claw project?

caliclaw migrate ~/path/to/old-project

Auto-detects project type. Migrates soul, memory, skills, database. Supports openclaw, nanoclaw, zeroclaw.

Deploy

ssh user@vps
pip install caliclaw
caliclaw start

Auto-reconnects on network drops. Auto-restarts on failure. Graceful shutdown with watchdog.

Make it immortal ☠

Survive reboots, crashes, OOM kills — caliclaw comes back every time:

caliclaw immortal on       # installs systemd unit, enables, starts
caliclaw immortal          # status — alive/dead, immortal/mortal
caliclaw immortal off      # break the seal

During first-run caliclaw init, the "Keep caliclaw always running" option does the same thing. You can toggle it later anytime with caliclaw immortal on/off — no need to re-run init.

Status output looks like:

  ☠  IMMORTAL  survives reboots and crashes
  ♥  Alive right now

Documentation

Full docs in docs/:

• Commands reference — every CLI and Telegram command
• Configuration — all .env settings
• Backup & recovery
• Troubleshooting
• Contributing — development guide

License

MIT