Introduction

Tiny Claw is an autonomous AI agent framework built from scratch. Simple, affordable, and truly personal - your own AI companion that grows with you.

Welcome to Tiny Claw

Your autonomous AI companion.

AI agents today are powerful but complex, expensive to run, and heavy to set up. Tiny Claw believes AI should be simple, affordable, and truly personal, like having your own Codsworth or AYLA as a helpful friend. It achieves this by being a native framework built from scratch with a tiny core, plugin architecture, self-improving memory, and smart routing that tiers queries to cut costs.

The result is an autonomous, self-improving, self-learning, and self-configuring personal AI companion that grows with you over time.

Tiny Claw is NOT a smaller version of OpenClaw. It is a completely independent product and an alternative to OpenClaw. While the original idea and inspiration came from OpenClaw (the lobster 🦞), Tiny Claw (the ant 🐜) has its own mission, architecture, and identity built from the ground up.

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.

Native Framework

Built from scratch with zero dependency on external AI frameworks. Every component is purpose-built for Tiny Claw.

Tiny Core, Plugin Everything

The core stays minimal. Channels, providers, and tools are all plugins. Add only what you need.

Self-Improving Memory

3-layer memory system with episodic, semantic FTS5, and temporal decay that learns what to remember and forget.

Smart Routing

8-dimension query classifier that tiers queries across providers, cutting LLM costs by routing simple queries to cheap models.

Discord-Like UI

Dark-themed web interface with real-time SSE streaming, typing indicators, and active agents sidebar - no terminal required.

Cost-Conscious

Uses Ollama Cloud with generous free tier. Smart routing slashes LLM spend by adapting to your installed provider plugins.

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.
• Cost-conscious. Smart routing tiers queries across your installed providers.

Key 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
Context Compactor	4-layer context compaction pipeline with rule-based pre-compression, shingle deduplication, LLM summarization
SHIELD.md Anti-Malware	Runtime SHIELD.md enforcement engine with threat parsing, pattern matching, and re-enforce action
5-Layer Security	Path sandbox, content validation, audit log, auto-backup, rate limiting
Delegation System	Autonomous sub-agent orchestration with self-improving role templates and blackboard collaboration
Bun-Native	Built on Bun for maximum performance, minimal footprint
Provider Fallback	Multi-provider support (Ollama, OpenAI, Anthropic) with automatic failover

Architecture

Tiny Claw uses a clean, modular architecture where everything above the plugin line is the tiny core. Channels, extra providers, and additional tools live as plugins.

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
    web/             Web UI (Svelte 5, Discord-like experience)

Under Active Development - This project is in heavy development and things will break. Running it now may spoil the experience we’re building for you. Please wait for the first official release before trying it out.

Next Steps

Quick Start

Get up and running with Tiny Claw in minutes

Installation

Detailed installation guide with prerequisites and configuration