miniclaw 0.1.3

Your tiny coding claw
Learn to build an AI coding agent in ~1500 lines of Python

What is miniclaw?

Ever wondered how tools like Claude Code or OpenClaw actually work under the hood? miniclaw is the answer -- a minimal, hackable AI coding agent you can read through in an afternoon.

The name says it all: mini + claw (from OpenClaw). No sprawling architecture, no thousand-file monorepo. Just the essential loop that powers every AI coding assistant:

You type a request
  -> LLM thinks
    -> LLM calls tools (read / write / edit / grep / glob / bash)
      -> Tools execute in your workspace
        -> LLM sees the result
          -> Repeat until done

If you want to learn, teach, or hack on an AI agent, start here.

Features

• 9 Tools -- read, write, edit, glob, grep, bash, Skill, memory, session_search. Workspace file ops plus on-demand skills, persistent memory, and past-session recall.
• Plan Mode -- The agent can enter a read-only planning phase: explore code, produce a structured plan, then execute only after you approve. Write operations are blocked until you say go.
• Skills System -- Drop a SKILL.md into .miniclaw/skills/<name>/ and the agent learns new tricks. Skills are injected into the system prompt automatically; the Skill tool loads full instructions on demand.
• Memory -- Durable facts live in ~/.miniclaw/memory/MEMORY.md and are auto-injected each session. The agent can read/write topic files for longer notes.
• Session Search -- Conversations are recorded locally; the agent can browse, full-text search, or scroll through past sessions.
• Context Management -- Micro-compaction and auto-summarize keep long conversations within the context window.
• Any OpenAI-compatible LLM -- Swap models by changing one environment variable. Default: MiniMax-M2.7.
• Workspace Isolation -- All file operations are sandboxed to your workspace directory. No .. path escapes.

Quick Start

Install:

pip install miniclaw

Run:

export LLM_API_KEY=your_api_key
cd ~/my-project
miniclaw

That's it. You're talking to an AI agent that can read, write, and run code in your project.

pip install pipx
pipx ensurepath
pipx install miniclaw

git clone https://github.com/sundl123/miniclaw.git
cd miniclaw
pip install -e .

Tip: If you get command not found: miniclaw after installing, your Python scripts directory isn't in PATH. Run pipx ensurepath (pipx) or add ~/.local/bin to your PATH (pip).

How It Works

The entire agent fits in a handful of Python modules. Here's the core loop:

flowchart LR
    User([You]) -->|message| REPL[cli.py<br>REPL]
    REPL -->|messages + tools| LLM[api.py<br>LLM API]
    LLM -->|tool_call| Tools[tools.py<br>9 Tools]
    Tools -->|result| LLM
    LLM -->|final reply| REPL
    REPL -->|display| User

Each module has a single responsibility -- read through them in this order:

Commands

Keyboard shortcuts: Ctrl+J newline, Up/Down history, Ctrl+C cancel, Ctrl+D exit.

Configuration

Config is JSON, with two layers: global (~/.miniclaw/config.json) and workspace ({workspace}/.miniclaw/config.json). Workspace config wins.

Run miniclaw init to create the default config. Use miniclaw init --force to reset.

{
  "llm": {
    "api_key": "your_api_key",
    "model": "MiniMax-M2.7",
    "base_url": "https://api.minimaxi.com/v1",
    "timeout": 300
  },
  "plan_mode": {
    "allowed_bash_patterns": ["^curl\\s+-s"]
  },
  "memory": {
    "enabled": true
  },
  "sessions": {
    "enabled": true
  }
}

All llm fields can be overridden by environment variables (env vars take priority):

Skills

Create .miniclaw/skills/<skill-name>/SKILL.md with YAML frontmatter (name, description) and instructions in the body. The agent sees the skill list at startup and reads the full SKILL.md on demand.

File Layout

~/.miniclaw/                    # User-level (shared across workspaces)
├── logs/                       # Runtime logs
├── memory/                     # Persistent memory (MEMORY.md + topic files)
├── sessions/                   # Session DB (SQLite + FTS)
└── config.json                 # Global config (optional)

{workspace}/.miniclaw/          # Workspace-level (per project)
├── config.json                 # Workspace config (higher priority)
├── plans/                      # Plan files
└── skills/                     # Skills directory

Project Structure

miniclaw/
├── chat.py              # Dev entry point (same as `miniclaw` command)
├── pyproject.toml       # Package config
├── CHANGELOG.md         # Release history
├── miniclaw/            # The Python package
│   ├── cli.py           # REPL
│   ├── api.py           # LLM API + tool loop
│   ├── tools.py         # Tool dispatch
│   ├── context/         # Context compaction + summarization
│   ├── memory/          # Persistent memory tool
│   ├── sessions/        # Session records + search
│   ├── plan_mode.py     # Plan mode permissions
│   ├── config.py        # Path safety + constants
│   ├── dirs.py          # Directory resolution
│   ├── settings.py      # Config loading + merge
│   ├── skills.py        # Skill scanning
│   ├── ui.py            # Terminal UI (rich)
│   └── dev_logging.py   # Dev logging
├── tests/               # Unit tests
└── docs/design/         # Design docs
    └── miniclaw-architecture-analysis.md

Changelog

See CHANGELOG.md for release history.

Design Documents

Running Tests

python3 -m pytest tests/ -v

Contributing

miniclaw is meant to stay small and readable. PRs that keep things simple are welcome.

License

MIT