Built by AI · Maintained by one person. Every line of code, every test, every commit was written by an AI agent — the human author supervises, reviews goals, and guides direction.

⚡ Why ClawLite?

• Truly local-first — runs entirely on your machine; no cloud required
• Real channel adapters — Telegram, Discord, Email, WhatsApp, Slack, IRC
• Persistent memory — hybrid BM25 + vector search, temporal decay, consolidation loop
• Self-healing runtime — heartbeat supervisor, dead-letter replay, automatic provider failover
• Batteries included — 25+ skills, streaming responses, operator dashboard

🏁 Quickstart

# Clone and install
git clone https://github.com/eobarretooo/ClawLite.git
cd ClawLite
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[browser,telegram,media,runtime]"

# Configure interactively
clawlite configure

# Start the gateway + dashboard
clawlite gateway

Open http://127.0.0.1:8787 for the live dashboard.

# Or talk directly from the terminal
clawlite run "hello — what can you do?"

Docker:

bash scripts/docker_setup.sh

Android / Termux: see docs/TERMUX_PROOT_UBUNTU.md

✨ Features

💬 Channels

🤖 Providers

Powered by LiteLLM — swap models without changing code.

OpenAI-compatible: OpenAI · Azure OpenAI · Gemini · Groq · DeepSeek · OpenRouter · SiliconFlow · Cerebras · Mistral · Moonshot · xAI · custom/<model>

Anthropic-compatible: Anthropic · MiniMax · Kimi

Local: Ollama · vLLM

OAuth (free-tier): gemini-oauth · qwen-oauth · openai-codex

clawlite provider login gemini-oauth   # authenticate
clawlite provider status gemini-oauth  # check status

The packaged dashboard Automation tab now also exposes Inspect provider cache, which reuses the same cached last_live_probe / last_capability_probe surface through the live gateway control plane. The Delivery tab now also renders a compact Channel posture card sourced from additive channels.posture data in GET /api/dashboard/state, so queue pressure, dispatcher trouble, recovery trouble, and dead-letter backlog are visible without reading the raw delivery/recovery JSON blocks. The Knowledge tab now also surfaces managed-marketplace blocker drill-down for the visible slice, so missing env/config/bin/policy blockers are visible without scanning each managed skill row manually.

Full auth details → docs/providers.md

🏛️ Architecture

User Message
    -> Channel Adapter (Telegram / Discord / CLI / ...)
    -> FastAPI Gateway :8787
    -> Agent Engine (memory + tools + LLM stream)
    -> Response streamed back + memory updated

🛠️ Development

pip install -e ".[all]"
python -m pytest tests/ -q --tb=short   # full suite (2090 passed, 1 skipped)
python -m ruff check --select=E,F,W .   # lint

CI runs on Python 3.10 and 3.12.

The packaged dashboard Automation tab now also exposes compact Runtime Posture, Runtime Policy, Provider Health, and Provider Budget cards, surfacing additive runtime.posture, runtime.policy, provider.health, and provider.budget signals from GET /api/dashboard/state so operators can quickly see autonomy, wake, approval, canary scope, config-versus-runtime policy drift, provider suppression/cache drift, and whether the current provider issue is quota, rate limiting, or a non-budget block without opening full diagnostics. The Delivery tab now also adds a compact Channel posture card sourced from additive channels.posture, so queue pressure, dispatcher trouble, recovery trouble, and dead-letter backlog are visible without mentally recombining the raw channel-manager diagnostics blocks. The Knowledge tab now also adds Managed blockers and Managed remediation cards on top of the existing managed marketplace inventory so skill blockers are grouped by kind and each visible blocker slice exposes the next safe remediation path instead of staying as row-by-row hints only, and the Memory card now also carries additive memory.remediation guidance so the next safe memory action is visible next to doctor/overview/quality instead of being inferred from raw counters alone. The Tools tab now also surfaces latest approval-audit reason, bounded request-scoped reason history, and a compact retention summary so operators can tell when the in-memory audit slice is truncated before exporting or handing it off.
When a user explicitly asks in chat, ClawLite can now also use the internal gateway_admin tool to inspect the active config or apply a bounded config patch, schedule a self-restart, and post a confirmation back to the same Telegram chat/topic after the gateway comes back up. That admin path is now schema-aware as well: it can look up snake_case config paths before editing, dry-run safe presets through config_intent_preview, raw config patches are fail-closed to a small allowlist of safe tool-tuning fields, and common low-risk changes can go through config_intent_and_restart presets such as default tool timeout, per-tool timeout, workspace restriction, loop-detection tuning, and bounded tools.web.* fetch-limit updates instead of hand-built patch payloads. It stays blocked in background/internal sessions and keeps the restart notice persisted when post-boot delivery fails, so the confirmation is not silently lost on the first transient channel error.

🖥️ CLI Reference

clawlite configure              # interactive setup wizard; reuses local runtimes, suggests the detected provider when clear, reuses detected credentials, skips redundant env-backed key prompts, surfaces plausible backends when setup is ambiguous, and lets quickstart skip redundant local-runtime/model prompts on the resolved happy path
clawlite --profile prod configure  # save setup changes to config.prod.json
clawlite --profile prod dashboard --no-open  # reopen the control plane against config.prod.json
clawlite gateway                # start HTTP/WS gateway
clawlite run "..."              # one-shot agent call
clawlite status                 # runtime health summary
clawlite diagnostics            # full diagnostic snapshot

clawlite skills list            # list available skills
clawlite skills doctor          # diagnose broken skills
clawlite skills validate        # refresh + diagnose live skills state
clawlite skills install <slug>  # install from marketplace

clawlite tools approvals        # list pending tool approvals
clawlite tools approval-audit   # inspect recent approval/grant audit rows
clawlite tools approval-audit --request-id req-1   # drill down one reviewed request/grant
clawlite tools approval-audit --format ndjson > audit.ndjson   # export bounded audit rows
clawlite tools approve <id>     # approve a tool call
clawlite tools reject <id>      # reject a tool call

Full CLI reference → docs/OPERATIONS.md

📚 Docs

🤝 Contributing

1. Fork the repo and create a feature branch
2. Follow the existing code style (ruff, typed Python 3.10+)
3. Add tests for new functionality
4. Open a PR with a clear description

See CONTRIBUTING.md for full guidelines. Join the Discord for discussion.

📄 License

MIT — see LICENSE.