{"id":47300626,"url":"https://github.com/krillclaw/KrillClaw","last_synced_at":"2026-03-31T06:00:52.158Z","repository":{"id":338999361,"uuid":"1158396731","full_name":"krillclaw/KrillClaw","owner":"krillclaw","description":"The world's smallest AI agent runtime. 49KB. Written in Zig. Zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-02-28T22:44:25.000Z","size":90685,"stargazers_count":79,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T00:44:18.002Z","etag":null,"topics":["ai-agent","arm","edge-ai","embedded","iot","llm","risc-v","runtime","tiny","zig"],"latest_commit_sha":null,"homepage":"https://krillclaw.com","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krillclaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T09:53:16.000Z","updated_at":"2026-03-01T00:03:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/krillclaw/KrillClaw","commit_stats":null,"previous_names":["krillclaw/krillclaw"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/krillclaw/KrillClaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krillclaw%2FKrillClaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krillclaw%2FKrillClaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krillclaw%2FKrillClaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krillclaw%2FKrillClaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krillclaw","download_url":"https://codeload.github.com/krillclaw/KrillClaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krillclaw%2FKrillClaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31223292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T04:08:55.938Z","status":"ssl_error","status_checked_at":"2026-03-31T04:08:47.883Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","arm","edge-ai","embedded","iot","llm","risc-v","runtime","tiny","zig"],"created_at":"2026-03-17T01:38:20.001Z","updated_at":"2026-03-31T06:00:52.151Z","avatar_url":"https://github.com/krillclaw.png","language":"Zig","funding_links":[],"categories":["Zig"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://krillclaw.com/assets/krillclaw-logo.svg\" alt=\"KrillClaw\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eKrillClaw\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eThe AI agent runtime that fits on a microcontroller.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/krillclaw/KrillClaw/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/krillclaw/KrillClaw/test.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-BSL_1.1-blue?style=flat-square\" alt=\"License: BSL 1.1\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/language-Zig_0.15+-f7a41d?style=flat-square\u0026logo=zig\u0026logoColor=white\" alt=\"Zig 0.15+\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/languages/code-size/krillclaw/KrillClaw?style=flat-square\u0026color=green\" alt=\"Code size\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/binary-~450KB-00ff88?style=flat-square\" alt=\"Binary size\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square\" alt=\"Zero deps\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#why-krillclaw\"\u003eWhy KrillClaw?\u003c/a\u003e •\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#profiles\"\u003eProfiles\u003c/a\u003e •\n  \u003ca href=\"#embedded-mode\"\u003eEmbedded\u003c/a\u003e •\n  \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n~450KB binary. 0 dependencies. 19 source files. 50+ validated device targets. Runs on a $3 microcontroller or a cloud server.\n\nKrillClaw 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.\n\n```\n ┌──────────────────────────────────────────────────────┐\n │                                                      │\n │   ~450 KB.  Zero deps.  Boots in \u003c10ms.              │\n │   The entire agent runtime — LLM client, tool        │\n │   executor, JSON parser, SSE streaming, cron,        │\n │   KV store, context mgmt — in 4,576 lines of Zig.   │\n │                                                      │\n └──────────────────────────────────────────────────────┘\n```\n\n## Quick Start\n\n```bash\n# 1. Install Zig 0.15+ → https://ziglang.org/download/\n# 2. Clone and build (takes ~1 second)\ngit clone https://github.com/krillclaw/KrillClaw.git\ncd KrillClaw\nzig build -Doptimize=ReleaseSmall\n\n# 3. Set your API key and go\nexport ANTHROPIC_API_KEY=sk-ant-...\n./zig-out/bin/krillclaw \"create a REST API in Go with user auth\"\n```\n\nThat's it. No npm install. No pip. No Docker. Just Zig and a binary.\n\n## Why KrillClaw?\n\n**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.\n\nKrillClaw 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.\n\n**KrillClaw exists because AI agents should run everywhere** — not just on machines with Node.js and 8GB of RAM.\n\n### The Numbers\n\n| | KrillClaw | Typical Edge Runtime | Desktop Agent |\n|---|:---:|:---:|:---:|\n| **Binary** | **~450 KB** | 2–8 MB | 50–500 MB |\n| **RAM** | **~2 MB** | 10–512 MB | 150 MB – 1 GB |\n| **Source** | **4,576 LOC** | 5–30K LOC | 30–100K+ LOC |\n| **Dependencies** | **0** | 10–100+ | 100–1000+ |\n| **Boot time** | **\u003c10 ms** | \u003c1s | 2–5s |\n| **Embedded/BLE** | **Yes** | Sometimes | No |\n| **Cron/Daemon** | **Yes** | Sometimes | No |\n\n### vs Embedded/Edge Runtimes\n\n| Feature | KrillClaw | MimiClaw | PicoClaw |\n|---------|:---------:|:--------:|:--------:|\n| **Language** | Zig | Python | Go |\n| **Binary size** | ~450 KB | ~2 MB | ~8 MB |\n| **RAM usage** | ~2 MB | ~512 KB* | ~10 MB |\n| **Dependencies** | 0 | pip | Go modules |\n| **BLE transport** | ✅ | ❌ | ❌ |\n| **Serial transport** | ✅ | ❌ | ❌ |\n| **Multi-provider** | 20+ (Claude, OpenAI, Ollama + 17 via `--base-url`) | 2 | 1 |\n| **SSE streaming** | ✅ | ❌ | ❌ |\n| **Inline tests** | 60 | 0 | Limited |\n| **Sandbox mode** | ✅ | ❌ | ❌ |\n| **MCP support** | ✅ | ❌ | ❌ |\n| **Channels** | 7 (Telegram, Discord, Slack, WhatsApp, MQTT, WebSocket, Webhook) | 2 | N/A |\n| **GPIO / hardware** | ✅ (GPIO, I2C, SPI) | ✅ (GPIO) | ❌ |\n| **License** | BSL 1.1 | MIT | MIT |\n\n*Competitor data as of Feb 2026. Check their repos for current numbers.*\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        KrillClaw                             │\n│                                                              │\n│  ┌─────────┐    ┌──────────┐    ┌────────────┐              │\n│  │  main    │───▶│  agent   │───▶│  tools     │              │\n│  │  (CLI)   │    │  (loop)  │    │  (dispatch)│              │\n│  └─────────┘    └────┬─────┘    └─────┬──────┘              │\n│                      │                │                      │\n│                 ┌────▼─────┐    ┌─────▼──────────────┐      │\n│                 │   api    │    │  tools_coding.zig   │      │\n│                 │ (client) │    │  tools_iot.zig      │      │\n│                 └────┬─────┘    │  tools_robotics.zig │      │\n│                      │          └────────────────────┘      │\n│               ┌──────▼──────┐                                │\n│               │  transport  │  ◀── vtable dispatch           │\n│               └──┬────┬──┬──┘                                │\n│                  │    │  │                                    │\n│              ┌───▼┐ ┌▼──▼┐                                   │\n│              │HTTP│ │BLE │ │Serial│                           │\n│              └────┘ └────┘ └──────┘                           │\n│                                                              │\n│  Support: json.zig │ stream.zig │ context.zig │ config.zig  │\n│           types.zig │ arena.zig                              │\n└─────────────────────────────────────────────────────────────┘\n\n19 files. 4,576 lines. Zero dependencies.\n```\n\n### Source Map\n\n| File | Lines | Role |\n|------|------:|------|\n| `main.zig` | 198 | CLI, REPL, cron daemon entry point |\n| `agent.zig` | 215 | Agent loop + FNV-1a stuck-loop detection |\n| `api.zig` | 341 | Multi-provider HTTP client (Claude/OpenAI/Ollama) |\n| `stream.zig` | 362 | SSE streaming parser |\n| `json.zig` | 519 | Hand-rolled JSON parser/builder — zero deps |\n| `tools.zig` | 191 | Tool dispatcher — comptime profile + shared tools |\n| `tools_shared.zig` | 362 | Shared tools: time, KV, web search, sessions, OTA (all profiles) |\n| `tools_coding.zig` | 484 | Coding profile: bash, read/write/edit, search, list, patch |\n| `tools_iot.zig` | 176 | IoT profile: MQTT, HTTP, device info |\n| `tools_robotics.zig` | 153 | Robotics profile: commands, e-stop, telemetry |\n| `context.zig` | 226 | Token estimation + priority-based truncation |\n| `config.zig` | 202 | Config: file → env → CLI precedence |\n| `cron.zig` | 206 | Cron/heartbeat scheduler for daemon mode |\n| `transport.zig` | 179 | Abstract vtable transport + RPC protocol |\n| `types.zig` | 157 | Core types: Provider, Message, Config, ToolDef |\n| `ble.zig` | 159 | BLE GATT transport (protocol + simulation) |\n| `serial.zig` | 142 | UART/serial transport (Linux/macOS) |\n| `arena.zig` | 200 | Fixed arena allocator for embedded targets |\n| `react.zig` | 104 | ReAct reasoning loop |\n\n## Profiles\n\nCompile-time profiles select different tool sets. Only the selected profile's code ships in the binary — zero runtime overhead.\n\n```bash\n# Coding agent (default)\nzig build -Dprofile=coding -Doptimize=ReleaseSmall\n\n# IoT agent — MQTT, HTTP, KV store, device info\nzig build -Dprofile=iot -Doptimize=ReleaseSmall\n\n# Robotics agent — motion commands, e-stop, telemetry\nzig build -Dprofile=robotics -Doptimize=ReleaseSmall\n```\n\n| Profile | Tools | Binary Size | Security Policy |\n|---------|-------|:-----------:|-----------------|\n| **coding** | bash, read/write/edit, search, list, patch + shared | ~459 KB | bash behind approval gate, writes restricted to cwd |\n| **iot** | MQTT pub/sub, HTTP, GPIO, I2C, SPI, device info + shared | ~463 KB | no bash, no file writes, 30 req/min rate limit |\n| **robotics** | robot_cmd, estop, telemetry + shared | ~473 KB | no bash, bounds checking, 10 cmd/s, e-stop |\n\nAll profiles include **shared tools** available across every profile:\n- `get_current_time` — ISO-8601 timestamp\n- `kv_get` / `kv_set` / `kv_list` / `kv_delete` — persistent key-value store\n\nAll profiles support sandbox mode: `zig build -Dsandbox=true`\n\n## Cron / Heartbeat (Daemon Mode)\n\nRun KrillClaw as a scheduled agent on edge devices:\n\n```bash\n# Run agent every 5 minutes with a custom prompt\nkrillclaw --cron-interval 300 --cron-prompt \"check sensors and report anomalies\"\n\n# Heartbeat every 60 seconds + agent every 10 minutes\nkrillclaw --heartbeat 60 --cron-interval 600\n\n# Run 10 times then exit\nkrillclaw --cron-interval 120 --cron-max-runs 10 --cron-prompt \"collect data\"\n```\n\nDesigned for edge devices running data collection cycles between connectivity windows (BLE, Serial). The scheduler has minimal binary cost (~2KB) and uses no threads.\n\n## Providers\n\nKrillClaw supports **20+ LLM providers** through three protocol backends. Any provider with an OpenAI-compatible API works via `--base-url`.\n\n| Provider | Models | Auth |\n|----------|--------|------|\n| **Claude** | claude-sonnet-4-5, claude-opus-4, etc. | `ANTHROPIC_API_KEY` |\n| **OpenAI** | gpt-4o, gpt-4-turbo, etc. | `OPENAI_API_KEY` |\n| **Ollama** | llama3, codellama, mistral, etc. | None (local) |\n| **+ 17 more** | via `--base-url` | Provider-specific |\n\n```bash\n# Claude (default)\n./zig-out/bin/krillclaw \"fix the tests\"\n\n# OpenAI\nexport OPENAI_API_KEY=sk-...\n./zig-out/bin/krillclaw --provider openai -m gpt-4o \"fix the tests\"\n\n# Local Ollama\n./zig-out/bin/krillclaw --provider ollama -m llama3 \"explain this code\"\n\n# Groq (ultra-fast inference)\nKRILLCLAW_API_KEY=gsk_... ./zig-out/bin/krillclaw \\\n  --provider openai --base-url https://api.groq.com/openai \\\n  -m llama-3.3-70b-versatile \"optimize this function\"\n\n# DeepSeek (cost-effective coding)\nKRILLCLAW_API_KEY=sk-... ./zig-out/bin/krillclaw \\\n  --provider openai --base-url https://api.deepseek.com \\\n  -m deepseek-chat \"refactor this module\"\n\n# Together AI (open-source models)\nKRILLCLAW_API_KEY=... ./zig-out/bin/krillclaw \\\n  --provider openai --base-url https://api.together.xyz \\\n  -m meta-llama/Llama-3.1-70B-Instruct-Turbo \"write tests\"\n\n# Google Gemini (via OpenAI compatibility layer)\nKRILLCLAW_API_KEY=... ./zig-out/bin/krillclaw \\\n  --provider openai \\\n  --base-url https://generativelanguage.googleapis.com/v1beta/openai \\\n  -m gemini-2.0-flash \"summarize this repo\"\n```\n\nSee [Docs/PROVIDERS.md](Docs/PROVIDERS.md) for the full list of 20+ supported providers with base URLs, tool calling support, and configuration examples.\n\n## MCP Support\n\nKrillClaw integrates with [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers, connecting your agent to 1000+ tools.\n\n```bash\n# Configure MCP servers in ~/.krillclaw/mcp_servers.json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/user\"]\n    }\n  }\n}\n\n# Start with MCP tools available\npython bridge/bridge.py --serve --channels webhook\n```\n\nMCP tools are namespaced as `servername__toolname` and automatically available to the agent. Supports stdio and streamable HTTP transports.\n\n## Channels\n\n7 messaging channels — your agent talks wherever your users are:\n\n| Channel | Library | Auth |\n|---------|---------|------|\n| **Telegram** | stdlib (urllib) | Bot token |\n| **Discord** | discord.py | Bot token |\n| **Slack** | slack-bolt | Bot + App token (Socket Mode) |\n| **WhatsApp** | Cloud API (Meta) | Business access token |\n| **MQTT** | paho-mqtt | Broker config |\n| **WebSocket** | websockets | Token auth |\n| **Webhook** | stdlib (http.server) | Bearer token |\n\n```bash\n# Start multi-channel server\npython bridge/bridge.py --serve --channels telegram,discord,webhook\n```\n\n## GPIO / Hardware Control\n\nDirect hardware control from AI — GPIO, I2C, SPI:\n\n```bash\n# IoT profile includes GPIO tools\nzig build -Dprofile=iot -Doptimize=ReleaseSmall\n\n# GPIO tools route through the Python bridge\n# Linux: real hardware via libgpiod\n# macOS: simulator mode (logs commands)\n```\n\n| Tool | Description |\n|------|-------------|\n| `gpio_read` | Read a GPIO pin value |\n| `gpio_write` | Write a value to a GPIO pin |\n| `gpio_list` | List available GPIO pins |\n| `i2c_read` | Read from an I2C device |\n| `spi_transfer` | Transfer data over SPI |\n\nSafety: pin allowlist via `~/.krillclaw/hardware.json`, rate limiting on writes.\n\n## Embedded Mode\n\nKrillClaw targets microcontrollers. The device runs the agent brain. A phone or laptop bridges to the internet.\n\n```\n┌─────────────┐       BLE/UART       ┌──────────────┐      HTTPS      ┌─────────┐\n│  KrillClaw  │ ◄──────────────────► │    Bridge     │ ◄────────────► │  LLM    │\n│  (device)   │                      │  (phone/PC)   │                │  API    │\n│             │  \"call bash ls\"      │               │                └─────────┘\n│ Agent loop  │ ────────────────►    │ Execute tools │\n│ JSON parse  │                      │ Return result │\n│ State mgmt  │ ◄────────────────   │               │\n│    ~50 KB   │  \"file1 file2...\"    │  bridge.py    │\n└─────────────┘                      └───────────────┘\n```\n\n### Build for Hardware\n\n```bash\n# BLE transport\nzig build -Dble=true -Doptimize=ReleaseSmall\n\n# Serial/UART transport\nzig build -Dserial=true -Doptimize=ReleaseSmall\n\n# Bare-metal (no OS)\nzig build -Dembedded=true -Dtarget=thumb-none-eabi -Doptimize=ReleaseSmall\n```\n\n### Target Hardware\n\n| Device | SoC | RAM | Flash | Cost |\n|--------|-----|-----|-------|-----:|\n| **ESP32-C3** | RISC-V | 400 KB | 4 MB | $3 |\n| **Raspberry Pi Pico W** | RP2040 | 264 KB | 2 MB | $6 |\n| **Colmi R02** (smart ring) | BlueX RF03 | ~32 KB | ~256 KB | $20 |\n| **nRF52840-DK** | nRF52840 | 256 KB | 1 MB | $40 |\n| **nRF5340-DK** | nRF5340 | 512 KB | 1 MB | $50 |\n\n### Fixed Arena Allocator\n\nFor devices with no OS heap:\n\n```zig\nvar mem = arena.Arena32K.init();  // 32KB — fits on nRF5340\nconst alloc = mem.allocator();\n// ... use alloc for everything ...\nmem.reset();  // Frees everything at once between agent turns\n```\n\nPreset sizes: `Arena4K`, `Arena16K`, `Arena32K`, `Arena128K`, `Arena256K`.\n\n## Transport Layers\n\n| Transport | Use Case | Status |\n|-----------|----------|--------|\n| **HTTP** | Desktop — direct HTTPS to API | Stable |\n| **BLE** | Embedded — GATT protocol + desktop simulation via Unix socket | Experimental |\n| **Serial** | Dev boards — UART to host machine | Experimental |\n\n\u003e **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.\n\n## Multi-Channel Gateway (Phase 3)\n\nThe bridge supports multiple message channels simultaneously via `--serve` mode:\n\n```bash\n# Start with webhook channel (default)\npython bridge/bridge/bridge.py --serve --channels webhook\n\n# Start with multiple channels\npython bridge/bridge/bridge.py --serve --channels telegram,webhook,websocket\n\n# WebSocket gateway for browser-based clients\npython bridge/bridge/bridge.py --serve --channels websocket\n```\n\n### Available Channels\n\n| Channel | Transport | Use Case |\n|---------|-----------|----------|\n| **webhook** | HTTP POST | Simplest integration — any HTTP client |\n| **websocket** | WebSocket | Browser clients, streaming responses |\n| **telegram** | Telegram Bot API | Chat-based interaction |\n| **mqtt** | MQTT pub/sub | IoT device messaging |\n\n### WebSocket Wire Protocol\n\n```json\n→ {\"type\": \"message\", \"text\": \"fix the bug\"}\n← {\"type\": \"text\", \"text\": \"Let me look at that...\"}\n← {\"type\": \"done\"}\n```\n\n### Channel Configuration\n\nPer-channel settings via `~/.krillclaw/channels.json`:\n\n```json\n{\n  \"webhook\": {\"port\": 8080, \"auth_token\": \"secret\"},\n  \"websocket\": {\"port\": 8765, \"agent_binary\": \"./zig-out/bin/krillclaw\"},\n  \"telegram\": {\"token\": \"bot123:ABC\", \"allowed_users\": [12345]},\n  \"mqtt\": {\"broker\": \"localhost\", \"subscribe_topic\": \"krillclaw/in\"}\n}\n```\n\n## Skills / Plugins\n\nExtend the agent with custom Python tools. Drop a `.py` file in `~/.krillclaw/plugins/`:\n\n```python\n# ~/.krillclaw/plugins/my_tool.py\nTOOL_NAME = \"my_custom_tool\"\nTOOL_DESCRIPTION = \"Does something custom.\"\nTOOL_SCHEMA = {\"type\": \"object\", \"properties\": {\"input\": {\"type\": \"string\"}}}\n\ndef handle(data: dict) -\u003e dict:\n    return {\"result\": f\"processed: {data.get('input', '')}\"}\n```\n\nPlugins 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.\n\n## Configuration\n\n```bash\n# Environment variables\nexport KRILLCLAW_MODEL=claude-opus-4-6\nexport KRILLCLAW_PROVIDER=claude\nexport KRILLCLAW_BASE_URL=https://my-proxy.com\nexport KRILLCLAW_SYSTEM_PROMPT=\"You are a Go expert...\"\n```\n\n```json\n// .krillclaw.json (project-level config)\n{\n  \"model\": \"claude-sonnet-4-5-20250929\",\n  \"provider\": \"claude\",\n  \"max_tokens\": 8192,\n  \"streaming\": true\n}\n```\n\nConfig precedence: CLI flags → environment variables → config file.\n\n## REPL Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show help |\n| `/quit` `/exit` `/q` | Exit |\n| `/model \u003cname\u003e` | Switch model |\n| `/provider \u003cname\u003e` | Switch provider |\n\n## Design Decisions\n\n| Decision | Rationale |\n|----------|-----------|\n| **Hand-rolled JSON** | `std.json` adds unnecessary code. KrillClaw only needs key extraction + body building. 501 lines, zero deps. |\n| **Vtable transports** | Same binary works over HTTP, BLE, or Serial. Swap physical layer without touching agent logic. |\n| **FNV-1a loop detection** | Detect stuck LLM loops in constant memory (128 bytes). Critical for embedded. |\n| **Priority-based truncation** | When context fills, drop assistant text first, keep tool results. Keeps working memory functional. |\n| **Substring search, not regex** | Regex engines are ~10K+ lines. `std.mem.indexOf` covers 90%+ of agent search use cases. |\n\n## Testing\n\n```bash\nzig build test        # 39 inline unit tests\nbash test/integration.sh  # 9 integration tests\n```\n\nTests cover JSON parsing, SSE streaming, arena allocation, context truncation, tool execution, glob matching, and security injection attempts.\n\nCI runs on every push with a binary size gate (\u003c600KB).\n\n## Building\n\n```bash\nzig build                              # Debug build\nzig build -Doptimize=ReleaseSmall      # Smallest binary\nzig build test                         # Run all tests\nzig build size                         # Report binary size\n```\n\n## Security\n\nKrillClaw executes tools with the permissions of the running user. **Do not run with elevated privileges.** Use profiles and sandbox mode to restrict tool access.\n\nBLE and Serial transports do not currently include encryption or authentication. Use only on trusted networks.\n\nSee [SECURITY.md](SECURITY.md) for reporting vulnerabilities.\n\n## Known Limitations\n\n- **JSON parser is flat** — finds first matching key at any depth (works for LLM API responses where keys are unambiguous)\n- **Token estimation is heuristic** — ~4 chars/token approximation, not billing-accurate\n- **Session persistence via bridge** — save/load conversation history through bridge tools\n- **BLE transport is protocol-only** — real hardware needs platform BLE SDK linking\n- **Serial baud uses `stty`** — Linux/macOS only\n- **Requires Zig 0.15+**\n\n## License\n\n[BSL 1.1](LICENSE) — Business Source License. Converts to Apache 2.0 after 3 years (Change Date: 2029-02-17).\n\nKrillClaw 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](LICENSE) for full terms.\n\n## Contributing\n\nContributions welcome under BSL 1.1. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with Zig. No frameworks were harmed in the making of this runtime.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrillclaw%2FKrillClaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrillclaw%2FKrillClaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrillclaw%2FKrillClaw/lists"}