Noureddine RAMDI / miniclawd: a compact multi-LLM personal AI assistant in TypeScript

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
947 Words
github-stars typescript ai-assistant bun multi-llm chatbot personal-ai

FoundDream/miniclawd

miniclawd packs a full personal AI assistant experience into just under 6,000 lines of TypeScript code. It supports multiple large language model backends, multi-channel chat, persistent memory with daily notes, scheduled tasks, and a Markdown-based skill system — all designed to run efficiently with Bun and installed globally via npm. For those looking to understand how to build a lean but capable AI assistant, miniclawd offers a solid, practical case study.

What miniclawd does and how it is architected

At its core, miniclawd is a modular AI assistant framework written in TypeScript and designed to run on the Bun runtime. The codebase is compact — roughly 5,900 lines — yet it integrates several advanced features that typically bloat AI assistants.

It supports multiple LLM backends out of the box, including Anthropic, OpenAI, Google, OpenRouter, Groq, and AWS Bedrock. This multi-LLM support allows users to choose or switch providers depending on availability, pricing, or capabilities.

On the communication front, miniclawd connects to chat platforms such as Telegram and Feishu (also known as Lark) through a multi-channel gateway. This gateway abstracts channel-specific details and routes messages seamlessly to the core agent logic.

Persistent memory is handled with a daily notes system, allowing the assistant to keep long-term context and recall past information across sessions. This is critical for personal assistants aiming to maintain continuity over time.

The skill system is particularly interesting: it uses Markdown files to define extensible skills that the AI can invoke. This approach makes it easy to add or modify capabilities without deep changes to the codebase.

Scheduling support is built-in via cron jobs, enabling timed tasks with heartbeat checks to ensure reliability. For heavier or asynchronous workloads, miniclawd can spawn subagents that run in the background, keeping the main agent responsive.

Configuration is centralized in a single JSON file located at ~/.miniclawd/config.json, simplifying setup and management.

Technical strengths and design tradeoffs

The standout technical strength of miniclawd is how it balances feature richness with codebase size and simplicity. Supporting six distinct LLM backends plus multiple chat platforms in under 6,000 lines of TypeScript is no small feat.

Using Bun as the runtime is a notable choice. Bun offers improved startup times and performance for TypeScript/JavaScript applications compared to Node.js, which helps keep the assistant responsive.

The Markdown-based skill system is an elegant way to separate core logic from extendable features. It allows developers and users to add new skills in a readable, declarative format without modifying TypeScript code directly. However, Markdown as a skill definition format may limit complex logic expressiveness compared to programmatic plugins.

The persistent memory using daily notes is a pragmatic tradeoff. It provides a simple, file-based way to store context long-term, suitable for personal use cases. But it likely lacks the robustness and query capabilities of a dedicated database or vector store, which might limit scaling or advanced retrieval.

Subagent spawning for background tasks is a clean way to offload work without blocking the main agent loop, improving responsiveness. The tradeoff is added complexity in managing subagent lifecycle and communication.

Configuration via a single JSON file is straightforward and lowers the barrier to entry. The downside is potential for configuration bloat as features grow, and lack of dynamic or environment-based config options out of the box.

Overall, the code quality appears thoughtfully organized to keep the footprint small while offering a surprisingly complete feature set, making it a good reference for building lean AI assistants.

Quick start

Installation and setup are straightforward. The README provides a single command to install miniclawd globally via npm:

npm install -g miniclawd@latest

This simplicity is nice for anyone wanting to try the assistant without fuss. After installation, configuration can be done by editing the JSON file at ~/.miniclawd/config.json.

From there, you can start the assistant, connect your preferred LLM backends, set up chat channels, and begin interacting with your personal AI.

Verdict

miniclawd is a solid example of building a multi-LLM personal AI assistant that doesn’t bloat into tens of thousands of lines or rely on heavyweight infrastructure. It’s particularly relevant for developers interested in AI agents who want to see how to integrate multiple LLM providers, persistent memory, scheduling, and extensible skills in a compact TypeScript codebase.

That said, miniclawd’s use of Markdown for skills and file-based memory indicates it’s optimized for personal or small-scale use rather than enterprise-grade deployments. Its reliance on Bun is a plus for performance, though it may pose compatibility considerations for some environments.

If you want a lightweight, extensible AI assistant framework with multi-channel chat and multi-LLM support that you can install and configure easily, miniclawd is worth a close look. Its design choices and tradeoffs provide practical lessons in lean AI agent architecture.

→ GitHub Repo: FoundDream/miniclawd ⭐ 136 · TypeScript