LIGHTCLAW

01 Control local Codex and Claude coding agents from Telegram

Send the mission.
Keep the proof.

Review the scope before local agents run. Keep the real checks, reviewable patch, private run receipt, and deliberate undo path after the chat scrolls away.

Run the $0 demo Inspect the source

Alpha software with host access. No Telegram or provider token is needed for the deterministic demo.

LC / RUN-0142 local
PHONE / OWNER

“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
Scope reviewed APPROVED
✓ test passed ✓ patch ready ✓ receipt sealed ↶ undo scoped
3token-free stories
3direct base dependencies
10clean-wheel distributions
$0fixture cost

02 The control loop

Autonomy is useful.
Review is non-negotiable.

Telegram is the review surface, not the moat. LightClaw stays narrow: one owner, one visible contract, explicit capability, local execution, observable checks, and evidence you can inspect later.

  1. 01

    Request

    Send a text or voice goal from Telegram, or start locally from the terminal.

    owner → goal
  2. 02

    Scope

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

    goal → DAG
  3. 03

    Approve

    Approve, edit, or deny before workers touch the dedicated task workspace.

    human gate
  4. 04

    Verify

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

    tests → status
  5. 05

    Review

    Keep the patch, artifacts, file hashes, receipt, cost/time evidence, and scoped recovery path.

    proof → choice

02B Choose the right 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.

03 Replayable proof

Inspect the receipt.
Not the promise.

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.

  • 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

04 Explicit boundaries

Local evidence.
Every external edge named.

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.

FAIL CLOSED

Owner access

An empty Telegram allowlist blocks startup. Public mode requires a separate explicit acknowledgement.

MINIMAL ENV

Worker isolation

Delegated workers do not inherit provider or Telegram secrets and run inside an owned task workspace.

YOUR DECISION

Trusted execution

Trusted host commands widen the boundary and require a separate confirmation. They are not called sandboxed.

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

05 Five-minute proof

Try the loop before
you trust the claim.

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 / EXTERNAL EVIDENCE

Run it on your machine.
Tell us what actually happened.

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

Submit a bounded alpha report