Tiny missions · your agents stay on your machine 🎮 Play the free demo
LIGHTCLAW

Your pocket-sized coding-agent clubhouse

Hand off a task.
Keep the proof.

Send Codex or Claude a tiny mission from Telegram. Check the plan, give the go-ahead, then come back to real tests, a reviewable patch, and a private receipt.

Try the free demo Peek at the code

Alpha software with host access. Demo is deterministic, costs $0, and needs no Telegram or provider token.

LIGHTCLAW / A SAMPLE RUN local
TELEGRAM / YOU

“Add a health check, test it, and return only verified work.”

  1. 01 builderservice.py · workspace-write ready
  2. 02 verifierpython -m unittest blocked by 01
Human reviewed the plan ✅ GO!
✓ test passed ✓ patch ready ✓ receipt sealed ↶ undo scoped
3🧪 replayable demo stories
3🪶 base dependencies
10📦 clean-install packages
$0🎟️ fixture demo cost

The mission loop

Agents do the work.
You call the shots. ✋

Telegram is the review surface, not the moat. LightClaw stays narrow: one owner, one visible plan, a human approval, local execution, real checks, and a tidy receipt you can inspect later.

  1. Request

    Send up to 20 text messages or six voice transcriptions per Telegram user each minute (voice files: 20 MB max). Review the transcript before it runs, or start locally from the terminal.

    owner → goal

  2. Scope

    See paths, risk, capability profile, worker ownership, dependencies, and expected output.

    goal → DAG

  3. Approve

    Approve, edit, or deny before workers touch the dedicated task workspace. Each approval identifies a complete review; an old review cannot start its replacement.

    human gate

  4. Verify

    Acceptance checks decide whether work is accepted, repaired within bounds, or rejected.

    tests → status

  5. Review

    Keep the patch, artifacts, file hashes, receipt, cost/time evidence, and scoped recovery path. Use /agent runs for recent status, task previews, per-lane progress, requester-only cancellation of queued runs in group or private chats, and one-tap diffs for completed runs, including after a restart. Selected-file copies require the reviewed plan hash; sources are staged and existing targets backed up before replacement.

    proof → choice

Choose your tool

Not a remote terminal.
A governed handoff.

Direct mobile clients are better for steering every turn. LightClaw is for handing off a bounded mission, leaving the desk, and judging delivery from durable evidence.

USE A LIVE REMOTE CLIENT WHEN

You want to drive the session.

  • You need a full terminal or IDE on your phone.
  • You want to steer every prompt and tool call live.
  • A transcript and diff viewer are enough evidence.
USE LIGHTCLAW WHEN

You want to review the delivery.

  • Scope, paths, risk, and checks must be approved first.
  • Codex or Claude workers need bounded handoffs and repair limits.
  • The result must include a patch, checks, receipt, and recovery path.

Proof you can replay

Show me the work.
Show me the tests.

Each tab maps to a committed, sanitized Run Card and a replayable fixture. The cards prove local contracts only—not live provider quality, latency, or availability.

PHONE REQUEST → VERIFIED PATCH

A real Git patch with a real passing unit test.

The fixture creates a disposable Git-backed service, adds a health check, runs unittest, and records the request, approval, test output, and patch. Telegram shows the first text hunk inline, then attaches the complete patch for deeper review.

  • review/changes.patch
  • artifact/test-output.txt
  • receipt.json + receipt.md
REPLAY COMMAND 
lightclaw demo --scenario repo-task --json
🎬 24 SEC / SILENTRequest → approval → workers → evidence
Captioned LightClaw walkthrough showing a Telegram goal, reviewed DAG, workers, tests, artifacts, and receipt

Safety, in plain sight

Clear guardrails.
No magic claims.

Telegram, configured model providers, and external coding-agent CLIs remain separate boundaries. Receipts and workspaces stay local by default; the whole flow is not offline. Plan, voice, and trusted-run approvals expire even if the clock changes or the machine sleeps.

🔒 FAIL CLOSED

Owner access

Allowlisted bots accept commands only in private chats. Public groups require explicit public mode and no user allowlist. Conversation and memory are shared within each group session; public mode disables process-wide /heartbeat controls, shared skill-catalog changes, and /agent doctor. Public chats can use preinstalled ClawHub skills, while host-local skill content stays 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 with a topic ID keep separate sessions and memory. Local terminal chat needs no Telegram allowlist and uses a separate memory scope.

🧼 MINIMAL ENV

Worker isolation

Delegated workers get a minimal environment and owned task workspace. CLI output is bounded and truncation is surfaced. Telegram replies and saved long-result artifacts redact configured secrets and recognizable credential patterns; detection is heuristic. Automatic task Git commands disable configured hooks and filesystem monitors; staging and checkouts bypass configured filters, commits skip signing, and diffs ignore external helpers. Automatic edit retries omit common credential paths and detected secret-bearing files; generated edits cannot write common credential paths, chat file operations reject symlinked workspace paths, private metadata directories are created without following symlinks, and undo stays anchored to its opened workspace. Memory and job SQLite databases, including existing WAL/SHM sidecars, are restricted to owner-only permissions before use.

🧠 LOCAL MEMORY

Local, bounded memory

Chat history and session summaries live in namespaced local SQLite. They expire after 90 days by default; MEMORY_RETENTION_DAYS changes the limit. /clear removes the current chat or forum-topic session. Global /wipe_memory erases all saved chat memory when public access is disabled and a user allowlist is configured; public mode blocks it. In-flight chat and scheduled updates cannot restore cleared history.

⚠️ YOUR DECISION

Trusted execution

Trusted host runs show the complete task before the requester approves that specific review. Old or incomplete reviews cannot authorize a replacement request. Acceptance checks run as user-approved host subprocesses with a minimal environment, but LightClaw does not sandbox them; review commands and use OS/container isolation for untrusted repositories.

LightClaw architecture diagram with local host, provider, coding-agent, and public-export trust boundaries

Your first five minutes

Kick the tires.
Trust the evidence.

Clone, isolate, install, and run the deterministic repository story. It uses no Telegram account, provider credential, or paid model call.

Read the annotated quickstart →
🧰 TERMINAL / SAFE INSTALL macOS · Linux 
git clone https://github.com/OthmaneBlial/lightclaw.git
cd lightclaw
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
lightclaw demo --scenario repo-task --json
EXPECTEDaccepted receipt · passing test · reviewable patch
🌍 ALPHA / REAL-WORLD NOTES

Tried it? Tell us
how it went. 💌

The stable release is intentionally blocked until real external self-hosters test a fresh install. Failures and missing timings count as useful evidence.

📨 Share an alpha report