clawlet: Lightweight Personal AI Assistant
Single Binary, Simple Setup

This project is inspired by OpenClaw and nanobot.

Why clawlet

📦 Single binary, small footprint: Runs as one executable with minimal moving parts.

📖 Readable: Straightforward organization so it’s easy to understand, modify, and extend.

✅ Easy to adopt: onboard creates a ready-to-edit workspace and config; you can start chatting immediately.

Install

Prebuilt binaries are published on GitHub Releases (via GoReleaser).

macOS example (Apple Silicon):

curl -L -o clawlet.tar.gz \
  https://github.com/mosaxiv/clawlet/releases/latest/download/clawlet_Darwin_arm64.tar.gz
tar -xzf clawlet.tar.gz
chmod +x clawlet
mkdir -p ~/.local/bin
mv clawlet ~/.local/bin/
clawlet --help

Quick Start

# Initialize
clawlet onboard \
  --openrouter-api-key "sk-or-..." \
  --model "openrouter/anthropic/claude-sonnet-4.5"

# Check effective configuration
clawlet status

# Chat
clawlet agent -m "What is 2+2?"

Architecture

flowchart LR
    ChatApps["Chat Apps / CLI"]

    %% Agent loop (Message -> LLM <-> Tools -> Response)
    subgraph Loop["Agent Loop"]
      Msg[Message]
      LLM[LLM]
      Tools[Tools]
      Resp[Response]
      Sess["Sessions"]
    end

    subgraph Ctx["Context"]
      CtxHub["Files, Memory, Skills"]
    end

    ChatApps --> Msg
    Msg --> LLM
    LLM -->|tool calls| Tools
    Tools -->|tool results| LLM
    LLM --> Resp

    Tools <--> CtxHub
    %% Sessions are internal state (history in/out)
    Sess -.-> LLM
    Msg -.-> Sess
    Resp -.-> Sess

    %% Conversation continues (next turn)
    Resp --> ChatApps
    Resp -.-> Msg

    %% Color blocks (similar to the reference diagram)
    classDef chat fill:#dbeafe,stroke:#60a5fa,color:#111827;
    classDef msg fill:#fef3c7,stroke:#f59e0b,color:#111827;
    classDef loop fill:#fed7aa,stroke:#fb923c,color:#111827;
    classDef resp fill:#fecaca,stroke:#f87171,color:#111827;
    classDef ctx fill:#e9d5ff,stroke:#a78bfa,color:#111827;

    class ChatApps chat;
    class Msg msg;
    class LLM,Tools loop;
    class Resp resp;
    class CtxHub,Sess ctx;

Workspace (How clawlet “thinks”)

Default workspace: ~/.clawlet/workspace (override with --workspace or CLAWLET_WORKSPACE).

Files in the workspace are automatically injected into the system prompt when present:

• AGENTS.md: contributor/user instructions for the agent
• SOUL.md, USER.md, IDENTITY.md: personalization and guardrails
• TOOLS.md: tool reference for humans
• HEARTBEAT.md: periodic tasks
• memory/: long-term and daily notes

This matches the “workspace-first” style: you control behavior by editing small, versionable text files.

Configuration (~/.clawlet/config.json)

Config file: ~/.clawlet/config.json

Supported providers

clawlet currently supports these LLM providers:

• OpenAI (openai/<model>, API key: env.OPENAI_API_KEY)
• OpenRouter (openrouter/<provider>/<model>, API key: env.OPENROUTER_API_KEY)
• Anthropic (anthropic/<model>, API key: env.ANTHROPIC_API_KEY)
• Gemini (gemini/<model>, API key: env.GEMINI_API_KEY or env.GOOGLE_API_KEY)
• Local (Ollama / vLLM / OpenAI-compatible local endpoint) (ollama/<model> or local/<model>, default base URL: http://localhost:11434/v1, API key optional)

Minimal config (OpenRouter):

{
  "env": { "OPENROUTER_API_KEY": "sk-or-..." },
  "agents": { "defaults": { "model": "openrouter/anthropic/claude-sonnet-4-5" } }
}

Agent generation defaults are configurable (aligned with nanobot defaults):

{
  "agents": {
    "defaults": {
      "model": "openrouter/anthropic/claude-sonnet-4-5",
      "maxTokens": 8192,
      "temperature": 0.7
    }
  }
}

Minimal config (Local via Ollama):

{
  "agents": { "defaults": { "model": "ollama/qwen2.5:14b" } }
}

Minimal config (Local via vLLM using the same ollama/ route):

{
  "agents": { "defaults": { "model": "ollama/meta-llama/Llama-3.1-8B-Instruct" } },
  "llm": { "baseURL": "http://localhost:8000/v1" }
}

clawlet will fill in sensible defaults for missing sections (tools, gateway, cron, heartbeat, channels).

Safety defaults

clawlet is conservative by default:

• tools.restrictToWorkspace defaults to true (tools can only access files inside the workspace directory)

Chat Apps

Chat app integrations are configured under channels (examples below).

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

clawlet gateway

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention",
      "allowFrom": ["U012345"]
    }
  }
}

clawlet gateway

CLI Reference

clawlet cron add formats

--message is required, and exactly one of --every, --cron, or --at must be set.

# Every N seconds
clawlet cron add --message "summarize my inbox" --every 3600

# Cron expression (5-field)
clawlet cron add --message "daily standup notes" --cron "0 9 * * 1-5"

# Run once at a specific time (RFC3339)
clawlet cron add --message "remind me" --at "2026-02-10T09:00:00Z"

# Deliver to a chat (requires both --channel and --to)
clawlet cron add --message "ping" --every 600 --channel slack --to U012345