Malikclaw

🎬 Live Terminal Demo

⚡ 30-Second Overview

What is MalikClaw?

MalikClaw is a production-grade, zero-dependency personal AI agent engine engineered in Go. Designed for extreme resource efficiency, it brings autonomous AI capabilities—tool execution, multi-step planning, persistent memory, and omnichannel messaging—to low-power single-board computers (SBCs), Android phones, local edge nodes, and cloud containers.

Why Use MalikClaw?

• 🪶 <10MB Idle RAM & <1s Startup: 99% lighter than heavy Python agent frameworks (AutoGen, CrewAI, LangChain).
• 💰 Runs on $10 Hardware: Deploys seamlessly on Orange Pi Zero, Raspberry Pi Zero 2 W, recycled Android smartphones (via Termux), and low-tier VPS instances.
• 💬 15+ Messaging & Social Channels: Unified gateway for Telegram, Discord, WhatsApp, Matrix, Slack, TikTok, LinkedIn, Twitter/X, Reddit, WeCom, QQ, DingTalk, LINE, Feishu, and MaixCam.
• 📱 Native Mobile ADB & Termux Control: Autonomous phone automation—take screenshots, tap UI elements, swipe, type, and launch apps.
• 🛡️ Security-First Sandboxing: Workspace jailing (restrict_to_workspace), command regex filtering, and safe path allowlisting.
• 🤖 Guardian Engine: Autonomous code auditing, debugging, and self-patching capabilities.

⚡ 30-Second Quick Start

1. One-Line Installation

Linux / macOS / Termux:

curl -fsSL https://raw.githubusercontent.com/AbdullahMalik17/malikclaw/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/AbdullahMalik17/malikclaw/main/install.ps1 | iex

Docker:

docker run -d --name malikclaw -p 18790:18790 -v ~/.malikclaw:/root/.malikclaw ghcr.io/abdullahmalik17/malikclaw:latest

2. Configure & Run Your First Agent Command

# Run interactive onboarding setup
malikclaw onboard

# Execute a direct CLI prompt
malikclaw agent -m "Summarize the system specs of this machine and save it to specs.md"

# Start the web UI and omnichannel gateway (Dashboard on http://localhost:18790)
malikclaw gateway

💻 Embed MalikClaw in Go (Production Snippet)

MalikClaw can be embedded directly into your Go microservices as a lightweight agent runtime:

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/AbdullahMalik17/malikclaw/pkg/agent/agentloop"
	"github.com/AbdullahMalik17/malikclaw/pkg/providers"
	"github.com/AbdullahMalik17/malikclaw/pkg/tools"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
	defer cancel()

	// 1. Initialize LLM Provider (OpenAI, Anthropic, Gemini, Ollama, etc.)
	provider, err := providers.NewOpenAIProvider("sk-proj-your-api-key", "gpt-4o-mini")
	if err != nil {
		log.Fatalf("Failed to initialize provider: %v", err)
	}

	// 2. Initialize Tool Registry with standard workspace tools
	toolRegistry := tools.NewRegistry("/home/user/workspace")
	if err := toolRegistry.RegisterDefaults(); err != nil {
		log.Fatalf("Failed to register tools: %v", err)
	}

	// 3. Configure the 5-Stage Agentic Loop
	cfg := agentloop.DefaultLoopConfig("/home/user/workspace")
	cfg.MaxIterations = 10
	cfg.EnableReflection = true

	// 4. Instantiate & Run Agent Loop
	loop := agentloop.NewAgentLoop(cfg, toolRegistry, provider)
	defer loop.Close()

	result, err := loop.ExecuteGoal(ctx, "Research recent Go 1.24 features and write a summary in go_features.md")
	if err != nil {
		log.Fatalf("Agent execution failed: %v", err)
	}

	fmt.Printf("Goal Achieved: %t | Actions Taken: %d | Duration: %s\n",
		result.Success, result.ActionsTaken, result.Duration)
}

📊 Performance Benchmarks (MalikClaw vs Python Frameworks)

Benchmarked on single-core 0.8GHz ARMv7 (Orange Pi Zero, 512MB RAM) and x86_64 VPS (1 vCPU, 1GB RAM):

🏛️ High-Level System Architecture

graph TD
    UserClient["Clients / Inbound Channels<br/>(Telegram, Discord, WhatsApp, Web UI)"] --> Gateway["Omnichannel Gateway<br/>(Port 18790 Webhook Server)"]
    Gateway --> Bus["Unified MessageBus<br/>(Go Channels / Events)"]
    Bus --> Loop["5-Stage Agent Loop<br/>(pkg/agent/agentloop)"]
    
    subgraph AgenticEngine ["5-Stage Agentic Core"]
        Loop --> Plan["1. Planner<br/>(ReAct Subtask Graph)"]
        Plan --> Act["2. Executor<br/>(Tool Execution &amp; Circuit Breaker)"]
        Act --> Obs["3. Observer<br/>(Output Schema Normalizer)"]
        Obs --> Ref["4. Reflector<br/>(Outcome &amp; Lesson Critic)"]
        Ref --> Mem["5. Memory Manager<br/>(Markdown Storage &amp; Search)"]
    end
    
    Act --> Sandbox["Security Sandbox<br/>(Workspace Jailing &amp; Regex Filtering)"]
    Sandbox --> Tools["Registered Tools<br/>(Shell, File, Web, ADB, MCP)"]
    Loop --> ProviderLayer["Provider Router &amp; Fallback Chain"]
    ProviderLayer --> LLMBackends["LLM APIs &amp; Local Models<br/>(OpenAI, Anthropic, Gemini, Ollama)"]
    Loop --> Guardian["Guardian Engine<br/>(Autonomous Self-Patching)"]

🔄 The 5-Stage Agent Loop Architecture

graph LR
    Goal["Inbound Goal"] --> PLAN["PLAN<br/>Decompose goal into subtask graph"]
    PLAN --> ACT["ACT<br/>Execute sandboxed tool action"]
    ACT --> OBSERVE["OBSERVE<br/>Capture &amp; normalize execution output"]
    OBSERVE --> REFLECT["REFLECT<br/>Evaluate success &amp; extract lessons"]
    REFLECT --> MEMORY["MEMORY UPDATE<br/>Persist state to Markdown logs"]
    MEMORY --> Choice{"Goal Achieved?"}
    Choice -- "No / Retry" --> PLAN
    Choice -- "Yes" --> Response["Return Final Output"]

✨ Core Features & Capabilities

• 🧠 5-Stage Production Agent Loop: Complete cycle of planning, step execution, output observation, reflection, and persistent memory updates.
• 💬 Omnichannel Messaging Engine: Native integration with 15+ channels (Telegram, Discord, WhatsApp, Matrix, WeCom, QQ, DingTalk, LINE, Feishu, Slack, MaixCam, TikTok, LinkedIn, Twitter/X, Reddit).
• 📱 Mobile & Android ADB Automation: Direct mobile control over USB/Wi-Fi ADB or headless native execution inside Android Termux.
• 🌐 Web Interface & Dashboard: Modern Bento Grid UI listening on http://localhost:18790 with real-time logs, agent controls, and chat shortcuts.
• 🛡️ Workspace Jailing & Security Sandboxing: Enforced directory boundaries, regex-based terminal command blocking, and strict secret protection.
• 🔌 MCP (Model Context Protocol) Support: Connect third-party Model Context Protocol servers to dynamically extend agent capabilities.
• 🛠️ Guardian Self-Evolution: Autonomous code inspection and safe git-diff patching for self-healing software agents.
• 🌍 RTL & Multilingual Translation: Built-in localization support for English, Urdu (RTL), Japanese, French, Portuguese, Vietnamese, and more.

🤖 Supported Model Providers & Web Search Engines

LLM Providers

• OpenAI: gpt-4o, gpt-4o-mini, o1, o3-mini
• Anthropic: claude-3-7-sonnet, claude-3-5-haiku (Native & Messages API, Prompt Caching)
• Google AI & Antigravity: Gemini 2.5 Pro, Gemini 2.5 Flash, Cloud Code Assist integration
• Ollama (Local Models): Llama 3.3, DeepSeek-R1, Qwen 2.5, Mistral (http://localhost:11434/v1)
• Groq: Ultra-fast LLaMA & Mixtral inference
• DeepSeek: DeepSeek-V3, DeepSeek-R1
• Zhipu GLM: GLM-4 Flash / Plus
• OpenRouter & ModelScope: Unified proxy access to hundreds of open/closed models

Web Search Providers

• DuckDuckGo: Free zero-config default search engine
• Tavily: AI-optimized structured research API
• Brave Search: Fast, independent privacy-first web index
• Perplexity: Conversational AI search
• SearXNG: Self-hosted privacy meta-search engine

🖥️ Platform & Hardware Support

📚 Documentation Index

• QUICKSTART.md: 5-minute onboarding & initial command guide.
• INSTALLATION.md: Detailed installation options (One-liner, Docker, Brew, Source).
• ARCHITECTURE.md: Deep-dive into internal packages, subsystems, and Go API patterns.
• FAQ.md: Frequently asked questions on setup, performance, ADB, and security.
• CHANGELOG.md: Version history, release notes, and migration steps.
• SECURITY.md: Threat model, directory sandboxing, and security policies.
• CODE_OF_CONDUCT.md: Community guidelines and standards.
• CONTRIBUTING.md: Developer guide for submitting code, tools, and translations.
• ROADMAP.md: Future technical vision and community priorities.

📄 License & Attribution

MalikClaw is licensed under the MIT License. See LICENSE for details.