KrillClaw

The AI agent runtime that fits on a microcontroller.

Quick Start • Why KrillClaw? • Architecture • Profiles • Embedded • Contributing

~450KB binary. 0 dependencies. 19 source files. 50+ validated device targets. Runs on a $3 microcontroller or a cloud server.

KrillClaw is an autonomous AI agent runtime written in Zig. It connects to 20+ LLM providers (Claude, OpenAI, Ollama + 17 via --base-url), executes tools, and loops until the task is done. Includes cron scheduling, persistent KV store, MCP support, 7 messaging channels, GPIO/hardware control, and BLE/Serial transports for edge devices.

 ┌──────────────────────────────────────────────────────┐
 │                                                      │
 │   ~450 KB.  Zero deps.  Boots in <10ms.              │
 │   The entire agent runtime — LLM client, tool        │
 │   executor, JSON parser, SSE streaming, cron,        │
 │   KV store, context mgmt — in 4,576 lines of Zig.   │
 │                                                      │
 └──────────────────────────────────────────────────────┘

Quick Start

# 1. Install Zig 0.15+ → https://ziglang.org/download/
# 2. Clone and build (takes ~1 second)
git clone https://github.com/krillclaw/KrillClaw.git
cd KrillClaw
zig build -Doptimize=ReleaseSmall

# 3. Set your API key and go
export ANTHROPIC_API_KEY=sk-ant-...
./zig-out/bin/krillclaw "create a REST API in Go with user auth"

That's it. No npm install. No pip. No Docker. Just Zig and a binary.

Why KrillClaw?

Every AI agent runtime is massive. Desktop coding agents ship as 50–500MB bundles with hundreds of dependencies. The actual logic — "call LLM, parse response, execute tools, repeat" — shouldn't need any of that.

KrillClaw proves it doesn't. The same agentic loop that powers desktop tools, compiled to a binary smaller than a JPEG, running on hardware that costs less than a coffee.

KrillClaw exists because AI agents should run everywhere — not just on machines with Node.js and 8GB of RAM.

The Numbers

vs Embedded/Edge Runtimes

Competitor data as of Feb 2026. Check their repos for current numbers.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        KrillClaw                             │
│                                                              │
│  ┌─────────┐    ┌──────────┐    ┌────────────┐              │
│  │  main    │───▶│  agent   │───▶│  tools     │              │
│  │  (CLI)   │    │  (loop)  │    │  (dispatch)│              │
│  └─────────┘    └────┬─────┘    └─────┬──────┘              │
│                      │                │                      │
│                 ┌────▼─────┐    ┌─────▼──────────────┐      │
│                 │   api    │    │  tools_coding.zig   │      │
│                 │ (client) │    │  tools_iot.zig      │      │
│                 └────┬─────┘    │  tools_robotics.zig │      │
│                      │          └────────────────────┘      │
│               ┌──────▼──────┐                                │
│               │  transport  │  ◀── vtable dispatch           │
│               └──┬────┬──┬──┘                                │
│                  │    │  │                                    │
│              ┌───▼┐ ┌▼──▼┐                                   │
│              │HTTP│ │BLE │ │Serial│                           │
│              └────┘ └────┘ └──────┘                           │
│                                                              │
│  Support: json.zig │ stream.zig │ context.zig │ config.zig  │
│           types.zig │ arena.zig                              │
└─────────────────────────────────────────────────────────────┘

19 files. 4,576 lines. Zero dependencies.

Source Map

Profiles

Compile-time profiles select different tool sets. Only the selected profile's code ships in the binary — zero runtime overhead.

# Coding agent (default)
zig build -Dprofile=coding -Doptimize=ReleaseSmall

# IoT agent — MQTT, HTTP, KV store, device info
zig build -Dprofile=iot -Doptimize=ReleaseSmall

# Robotics agent — motion commands, e-stop, telemetry
zig build -Dprofile=robotics -Doptimize=ReleaseSmall

All profiles include shared tools available across every profile:

• get_current_time — ISO-8601 timestamp
• kv_get / kv_set / kv_list / kv_delete — persistent key-value store

All profiles support sandbox mode: zig build -Dsandbox=true

Cron / Heartbeat (Daemon Mode)

Run KrillClaw as a scheduled agent on edge devices:

# Run agent every 5 minutes with a custom prompt
krillclaw --cron-interval 300 --cron-prompt "check sensors and report anomalies"

# Heartbeat every 60 seconds + agent every 10 minutes
krillclaw --heartbeat 60 --cron-interval 600

# Run 10 times then exit
krillclaw --cron-interval 120 --cron-max-runs 10 --cron-prompt "collect data"

Designed for edge devices running data collection cycles between connectivity windows (BLE, Serial). The scheduler has minimal binary cost (~2KB) and uses no threads.

Providers

KrillClaw supports 20+ LLM providers through three protocol backends. Any provider with an OpenAI-compatible API works via --base-url.

# Claude (default)
./zig-out/bin/krillclaw "fix the tests"

# OpenAI
export OPENAI_API_KEY=sk-...
./zig-out/bin/krillclaw --provider openai -m gpt-4o "fix the tests"

# Local Ollama
./zig-out/bin/krillclaw --provider ollama -m llama3 "explain this code"

# Groq (ultra-fast inference)
KRILLCLAW_API_KEY=gsk_... ./zig-out/bin/krillclaw \
  --provider openai --base-url https://api.groq.com/openai \
  -m llama-3.3-70b-versatile "optimize this function"

# DeepSeek (cost-effective coding)
KRILLCLAW_API_KEY=sk-... ./zig-out/bin/krillclaw \
  --provider openai --base-url https://api.deepseek.com \
  -m deepseek-chat "refactor this module"

# Together AI (open-source models)
KRILLCLAW_API_KEY=... ./zig-out/bin/krillclaw \
  --provider openai --base-url https://api.together.xyz \
  -m meta-llama/Llama-3.1-70B-Instruct-Turbo "write tests"

# Google Gemini (via OpenAI compatibility layer)
KRILLCLAW_API_KEY=... ./zig-out/bin/krillclaw \
  --provider openai \
  --base-url https://generativelanguage.googleapis.com/v1beta/openai \
  -m gemini-2.0-flash "summarize this repo"

See Docs/PROVIDERS.md for the full list of 20+ supported providers with base URLs, tool calling support, and configuration examples.

MCP Support

KrillClaw integrates with Model Context Protocol (MCP) servers, connecting your agent to 1000+ tools.

# Configure MCP servers in ~/.krillclaw/mcp_servers.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  }
}

# Start with MCP tools available
python bridge/bridge.py --serve --channels webhook

MCP tools are namespaced as servername__toolname and automatically available to the agent. Supports stdio and streamable HTTP transports.

Channels

7 messaging channels — your agent talks wherever your users are:

# Start multi-channel server
python bridge/bridge.py --serve --channels telegram,discord,webhook

GPIO / Hardware Control

Direct hardware control from AI — GPIO, I2C, SPI:

# IoT profile includes GPIO tools
zig build -Dprofile=iot -Doptimize=ReleaseSmall

# GPIO tools route through the Python bridge
# Linux: real hardware via libgpiod
# macOS: simulator mode (logs commands)

Safety: pin allowlist via ~/.krillclaw/hardware.json, rate limiting on writes.

Embedded Mode

KrillClaw targets microcontrollers. The device runs the agent brain. A phone or laptop bridges to the internet.

┌─────────────┐       BLE/UART       ┌──────────────┐      HTTPS      ┌─────────┐
│  KrillClaw  │ ◄──────────────────► │    Bridge     │ ◄────────────► │  LLM    │
│  (device)   │                      │  (phone/PC)   │                │  API    │
│             │  "call bash ls"      │               │                └─────────┘
│ Agent loop  │ ────────────────►    │ Execute tools │
│ JSON parse  │                      │ Return result │
│ State mgmt  │ ◄────────────────   │               │
│    ~50 KB   │  "file1 file2..."    │  bridge.py    │
└─────────────┘                      └───────────────┘

Build for Hardware

# BLE transport
zig build -Dble=true -Doptimize=ReleaseSmall

# Serial/UART transport
zig build -Dserial=true -Doptimize=ReleaseSmall

# Bare-metal (no OS)
zig build -Dembedded=true -Dtarget=thumb-none-eabi -Doptimize=ReleaseSmall

Target Hardware

Fixed Arena Allocator

For devices with no OS heap:

var mem = arena.Arena32K.init();  // 32KB — fits on nRF5340
const alloc = mem.allocator();
// ... use alloc for everything ...
mem.reset();  // Frees everything at once between agent turns

Preset sizes: Arena4K, Arena16K, Arena32K, Arena128K, Arena256K.

Transport Layers

BLE note: The BLE transport implements framing and GATT service UUIDs with desktop simulation via Unix sockets. Real hardware integration requires linking against the platform BLE SDK (e.g., Nordic SoftDevice). See ble.zig for integration points.

Multi-Channel Gateway (Phase 3)

The bridge supports multiple message channels simultaneously via --serve mode:

# Start with webhook channel (default)
python bridge/bridge/bridge.py --serve --channels webhook

# Start with multiple channels
python bridge/bridge/bridge.py --serve --channels telegram,webhook,websocket

# WebSocket gateway for browser-based clients
python bridge/bridge/bridge.py --serve --channels websocket

Available Channels

WebSocket Wire Protocol

→ {"type": "message", "text": "fix the bug"}
← {"type": "text", "text": "Let me look at that..."}
← {"type": "done"}

Channel Configuration

Per-channel settings via ~/.krillclaw/channels.json:

{
  "webhook": {"port": 8080, "auth_token": "secret"},
  "websocket": {"port": 8765, "agent_binary": "./zig-out/bin/krillclaw"},
  "telegram": {"token": "bot123:ABC", "allowed_users": [12345]},
  "mqtt": {"broker": "localhost", "subscribe_topic": "krillclaw/in"}
}

Skills / Plugins

Extend the agent with custom Python tools. Drop a .py file in ~/.krillclaw/plugins/:

# ~/.krillclaw/plugins/my_tool.py
TOOL_NAME = "my_custom_tool"
TOOL_DESCRIPTION = "Does something custom."
TOOL_SCHEMA = {"type": "object", "properties": {"input": {"type": "string"}}}

def handle(data: dict) -> dict:
    return {"result": f"processed: {data.get('input', '')}"}

Plugins are discovered on bridge startup. Unknown tools from the Zig agent automatically fall through to the bridge, which routes them to the matching plugin handler. Built-in tool names cannot be overridden.

Configuration

# Environment variables
export KRILLCLAW_MODEL=claude-opus-4-6
export KRILLCLAW_PROVIDER=claude
export KRILLCLAW_BASE_URL=https://my-proxy.com
export KRILLCLAW_SYSTEM_PROMPT="You are a Go expert..."

// .krillclaw.json (project-level config)
{
  "model": "claude-sonnet-4-5-20250929",
  "provider": "claude",
  "max_tokens": 8192,
  "streaming": true
}

Config precedence: CLI flags → environment variables → config file.

REPL Commands

Design Decisions

Testing

zig build test        # 39 inline unit tests
bash test/integration.sh  # 9 integration tests

Tests cover JSON parsing, SSE streaming, arena allocation, context truncation, tool execution, glob matching, and security injection attempts.

CI runs on every push with a binary size gate (<600KB).

Building

zig build                              # Debug build
zig build -Doptimize=ReleaseSmall      # Smallest binary
zig build test                         # Run all tests
zig build size                         # Report binary size

Security

KrillClaw executes tools with the permissions of the running user. Do not run with elevated privileges. Use profiles and sandbox mode to restrict tool access.

BLE and Serial transports do not currently include encryption or authentication. Use only on trusted networks.

See SECURITY.md for reporting vulnerabilities.

Known Limitations

• JSON parser is flat — finds first matching key at any depth (works for LLM API responses where keys are unambiguous)
• Token estimation is heuristic — ~4 chars/token approximation, not billing-accurate
• Session persistence via bridge — save/load conversation history through bridge tools
• BLE transport is protocol-only — real hardware needs platform BLE SDK linking
• Serial baud uses stty — Linux/macOS only
• Requires Zig 0.15+

License

BSL 1.1 — Business Source License. Converts to Apache 2.0 after 3 years (Change Date: 2029-02-17).

KrillClaw is source-available, not open source. You can read, build, and modify the code. Commercial use above the license thresholds requires a commercial license. See LICENSE for full terms.

Contributing

Contributions welcome under BSL 1.1. See CONTRIBUTING.md for guidelines.

_{Built with Zig. No frameworks were harmed in the making of this runtime.}