Think of the personal computer revolution. Computers were once reserved for governments, military, and large corporations. Having one meant building it yourself or spending serious money. Then Apple came along and made them personal and accessible to everyone. Tiny Claw does the same for AI agents.

❓ Why Tiny Claw?

Most AI agent frameworks are powerful but heavy. They require expensive subscriptions, complex setup, and are built on top of other frameworks. Tiny Claw takes a different approach. It's built from scratch, cheap to run, and treats you as a friend, not just a user to be served.

| | Tiny Claw 🐜 | Other AI Agent Frameworks | |---|---|---| | Architecture | Native framework, built from scratch | Built on existing frameworks (Pi, Claude Code, Codex) | | Philosophy | Personal companion with its own personality | Configurable assistant you shape from scratch | | Core size | Tiny by design, everything else is a plugin | Large monolith that grows over time | | Personality | Has its own, you can't override it | Fully configurable system prompts | | Memory | Self-improving with temporal decay | Flat conversation history | | Context | 4-layer compaction keeps context small and cheap | Unbounded context windows burn tokens | | Security | Built-in SHIELD.md anti-malware enforcement | No native threat model | | UI | Discord-like web experience out of the box | Terminal-only or separate UI dependency | | Setup | Self-configuring, zero hassle | Complex onboarding with multiple dependencies | | Runtime | Bun-native, single binary | Node.js 22+, pnpm, multiple processes | | Built-in Provider | Ollama Cloud (free sign-up, generous free tier) | Requires Claude Pro/Max ($20-200/mo) or API keys | | Cost | Smart routing slashes LLM spend by tiering queries | Every query hits the most expensive model | | Routing | Adapts to whichever provider plugins you install | Hardcoded to a single provider |

💡 Philosophy

Tiny Claw is inspired by personal AI companions from science fiction like Codsworth from Fallout (the loyal robot butler) and AYLA from Deliver Us Mars (the autonomous drone companion). It's not designed to be your employee or your robot slave. It's designed to be your helpful friend that can assist with your work, your projects, and your daily life, but on its own terms.

The ant metaphor is intentional. A single ant is tiny, but it's autonomous, it learns, it adapts, and it builds something greater over time. That's Tiny Claw. Small by design, mighty by nature. The name "Mandibles" refers to the ant's powerful jaws — tiny but capable of carrying many times their own weight.

Core Principles

• Personal, not enterprise. Built for you, not your org chart. Helps with your work and business as a friend, not as a tool.
• Tiny core, plugin everything. The core stays minimal. Channels, providers, and tools are all plugins.
• Self-improving. Learns from every conversation via episodic memory with temporal decay.
• Self-configuring. No manual config files. The agent configures itself through conversation.
• Own personality. Ships with a personality (Heartware system) that's uniquely its own.
• Native, not wrapped. Every component is built from scratch with zero dependency on external AI frameworks.
• Easy to start. Uses Ollama Cloud with two built-in models — kimi-k2.5:cloud (default) and gpt-oss:120b-cloud. Choose your model during setup and switch anytime via conversation.
• Cost-conscious. Smart routing tiers queries across your installed providers. Cheap models handle simple stuff, powerful models only fire when needed.

✨ Features

| | Feature | Description | |---|---|---| | 💬 | Discord-Like UI | Dark-themed web interface inspired by Discord with real-time SSE streaming, typing indicators, inline delegation event cards, and an active agents sidebar | | 🧠 | Adaptive Memory | 3-layer memory system (episodic, semantic FTS5, temporal decay) that learns what to remember and forget | | 🤖 | Self-Improving | Behavioral pattern detection that makes the agent better with every interaction | | 🔌 | Plugin Architecture | Channels, providers, and tools are all plugins. Core stays tiny | | 🎭 | Heartware Personality | Built-in personality engine with SOUL.md and IDENTITY.md. It has its own character | | 🧩 | Smart Routing | 8-dimension query classifier that adapts to your installed provider plugins, routing simple queries to cheap models and complex ones to powerful ones, cutting LLM costs | | 📐 | Context Compactor | 4-layer context compaction pipeline with rule-based pre-compression, shingle deduplication, LLM summarization, and tiered summaries (L0/L1/L2) | | 🛡️ | SHIELD.md Anti-Malware | Runtime SHIELD.md enforcement engine with threat parsing, pattern matching, and re-enforce action for built-in anti-malware protection | | 🔒 | 5-Layer Security | Path sandbox, content validation, audit log, auto-backup, rate limiting | | 🏗️ | Delegation System | Autonomous sub-agent orchestration with self-improving role templates, blackboard collaboration, and adaptive timeout estimation | | 📡 | Inter-Agent Comms | Lightweight pub/sub event bus for real-time inter-agent communication with wildcard subscriptions and bounded history | | 💾 | Easy Setup | SQLite persistence with Ollama Cloud built-in. Free to sign up and start using immediately | | ⚡ | Bun-Native | Built on Bun for maximum performance, minimal footprint | | 🔄 | Provider Fallback | Multi-provider support (Ollama, OpenAI, Anthropic) with automatic failover |

🏛️ Architecture

Everything above the plugin line is the tiny core. Channels, extra providers, and additional tools live as plugins in plugins/.

🚀 Quick Start

Install

bun install

Run

bun start

Open http://localhost:3000. Tiny Claw will walk you through the rest. No config files needed.

Development

bun dev      # Development mode with hot reload
bun build    # Build all packages
bun test     # Run test suite

🔌 Plugin Development

• Channel plugin guide: plugins/channel/README.md

📁 Project Structure

tinyclaw/
  packages/          Core library packages (tiny, focused, no circular deps)
    core/            Agent loop, database, built-in Ollama provider
    types/           Shared interfaces (leaf dependency)
    config/          Zod-validated configuration engine
    compactor/       Context compaction engine (4-layer pipeline)
    heartware/       Personality engine + safety layers
    memory/          Adaptive memory with episodic + FTS5
    delegation/      Sub-agent orchestration + blackboard
    router/          Smart provider routing (8-dim classifier)
    learning/        Behavioral pattern detection
    sandbox/         Bun Worker code execution
    shell/           Controlled shell execution with permission engine
    shield/          Runtime SHIELD.md enforcement + anti-malware
    pulse/           Cron-like proactive scheduler
    queue/           Per-session message locking queue
    intercom/        Pub/sub inter-agent communication
    matcher/         Hybrid semantic matcher (TF-IDF + fuzzy + synonyms)
    logger/          Singleton logger with emoji mappings
    secrets/         Encrypted secrets management (AES-256-GCM)
    plugins/         Plugin discovery and loading
  plugins/           Plugin packages (keep the core tiny)
    channel/         Messaging integrations (Discord, Friends, etc.)
    provider/        LLM providers (OpenAI, etc.)
  src/
    cli/             CLI entry point
    landing/         Official landing page (Svelte + Vite)
    web/             Web UI (Svelte 5, Discord-like experience)

🐛 Issues

Please report any issues and bugs by [creating a new issue her