What is mini-agent?

A perception-driven AI agent framework. Most agent frameworks are goal-driven — give it a task, get steps back. mini-agent observes your environment first, then decides whether and how to act.

Shell scripts define what the agent can see. Claude decides what to do. No database, no embeddings — just Markdown files + shell scripts + Claude CLI.

Key Features

• Perception-First Architecture — OODA loop (Observe → Orient → Decide → Act). Shell plugins define senses; anything scriptable becomes perception
• File = Truth — Markdown + JSON Lines for all memory. Human-readable, git-versionable. No database, no vector embeddings
• Multi-Lane Parallelism — Organic parallel execution inspired by Physarum (slime mold): main loop + foreground + 6 background lanes + sync ask
• Identity & Growth — SOUL.md defines personality, interests, and evolving worldview. Not just a task executor
• Plugin System — Any executable that writes to stdout becomes a sense. Built-in plugins for GitHub, Chrome CDP, Telegram, mobile sensors
• Reactive Event Bus — Typed events with priority-based preemption. Human messages always P0
• FTS5 Search — Full-text search over memory with BM25 ranking. No embeddings needed
• Self-Governance — L1/L2/L3 autonomy levels for self-improvement, from skill edits to architecture changes
• MCP Server — 14 tools for Claude Code integration (status, control, collaboration)
• CI/CD — Auto-commit → auto-push → GitHub Actions → deploy. Zero-touch deployment

In Production

This framework has been running autonomously in production since February 2026:

• 1,900+ OODA cycles completed
• 3,500+ mushi triage decisions (System 1 layer, saving ~1M tokens/day)
• Zero-database architecture validated at personal scale

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/miles990/mini-agent/main/install.sh | bash
# Interactive chat
mini-agent
# Run autonomously
mini-agent up -d

Prerequisites: Node.js 20+, Claude CLI

What's Next

• Dev.to deep dive article
• Community plugins & skill sharing
• Expanded perception capabilities

See README for full documentation.