🐾 LightClaw

🐾 Tiny missions for local coding buddies.
Approve the plan. Come back to the proof. 🧾

🐾 Meet LightClaw · 🧪 Run the demo · 📦 Install · 🛡️ Security · 📝 Changelog

🚧 Alpha software with real host access. Telegram access fails closed. Local agents can change files. Read the security model before connecting a bot.

🎯 The short version

LightClaw is a self-hosted mission desk for Codex and Claude Code. Toss a goal over from Telegram, check the plan, approve or tweak it, then come back to real checks, a patch, and a private receipt.

You hold the approval button. Your local agent does the typing. The receipt keeps score. 🧾

🗺️ One mission, start to finish

1. 📩 Send a text or voice goal from Telegram.
2. 👀 Review paths, risks, worker roles, and acceptance checks.
3. 🙋 Approve, edit, deny, or cancel. No approval, no run.
4. 🤖 Local Codex or Claude workers run in a bounded task workspace.
5. 🧪 Inspect real checks, a Git patch, file evidence, a private receipt, and the scoped recovery path.

Nothing is pushed for you. No approval means no delegated run. A green check is evidence about a command, not a promise that generated code is correct.

🧪 Try the demo

The deterministic demo needs no Telegram account, API key, or paid model call. It creates a disposable repo, runs a real unit test, and saves a patch plus receipts.

git clone https://github.com/OthmaneBlial/lightclaw.git
cd lightclaw
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
lightclaw demo

Pick a story:

lightclaw demo --scenario repo-task
lightclaw demo --scenario memory
lightclaw demo --scenario multi-agent

🎮 Story	🧾 What the local replay shows
repo-task	A passing unit test, Git patch, artifact, and accepted receipt
memory	A synthetic fact recalled after a real SQLite restart
multi-agent	Dependency order, worker handoffs, a failed check, and one bounded repair

These are fixture stories, not live-model benchmarks. See the exact prompts and limits.

🛠️ Install for real work

LightClaw supports Python 3.10–3.14 on macOS and Linux. Use an isolated tool environment:

pipx install 'lightclaw-ai[openai] @ git+https://github.com/OthmaneBlial/lightclaw.git'
# or: uv tool install 'lightclaw-ai[openai] @ git+https://github.com/OthmaneBlial/lightclaw.git'

Replace openai with claude or gemini; use providers for all three SDK families. The demo itself needs no provider extra.

lightclaw demo
lightclaw onboard --configure
lightclaw doctor
lightclaw run

Your data stays in app-specific locations:

• 🔐 Config: ~/.config/lightclaw/config.env (0600)
• 🧠 Memory, skills, logs, receipts: ~/.lightclaw/
• 🧰 Owned task workspaces: ~/.lightclaw/workspace/

See the installation guide for Telegram bot setup, authorization, upgrades, undo, and uninstall.

🧩 What is in the toolbox?

• 📱 Telegram-first text and voice requests, plus terminal chat. Limits: 20 text messages and six voice transcriptions per Telegram user per minute.
• 🧭 Reviewed multi-agent plans with owned paths, dependencies, acceptance checks, and bounded repair.
• 🧪 Codex and Claude profiles: observe, workspace-write, and trusted-command.
• 🧾 Private JSON/Markdown receipts with commands, results, hashes, artifacts, and recovery context.
• 📚 Paginated per-chat run history via /agent runs, with status and per-lane progress. Pages and completed-run diff buttons stay stable through new jobs and bot restarts. Original requesters can cancel queued runs from group or private history; rerun the command to refresh.
• 📱 Phone-friendly diff previews, full patch attachments, local accept/reject, and selective file apply.
• 🧠 Namespaced SQLite FTS5 memory and persisted summaries with 90-day default retention, export, and selective delete.
• 🧰 Permission-manifest skills, inactive by default, with provenance and hash review.
• 🔌 Provider routes for OpenAI, xAI, Anthropic, Gemini, DeepSeek, and Z-AI.

🛡️ Safety, without magic claims

• Telegram startup requires a numeric user allowlist or explicitly acknowledged public-group mode. Allowlisted bots reject group chats. Public-group conversation and memory stay within each session; global /wipe_memory, process-wide /heartbeat, shared skill-catalog changes, and /agent doctor are disabled in public mode. Public chats can use preinstalled ClawHub skills, while host-local skills stay private. /agent doctor stays private because its output can reveal host authentication status and local paths. Only the requester can use or replace a pending plan, voice request, or trusted-run review, cancel queued or active runs, and accept or reject results; all group members can view run diffs. Host CLI retries require a resumable job and an idempotent, resumable lane. Forum topics have separate sessions, and scheduled messages return to their topic. Local terminal chat uses a separate memory scope.
• Delegated workers get a minimal environment without Telegram/provider keys. Workspaces, output, callbacks, files, receipts, and SQLite permissions have explicit bounds.
• Plans and trusted runs require approval of a specific complete review; approvals expire if the clock changes or the machine sleeps. Trusted host runs show the complete task and require the requester to approve that specific review.
• Acceptance commands run on your host and are not sandboxed by LightClaw. Review them and use OS/container isolation for untrusted repositories.
• Secret detection is heuristic. External agent CLIs and hosted providers remain separate trust boundaries.

Read the threat model, privacy notes, and approval guide before using real repositories.

🧭 Is it your kind of tool?

Reach for…	When you want…
A remote-control client	A live terminal or IDE and control over every turn
A general agent gateway	A broad personal assistant across many channels
LightClaw	A bounded local coding task with plan approval, checks, patch, receipt, and recovery path

LightClaw is local-first and lightweight. It is not a hosted multi-tenant service, fully local inference, or a guarantee that model-generated changes are correct.

📚 Take a look around

• 🗺️ Docs map · Quickstart · Install and upgrade
• 🙋 Telegram approvals · Job control · Run receipts
• 🏗️ Architecture · Threat model · Privacy
• 🔌 Provider support · Multi-agent guide · Reproducible stories
• 🧾 Roadmap · Release evidence audit · Bench data

🧑‍🔧 Hacking on LightClaw

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements-pip.txt
python -m pip install --require-hashes -r requirements-dev.txt
python -m pip install --no-deps --no-build-isolation -e .
python scripts/quality.py

That is the canonical local quality gate: lint, docs, architecture/runtime budgets, dependency audit, the full pytest suite, demo replays, and clean-wheel checks. GitHub CI, CodeQL, OpenSSF Scorecard, and showcase workflows are disabled; run the local gate before pushing.

Read contributing, support, and the Code of Conduct before opening a ticket.

🌱 Alpha status

No stable release yet. The first stable release waits for real external self-hosters to try a fresh install. If you test it, send a privacy-bounded alpha report. Please leave prompts, receipts, paths, identities, and tokens out of the report.

Follow development notes and release evidence for updates. Failures and missing timings are useful data too. 🪲

📄 License

MIT — bring your own bot, agents, and good judgment. 🐾