LightClaw Architecture
August 23, 2026 ยท View on GitHub
LightClaw is a Telegram-first control surface around hosted model providers and local coding-agent CLIs. The public top-level modules remain compatibility facades; stable implementation domains live under core/.
Runtime domains
| Domain | Owner | Does not own |
|---|---|---|
| Provider protocol | core/llm/ | Telegram handlers, persistence, vendor SDK behavior outside adapters |
| Telegram command routing | core/bot/commands/agent_router.py | Plan normalization, worker acceptance, durable execution |
| Multi-agent planning | core/bot/delegation/planning.py | Process execution, job state, acceptance |
| Worker task contracts | core/bot/delegation/tasks.py | Scheduler state or process lifecycle |
| Acceptance | core/bot/commands/agent_acceptance.py | Planning and worker execution |
| Durable execution coordination | core/bot/commands/agent_execution.py | Acceptance rules and plan normalization |
| Local process execution | core/bot/delegation/execution.py | Telegram command routing and planning |
| Job persistence | core/jobs.py | UI rendering and model planning |
| Receipts/artifacts | core/receipts.py, core/artifacts.py | Execution authorization |
| Filesystem state primitives | core/fs.py | Domain policy |
Compatibility compositions in core/bot/commands/agent.py and core/bot/delegation/multi.py preserve existing mixin imports without recombining implementation responsibilities.
Contribution map
| Change | Start here | Required evidence |
|---|---|---|
| Authentication, capabilities, process environment | core/security.py, core/bot/delegation/execution.py | Security regression and threat-boundary note |
| Telegram command behavior | core/bot/commands/, core/bot/handlers.py | Authorized and unauthorized handler tests |
| Plans and worker contracts | core/bot/delegation/planning.py, tasks.py | Deterministic DAG/fixture test |
| Jobs, receipts, files, workspaces | core/jobs.py, core/receipts.py, core/fs.py, core/workspaces.py | Restart, redaction, symlink, or ownership test as applicable |
| Memory | memory.py | Namespace/retention test and evaluation when retrieval changes |
| Skills | skills.py | Manifest, hash, provenance, and permission test |
| Provider adapters | core/llm/ | Recorded fixture plus shared contract test |
| CLI/install lifecycle | lightclaw_cli.py, core/paths.py | Isolated-home or clean-wheel smoke test |
Run python scripts/quality.py after changing any domain. Changes that cross multiple
rows should explain why a smaller boundary is insufficient.
Enforced budget
The versioned core budget caps total runtime lines, module/function size, AST branch points, direct dependencies, cold-start p95, and wheel size. Module boundaries assert separate planning, execution, persistence, rendering, and acceptance owners.
python scripts/check_architecture.py --check
python -m bench.runtime_footprint --output /tmp/lightclaw-runtime-footprint.json
CI rejects stale metrics and budget overruns. Raising a limit requires an explicit architecture rationale; limits are not silently moved to make a change pass. Release builds attach a machine-readable runtime footprint containing cold-start samples, direct dependency list, and wheel size.