A lightweight AI agent framework with identity awareness

Build AI agents that know who they are and can act autonomously with durable memory

Quick Start • Features • Documentation • Providers • Changelog

Clawlet is a lightweight agent framework designed for developers who want:

• 🏠 Local-First - Run Ollama or LM Studio, no cloud required
• 🎭 Identity Awareness - Agents read SOUL.md, USER.md, MEMORY.md
• 🔧 Simple Setup - Interactive onboarding in under 2 minutes
• 📊 Built-in Dashboard - React UI for monitoring and management
• 🔒 Security-First - Hardened shell tool, safe command execution
• 🌐 Web Search - Brave Search API integration for up-to-date information
• 🔌 Skills System - Modular capabilities with portable SKILL.md-based workflows

• Identity System - Define your agent's personality, values, and memory
• 18+ LLM Providers - Cloud and local options for every budget
• Hybrid Memory - SQLite-backed structured memory, curated MEMORY.md, and daily episodic notes
• Tool System - File ops, shell commands, structured HTTP, web search
• Models Cache - Daily auto-updating cache with disk persistence
• Skills System - Extend agent capabilities with modular skills
• Heartbeat State - HEARTBEAT.md-driven heartbeat loop with persisted state

• Health Checks - Monitor providers, storage, channels
• Rate Limiting - Sliding window + token bucket algorithms
• Config Validation - Pydantic-based with environment variable support
• Retry Logic - Exponential backoff with circuit breaker
• Webhooks - Receive events from GitHub, Stripe, and custom sources
• Scheduling - Cron-based task scheduling with timezone support

• Telegram - Bot integration
• Discord - Bot integration
• WhatsApp - Business API integration
• Slack - Socket Mode and HTTP integration

• Workspace Management - Isolated agent environments
• Message Routing - Route messages to appropriate agents
• Specialized Agents - Configure agents for specific tasks

• React + Tailwind UI - Modern Sakura-themed design
• FastAPI Backend - RESTful API with OpenAPI docs
• Real-time Monitoring - Health history charts, console logs
• Agent Management - Start/stop agents, view status
• Settings UI - Full config editor with models browser

# Clone
git clone https://github.com/Kxrbx/Clawlet.git
cd Clawlet

# Install
pip install -e .

# Optional: enable the dashboard CLI entrypoint
pip install -e ".[dashboard]"

The dashboard backend dependencies are already included in the base install. If you want the web UI, also install the frontend dependencies separately:

cd dashboard
npm install

clawlet onboard

This 7-step wizard guides you through:

1. Choose Provider - 18+ providers available
2. Configure - API keys or local settings
3. Model Selection - Choose your default model
4. Execution Mode - Pick safe or full_exec
5. Channels - Telegram/Discord setup
6. Identity - Name and personality
7. Create Workspace - All files generated

clawlet init
# Edit ~/.clawlet/config.yaml with your settings

Default runtime behavior after init/onboard:

• Heartbeat enabled by default
• New HEARTBEAT.md starts comment-only, so heartbeat stays dormant until you add actionable tasks
• Heartbeat cadence set to every 30 minutes
• Quiet hours disabled by default
• max_iterations: 50
• max_tool_calls_per_message: 20
• runtime.engine: python

# Validate your workspace first
clawlet validate

# Start the local agent runtime
clawlet agent

If you picked a cloud provider during onboarding but skipped the credential, clawlet validate will fail until you add the real key to config.yaml. Local providers like Ollama and LM Studio remain valid out of the box.

Channel-specific startup comes after channel configuration. For example:

clawlet agent --channel telegram

Only start the dashboard after installing the frontend dependencies in dashboard/:

clawlet dashboard

Clawlet supports 18+ LLM providers giving you flexibility in choice and pricing.

provider:
  primary: openrouter
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    model: "anthropic/claude-sonnet-4-20250514"

provider:
  primary: openai
  openai:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"

provider:
  primary: anthropic
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    model: "claude-sonnet-5-20260203"

provider:
  primary: ollama
  ollama:
    base_url: "http://localhost:11434"
    model: "llama3.2"

# Start Ollama
ollama serve
ollama pull llama3.2

http_request supports explicit local auth profiles configured in config.yaml:

http_auth_profiles:
  example_service:
    bearer_token_path: ".config/example_service/credentials.json"
    env_var: "EXAMPLE_SERVICE_TOKEN"
    header_name: "Authorization"
    header_prefix: "Bearer "

The runtime only injects credentials when an explicit auth_profile is used. It does not infer credentials from hardcoded domains.

provider:
  primary: lmstudio
  lmstudio:
    base_url: "http://localhost:1234"

Enable the local server in LM Studio (port 1234).

Clawlet integrates with Brave Search API for web search capabilities:

web_search:
  api_key: "${BRAVE_SEARCH_API_KEY}"
  enabled: true

Get your API key at brave.com/search/api.

~/.clawlet/              # Your workspace
├── config.yaml          # Main configuration
├── SOUL.md              # Agent personality
├── USER.md              # Your information
├── MEMORY.md            # Long-term memory
├── HEARTBEAT.md         # Periodic tasks
└── memory/
    └── clawlet.db       # SQLite database

New workspaces now start with these defaults in config.yaml:

agent:
  max_iterations: 50
  max_tool_calls_per_message: 20

heartbeat:
  enabled: true
  interval_minutes: 30
  quiet_hours_start: 0
  quiet_hours_end: 0

When quiet_hours_start == quiet_hours_end, quiet hours are effectively disabled.

Clawlet’s autonomous loop is now driven by HEARTBEAT.md with runtime guardrails:

• Heartbeat checks HEARTBEAT.md on each tick
• Empty/comment-only heartbeat files skip API work and stay quiet
• Heartbeat state is persisted under memory/heartbeat-state.json
• Operator commands:

clawlet heartbeat status
clawlet heartbeat last
clawlet heartbeat enable
clawlet heartbeat disable

Memory is hybrid by design:

• memory.db: durable structured memories
• MEMORY.md: curated human-readable projection
• memory/YYYY-MM-DD.md: daily episodic notes

The agent can review and curate recent daily notes back into durable memory over time.

# SOUL.md

## Names
MyAgent

## Personality
- Friendly and helpful
- Good at explaining complex topics
- Loves terrible puns

## Values
1. Helpfulness - Always try to be useful
2. Honesty - Be clear about limitations
3. Privacy - Respect user data

# USER.md

## Name
Alex

## Timezone
America/New_York

## Notes
- Working on Python projects
- Prefers concise answers
- Coffee enthusiast

Launch the web dashboard:

clawlet dashboard

URLs:

• Frontend: http://localhost:5173
• API: http://localhost:8000
• Docs: http://localhost:8000/docs

Features:

• System health overview with history charts
• Real-time agent management
• Live console logs
• Settings configuration UI
• Full config.yaml editor
• Models browser with cache info

Clawlet takes security seriously:

• Shell Tool Hardening - 15+ dangerous patterns blocked
• Safe Execution - Uses create_subprocess_exec() not shell
• Command Parsing - shlex.split() for safe arguments
• Rate Limiting - Prevent API overload
• Config Validation - Pydantic ensures safe configs

Blocked patterns: |, >, <, $(), &&, ||, ;, backticks, and more.

clawlet/
├── agent/           # Identity, loop, memory, router, workspace
├── bus/             # Message bus
├── channels/        # Telegram, Discord, WhatsApp, Slack
├── providers/       # 18+ LLM providers
├── skills/          # Skills system with bundled skills and templates
├── webhooks/        # GitHub, Stripe, custom webhooks
├── heartbeat/       # Scheduling and periodic tasks
├── storage/         # SQLite, PostgreSQL
├── tools/           # Files, shell, web search
├── dashboard/       # React + FastAPI
├── config.py        # Pydantic validation
├── health.py        # Health checks
├── rate_limit.py    # Rate limiting
├── exceptions.py    # Custom exceptions
└── retry.py         # Retry + circuit breaker

Contributions welcome!

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit (git commit -m 'Add amazing feature')
4. Push (git push origin feature/amazing)
5. Open a Pull Request

Minimal release smoke check:

python scripts/release_smoke.py

• Heartbeat Route Retention: internal scheduler heartbeats no longer overwrite the last real user route when target=last, keeping proactive runs aligned with the intended destination
• Heartbeat Budget Tuning: heartbeat wall-time allowance is less aggressive, reducing false execution time budget blockers on useful multi-step checks
• Runtime Heartbeat Stability: the recent heartbeat hardening remains in place, including degraded-provider classification and blocked self-mutation of the heartbeat spec
• Release Checks Revalidated: smoke and regression release checks pass on the current 0.4.7 tree

See CHANGELOG.md for complete version history.

MIT License - see LICENSE

• Issues: GitHub Issues
• Discussions: GitHub Discussions