Lightclaw

Name: Lightclaw
Rating: 3.5 (1 reviews)
Author: OthmaneBlial

By OthmaneBlial ⭐ 1 stars 👁 37 views ▲ 0 votes

🦞 LightClaw: The Featherweight Core of OpenClaw — Your AI Agent in a Tiny Codebase

GitHub

Install

pip install -r

README

<div align="center">

  <h1>🦞 LightClaw</h1>

  <h3>The Featherweight Core of OpenClaw — Your AI Agent in a Tiny Codebase</h3>

  <p><strong>OpenClaw-inspired Python AI agent</strong> for Telegram, long-term memory, and multi-provider LLM support.</p>

  <p>
    <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white" alt="Python">
    <img src="https://img.shields.io/badge/Core-lean-brightgreen" alt="Core">
    <img src="https://img.shields.io/badge/Repo-lightweight_core-blue" alt="Repo">
    <img src="https://img.shields.io/badge/LLM_Providers-6-purple" alt="Providers">
    <img src="https://img.shields.io/badge/RAM-<50MB-orange" alt="RAM">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  </p>

  <p><i>Fork it. Hack it. Ship it. No framework tax.</i></p>

</div>

---

## Why LightClaw Exists

**OpenClaw** is a powerful, full-featured AI agent platform — but it's also *big*. Dozens of packages, multiple channels, tool registries, message buses, plugin systems. It's built for scale and enterprise use.

**LightClaw** is the opposite. It's the *distilled essence* of the OpenClaw idea, stripped down to the atomic minimum:

If you are searching for an **OpenClaw alternative**, **OpenClaw in Python**, or a **self-hosted Telegram AI assistant with memory**, this repository is built for that exact use case.

```
OpenClaw:     Large multi-app monorepo │ TypeScript-first │ many channels + platform apps
LightClaw:    Focused Python core       │ Telegram-first   │ 6 providers │ lightweight runtime
```

As of February 2026, the official OpenClaw repository shows 12k+ commits and 200k+ GitHub stars.

Think of LightClaw as **the starter engine** — the part of a rocket that ignites first. It contains the core DNA of OpenClaw (LLM routing, memory, conversational agent) but removes everything else. No message bus. No plugin registry. No tool orchestration. Just a direct pipeline:

```
📱 Telegram Message → 🧠 Memory Recall → 🤖 LLM → 💡 HTML Format → 💬 Reply
```

## Looking for OpenClaw?

- OpenClaw GitHub: https://github.com/openclaw/openclaw
- OpenClaw docs: https://docs.openclaw.ai/
- LightClaw focuses on the lightweight Python path: Telegram-first, memory-enabled, and easy to fork.

## Who Is This For?

<table>
  <tr>
    <td>🧑‍💻 <b>Builders</b></td>
    <td>You want to build <i>your own</i> AI assistant without inheriting a massive codebase. Fork LightClaw, add what you need, nothing more.</td>
  </tr>
  <tr>
    <td>🎓 <b>Learners</b></td>
    <td>You want to understand how AI agents work — memory, RAG, LLM routing — in code you can read in 30 minutes.</td>
  </tr>
  <tr>
    <td>⚡ <b>Minimalists</b></td>
    <td>You need a personal AI bot on a $5/month VPS. No Docker. No build steps. Just <code>./lightclaw run</code>.</td>
  </tr>
  <tr>
    <td>🔬 <b>Tinkerers</b></td>
    <td>You want to experiment with different LLM providers, memory strategies, or prompt engineering without fighting a framework.</td>
  </tr>
</table>

## The Core Idea

> **OpenClaw is the Industrial Complex. LightClaw is the Precision Workbench.**
>
> You don't need an entire industrial complex to build a custom tool. You need a workbench with the right instruments. LightClaw gives you exactly that — a clean, readable, forkable foundation that does one thing well: **connect you to an AI through Telegram, with infinite memory.**
>
> Add Discord support? Drop in a file. Need tool calling? Add a function. Want vector search with FAISS? Swap out 20 lines in `memory.py`. The codebase is small enough that *you own it completely*.

## Features

🧠 **Infinite Memory** — Every conversation is persisted in SQLite with TF-IDF vector embeddings. The bot recalls relevant context from days, weeks, or months ago via semantic search (RAG).

🔌 **6 LLM Providers** — OpenAI (ChatGPT), xAI (Grok), Anthropic (Claude), Google (Gemini), DeepSeek, Z-AI (GLM). Switch providers by changing one line in `.env`.

📱 **Telegram Native** — Polling-based bot with "Thinking… 💭" placeholders, HTML-formatted responses, typing indicators, and rich commands.

🎭 **Customizable Personality** — Edit `.lightclaw/workspace/SOUL.md`, `IDENTITY.md`, and `USER.md` to shape your bot's character, identity, and personal context.

🧩 **Skill System (ClawHub + Local)** — Install skills from `clawhub.ai`, activate them per chat with `/skills`, and create your own custom skills locally.

🤖 **Local Agent Delegation** — Delegate large build tasks to installed local coding agents (`codex`, `claude`, `opencode`) with `/agent`, while LightClaw reports workspace change summaries back in Telegram.

🛠️ **Workspace File Operations + Diff Summaries** — Large code is written directly to `.lightclaw/workspace` (not dumped in chat). LightClaw applies create/edit operations, then returns concise operation + diff line summaries.

🧱 **Truncation Recovery for Large Files** — If an LLM response is cut mid-file, LightClaw attempts continuation/repair passes (including HTML completion) before finalizing the saved file.

🎙️ **Voice Messages** — Automatic voice transcription via Groq Whisper (optional). Send a voice note and the bot transcribes + responds.

📸 **Photo & Document Support** — Send images and files — the bot acknowledges them and processes captions through the agent loop.

🧹 **Smart Context Management** — Auto-summarization when conversations grow too long, plus emergency context window compression with retry on overflow.

📦 **Small Core** — `main.py` + `memory.py` + `providers.py` + `config.py` + `lightclaw` CLI. No hidden complexity. No abstractions for the sake of abstractions.

🚀 **Instant Startup** — No compilation, no Docker, no build pipeline. `./lightclaw run` and you're running.

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                      main.py                                      │
│                                                                  │
│  ┌─────────────────────────────────────────┐                     │
│  │ markdown_to_telegram_html()             │  MD → HTML converter│
│  │ load_personality()                      │  .lightclaw/workspace/*.md │
│  │ build_system_prompt()                   │  Dynamic prompts    │
│  │ transcribe_voice()                      │  Groq Whisper       │
│  └─────────────────────────────────────────┘                     │
│                                                                  │
│  LightClawBot                                                    │
│  ├── handle_message()    ← text messages                         │
│  ├── handle_voice()      ← voice transcription                   │
│  ├── handle_photo()      ← image handling                        │
│  ├── handle_document()   ← file handling                         │
│  ├── _process_user_message()                                     │
│  │     │                                                         │
│  │     ├─ 1. Send "Thinking… 💭"  placeholder                   │
│  │     ├─ 2. Recall memories      ◄── memory.py                  │
│  │     ├─ 3. Build prompt              SQLite + TF-IDF RAG      │
│  │     ├─ 4. Call LLM + retry     ◄── providers.py               │
│  │     ├─ 5. Edit placeholder          6 providers unified       │
│  │     └─ 6. Summarize if needed                                 │
│  │                                                               │
│  └── cmd_start/help/clear/wipe_memory/memory/recall/skills/agent/show │
│                                                                  │
│  config.py ◄── .env file                                          │
└──────────────────────────────────────────────────────────────────┘
```

## Quick Start

### ⚡ One-Command Setup (Recommended)

```bash
git clone https://github.com/OthmaneBlial/lightclaw.git && cd lightclaw && bash setup.sh
```

The interactive setup wizard will walk you through:
1. Choosing your AI provider (OpenAI, xAI, Claude, Gemini, DeepSeek, Z-AI)
2. Entering your API key
3. Creating a Telegram bot via @BotFather (step-by-step guide)
4. Optional voice transcription setup
5. Auto-start your bot 🚀

### 🔧 Manual Setup

```bash
git clone https://github.com/OthmaneBlial/lightclaw.git
cd lightclaw
pip install -r requirements.txt
```

**2. Onboard (recommended)**

```bash
./lightclaw onboard
```

This creates:
- `.env` (if missing)
- `.lightclaw/workspace/` (runtime personality files)
- `.lightclaw/lightclaw.db` (runtime DB path)

Then edit `.env` with your API key and Telegram bot token:

```env
# Choose your provider: openai | xai | claude | gemini | deepseek | zai
LLM_PROVIDER=openai
LLM_MODEL=latest
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=

# Get a token from @BotFather on Telegram
TELEGRAM_BOT_TOKEN=123456:ABC...

# Optional: restrict to your user ID (get it from @userinfobot)
TELEGRAM_ALLOWED_USERS=123456789

# Optional tuning for large code/file generation
MAX_OUTPUT_TOKENS=12000
LOCAL_AGENT_TIMEOUT_SEC=1800

# Optional delegated local-agent safety policy
LOCAL_AGENT_SAFETY_MODE=off
LOCAL_AGENT_DENY_PATTERNS=

# Skills (default registry)
SKILLS_HUB_BASE_URL=https://clawhub.ai
SKILLS_STATE_PATH=.lightclaw/skills_state.json
```

**3. Customize (Optional)**

Edit the personality files in `.lightclaw/workspace/`:

```
.lightclaw/workspace/
├── IDENTITY.md   # Bot's name, purpose, philosophy
├── SOUL.md       # Personality traits and values
└── USER.md       # Your preferences and personal context
```

**4. Run**

```bash
./lightclaw run
```

That's it. Open Telegram, find your bot, say hello. 🦞

> Development mode still works with `python main.py` (it now defaults to `.lightclaw/workspace`).

## CLI Commands

```bash
lightclaw onboard   # initialize .env + .lightclaw/workspace in current directory
lightclaw onboard --reset-env  # reset existing .env from latest template
lightclaw onboard --configure  # guided provider/model/key setup on current .env
lightclaw run       # ru

... (truncated)

tools