claudeclaw
A personality, heartbeat loop, and Telegram bridge for Claude Code — bring your subscription, skip the API key.
claudeclaw is a workspace template for people who already pay for Claude (Pro/Max/Team) and want their CLI to feel like an always-on co-worker: it knows who you are, talks the way you've trained it to, runs recurring background checks, and answers your phone over Telegram. All of it routed through your existing Claude Code session — no separate daemon, no extra LLM API key.
If you've used OpenClaw and liked the model but didn't want to pay twice for inference, this is that pattern reimplemented on Claude Code's primitives (hooks, skills, channel plugins).
What you get
- Conversational onboarding. First launch, the agent asks who you are, who it is, how it should communicate. No config files to hand-edit.
- Persistent identity across sessions.
profile/IDENTITY.md, USER.md, SOUL.md capture the agent, you, and the voice. Auto-loaded every session.
- Heartbeat loop. Every 30 minutes a sub-agent reads
profile/HEARTBEAT.md and runs whatever recurring checks live there — inbox triage, deploy status, AI news, calendar gaps. Replies HEARTBEAT_OK if nothing needs attention.
- Telegram bridge. Talk to your workspace from your phone. The agent reacts 👀 on inbound, streams tool calls live as it works, and pushes the final reply with a notification. Telegram-flavoured Markdown is rendered automatically.
- Shippable as a template. This same repo is both the published template AND your personal instance. Personal files live under
profile/ (gitignored); framework updates pull cleanly with no merge conflicts.
Requirements
- Claude Code v2.1.80 or later, logged in via claude.ai (Pro / Max / Team — not Console / API key)
- Node.js 18+ and npm (for the Telegram plugin)
- A Telegram account if you want the phone bridge
Quickstart
git clone https://github.com/aerolalit/claudeclaw my-workspace
cd my-workspace
./start.sh
start.sh does everything on first run:
- Installs the Telegram plugin's npm dependencies.
- Registers the local
claudeclaw plugin marketplace with Claude Code.
- Installs the bundled Telegram plugin from that marketplace.
- Prompts you for a Telegram bot token (get one from @BotFather →
/newbot) and saves it to a gitignored .env.
- Spins up the bot, asks you to DM it once, captures the pairing code from your reply, and writes you to the allowlist.
- Launches Claude Code with the channel active.
Then send any message in Claude (e.g. hi). The interview kicks in, you answer a few questions, and the workspace is ready.
Subsequent runs skip every setup step — straight to launch.
To launch without the Telegram bridge: ./start.sh --no-tg.
File layout
claudeclaw/
├── CLAUDE.md ← framework instructions Claude Code reads on session start
├── start.sh ← one-command bootstrap + launch
├── README.md / LICENSE
├── .env / .env.example ← bot token (gitignored / template)
│
├── templates/ ← TRACKED: per-instance file templates
│ ├── BOOTSTRAP.md ← first-run interview script
│ ├── IDENTITY.md ← who the agent is
│ ├── SOUL.md ← how the agent talks
│ ├── USER.md ← who you are
│ └── HEARTBEAT.md ← recurring checks for the heartbeat loop
│
├── profile/ ← GITIGNORED: live per-instance files (auto-copied from templates/)
│
├── .claude/
│ ├── settings.json ← permissions + hooks
│ └── hooks/ ← Telegram streaming + reply formatting + lifecycle
│
├── .claude-plugin/
│ └── marketplace.json ← declares the local "claudeclaw" plugin marketplace
│
├── plugins/
│ └── telegram/ ← forked Telegram channel plugin (Apache-2.0)
│
└── .telegram/ ← GITIGNORED: per-instance Telegram state (access.json, bot.pid)
How it works
