You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,12 +12,12 @@ A [skill](https://code.claude.com/docs/en/skills) is a markdown file in `.claude
12
12
13
13
A PR that contributes a skill should not modify any source files.
14
14
15
-
Your skill should contain the **instructions** Claude follows to add the feature—not pre-built code. See `/add-telegram` for a good example.
15
+
Your skill should contain the **instructions** Claude follows to add the feature — not pre-built code. See `/add-telegram` for a good example.
16
16
17
-
### Why?
17
+
### Testing
18
18
19
-
Every user should have clean and minimal code that does exactly what they need. Skills let users selectively add features to their fork without inheriting code for features they don't want.
19
+
Test your skill by running it on a fresh clone before submitting. All skills are security-scanned before installation.
20
20
21
-
### Testing
21
+
##Community
22
22
23
-
Test your skill by running it on a fresh clone before submitting.
23
+
Join the [OpenClawOS Telegram group](https://t.me/+8qJbqxzBQAZkYTNk) for discussion.
An AI agent that lives on its own computer, has its own accounts, and works as your always-on co-worker.
18
-
19
-
You interact with it like a person — voice notes on Telegram, mentions in WhatsApp groups, or just texting. It knows how you like to communicate, reads your email, monitors your services, and runs tasks on a schedule. And you customise everything through Claude Code, exactly the way you already work.
20
-
21
-
## Why this exists
22
-
23
-
**OpenClaw** is beautiful. Watching your agent talk to other agents, self-iterate, install things, and work stuff out for itself is genuinely mind-bending. But it's 500,000 lines of code, the setup is an approximation of the Claude Code terminal that doesn't quite work, and making changes that don't break everything is non-trivial. It's like driving a classic car — charming when it works, but you're fixing it more than driving it.
24
-
25
-
**NanoClaw** is elegant. 400 lines of core code, completely customisable, works out of the box. But it runs in containers, which is great for security on a shared machine — less great if you want your agent to actually *do things* across your system.
26
-
27
-
**GhostClaw** is the middle ground. NanoClaw's simplicity and skill system, with the freedom and functionality of OpenClaw. No containers — your agent runs bare metal on a dedicated machine with full access to everything. Add skills the same way you add capabilities in Claude Code. Compatible with both NanoClaw and OpenClaw skill ecosystems.
28
-
29
-
If you're already an advanced Claude Code user and want an agent that runs wild on its own hardware, this is for you.
30
-
31
-
## What it does
32
-
33
-
-**Its own Telegram identity** — message it like a person. No slash commands, no trigger needed in DMs.
34
-
-**WhatsApp group chats** — add it to any group. Responds when mentioned, stays quiet otherwise.
35
-
-**Voice notes** — send voice messages, it transcribes and responds.
36
-
-**Scheduled tasks** — "check Hacker News every morning" or "remind me to review PRs every Friday at 3pm". Natural language, cron, or intervals.
37
-
-**Per-group personality** — each chat gets its own tone, memory, and rules. Direct in your DM, casual in the group chat.
38
-
-**Email** — reads and sends Gmail. Picks up verification codes, flags urgent messages, sends summaries.
39
-
-**Health monitoring** — heartbeat checks on disk space, services, logs. Daily briefings. Silent unless something needs attention.
40
-
-**Layer any Claude Code skill onto your bot** — anything you can do in Claude Code, you can add to your agent. NanoClaw skills, OpenClaw skills, or your own. Every install is automatically security-scanned.
41
-
-**Mission Control dashboard** — built-in web UI for monitoring chats, tasks, research runs, and agent health.
42
-
-**Fully modifiable from Claude Code** — every behaviour, every personality file, every integration. Customise exactly the way you already work.
17
+
A bare-metal AI agent that runs on your hardware, under your control. Single Node.js process, SQLite for state, Claude as a child process. No containers, no cloud, no orchestration. Telegram, WhatsApp, email, cron. 10 minutes to set up.
43
18
44
19
## Install
45
20
46
-
On the machine you want your agent to live on, open a terminal and install [Claude Code](https://claude.ai/download) if you haven't already:
47
-
48
-
```bash
49
-
npm install -g @anthropic-ai/claude-code
50
-
```
51
-
52
-
Then:
53
-
54
21
```bash
22
+
npm install -g @anthropic-ai/claude-code # if you haven't already
Everything below ships with every install. No extras to configure.
86
42
87
-
Skills are security-scanned before installation. Build your own or pull from the NanoClaw/OpenClaw ecosystem — they're compatible.
43
+
### Channels
88
44
89
-
## The soul system
45
+
-**Telegram** — DM it like a person. In groups, responds when mentioned. Voice notes supported. This is the primary interface.
46
+
-**WhatsApp** — group chat support. Scan QR to connect. Stays quiet until mentioned.
90
47
91
-
Each chat has a `CLAUDE.md` that defines the bot's personality for that context. Your main channel might say:
48
+
### Core capabilities
92
49
93
-
> Be direct. No emoji. Have opinions. Don't say "there are several approaches" — say "this is the move, here's why."
50
+
-**Web research** — Perplexity-powered search and deep research built in. Ask anything current, it searches and cites sources.
51
+
-**Ralph loops** — autonomous multi-task engine. Hand it a checklist, it works through tasks one by one. Leave it overnight, come back to finished work. Outputs editable reports.
52
+
-**Scheduled tasks** — "check Hacker News every morning" or cron syntax. Natural language or precise, your call.
53
+
-**Per-group personality** — each chat gets its own `CLAUDE.md` defining tone, memory, and rules. Edit the file, personality changes instantly.
94
54
95
-
A group chat with friends might say:
55
+
### Mission Control
96
56
97
-
> Be casual and funny. Only respond when mentioned. Keep it short.
57
+
Built-in dashboard at `localhost:3333`. Real-time activity feed, task scheduling, soul editing, research runs with editable output. Send messages as the bot. SSE live updates, zero extra dependencies.
98
58
99
-
Edit the file, the personality changes instantly. The setup wizard builds your initial soul automatically.
59
+
<palign="center">
60
+
<imgsrc=".github/dashboard-preview.png"width="700"alt="Mission Control dashboard">
61
+
</p>
100
62
101
-
##How it works
63
+
### Architecture
102
64
103
65
```
104
-
You (Telegram/WhatsApp) --> GhostClaw --> Claude (Agent SDK) --> Response
66
+
You (Telegram/WhatsApp) → GhostClaw → Claude (Agent SDK) → Response
105
67
```
106
68
107
-
One Node.js process. SQLite for state. Claude runs as a child process. No containers, no orchestration, no cloud infrastructure. Your bot runs directly on the host with full system access — that's the point.
69
+
One process. SQLite state. Claude runs as a direct child process. No containers, no Docker, no Kubernetes. Your bot runs on the host with full system access — that's the point.
70
+
71
+
## Optional skills
72
+
73
+
Layer on more capabilities from Claude Code. One command each, security-scanned before install.
Build your own skills or use compatible ones from the NanoClaw/OpenClaw ecosystem. The skills engine (originally NanoClaw's, forked and extended) handles three-way merging, dependency tracking, and rollback. Every skill is security-scanned before installation.
108
89
109
90
## Configuration
110
91
111
-
All config lives in `.env`. The setup wizard creates this for you.
92
+
All config lives in `.env`. The setup wizard creates this.
112
93
113
94
| Variable | Required | Description |
114
95
|----------|----------|-------------|
@@ -117,16 +98,16 @@ All config lives in `.env`. The setup wizard creates this for you.
117
98
|`ASSISTANT_NAME`| Yes | Bot name (trigger word in groups) |
118
99
|`TELEGRAM_BOT_TOKEN`| Yes | From @BotFather|
119
100
|`GHOSTCLAW_MODEL`| No | Default: `claude-sonnet-4-6`. Also: `claude-opus-4-6`, `claude-haiku-4-5-20251001`|
120
-
|`ELEVENLABS_API_KEY`| No | For voice transcription and voice replies |
121
-
|`ELEVENLABS_VOICE_ID`| No | Voice ID for TTS replies (elevenlabs.io/voice-library) |
101
+
|`ELEVENLABS_API_KEY`| No | For voice transcription and replies |
102
+
|`ELEVENLABS_VOICE_ID`| No | Voice ID for TTS (elevenlabs.io/voice-library) |
122
103
|`TELEGRAM_ONLY`| No | Set `true` to skip WhatsApp |
123
104
|`GMAIL_MCP_ENABLED`| No | Set `1` for email integration |
124
105
125
106
*One of `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` is required.
126
107
127
108
## Service management
128
109
129
-
The setup wizard configures this automatically. For manual control:
That's it. It backs up your current state, pulls the latest, runs migrations, rebuilds, and restarts the service. If anything goes wrong, it gives you a rollback tag.
Backs up current state, pulls latest, runs migrations, rebuilds, restarts. Gives you a rollback tag if anything goes wrong.
160
132
161
133
## FAQ
162
134
163
135
**What does it cost?**
164
-
165
-
Your Claude subscription (Max or API) and optionally ElevenLabs for voice transcription and replies. No platform fees.
136
+
Your Claude subscription (Max or API) and optionally ElevenLabs for voice. No platform fees.
166
137
167
138
**Is this secure?**
168
-
169
-
The bot has full access to its machine. That's the point — run it on dedicated hardware with fresh accounts, not your daily driver. Skills are security-scanned before installation.
170
-
171
-
**What's the relationship to NanoClaw and OpenClaw?**
172
-
173
-
GhostClaw is a fork of [NanoClaw](https://github.com/qwibitai/nanoclaw) with containers removed and OpenClaw-inspired features added (heartbeat, briefings, email, monitoring). NanoClaw skills work without modification. Think of it as NanoClaw's simplicity with OpenClaw's ambition.
139
+
The bot has full access to its machine. That's the design — run it on dedicated hardware with fresh accounts, not your daily driver. Skills are security-scanned before install.
174
140
175
141
## Community
176
142
177
-
Join the [OpenClawOS Telegram group](https://t.me/+8qJbqxzBQAZkYTNk) to share problems, suggestions, or just see what others are building.
143
+
Join the [OpenClawOS Telegram group](https://t.me/+8qJbqxzBQAZkYTNk) to share problems, suggestions, or see what others are building.
178
144
179
145
## Credits
180
146
181
-
Fork of [NanoClaw](https://github.com/qwibitai/nanoclaw) by [qwibitai](https://github.com/qwibitai). Core architecture, skills engine, and agent runner are their work.
147
+
Originally forked from [NanoClaw](https://github.com/qwibitai/nanoclaw) by [qwibitai](https://github.com/qwibitai). Skills engine built on NanoClaw's three-way merge system.
0 commit comments