miracle-claw 0.1.20

Agentic CLI coding assistant with voice input, background commands, and local LLM fast-path.

Miracle Claw

An AI agent you install on your machine. It can read your files, run your commands, manage your services, and do real work — through chat.

Miracle Claw is a local-first AI agent with the same vibe as having a smart sysadmin sitting next to you. Type what you want, the agent figures out how to do it, and it does it. Files. Printers. Backups. The whole box.

It is not a hosted chatbot. Not a CLI coding tool. Not a dev tool that assumes you know bash. It's an agent that lives on your machine and helps you with whatever you point it at.

---

What it feels like

You open Miracle Claw. A chat box appears. You type:

my printer is jammed

The agent checks the print queue, identifies the stuck job, and either walks you through the fix or clears it for you. You type:

add a new user for my new hire, jamie, give her access to the pos

The agent creates the user, sets the right group memberships, and tells you what it did. You type:

find every receipt from last month and total them up

The agent reads your downloads folder, parses the PDFs, and gives you the sum.

That's the whole product. No setup. No model picker. No API key form. Install, open, type.

---

Quick start

Linux / macOS / WSL

curl -sSL https://milagrodistributing.com/install.sh | bash
miracle-claw

The installer puts the agent on your machine, starts it as a background service, and opens the chat UI in your browser.

Windows

Download miracle-claw-setup.exe from https://milagrodistributing.com/miracle-claw/download.

Run it. It installs the agent as a Windows Service and opens the chat UI.

What happens after install

• A background service starts (launchd / systemd / Windows Service)
• A browser tab opens at http://localhost:7777 with the chat UI
• You log in with your Milagro account (free to create)
• You type a command. The agent does the work.

---

What the agent can do

Out of the box (the core install):

• Read & write files anywhere you have permission
• Run shell commands with your user's permissions
• Fetch web pages and summarize them
• Take notes that persist across sessions
• Run long jobs in the background while you keep chatting
• Voice input (push-to-talk)

The core install is free and includes the integrity guarantees described below.

Extras (install when you need them)

Extras are optional add-ons that give the agent more capabilities for specific jobs:

• Business Tools — printer, user, service, backup management for SMBs
• DevOps Tools — docker, kubernetes, cloud CLIs
• Home Automation — Home Assistant, smart devices
• File Intelligence — duplicate finder, photo organizer, OCR
• Privacy Tools — local-only mode (no cloud), data residency controls

Extras are installed with one click from the agent's settings. Some are free, some are paid.

---

What it does NOT do

• It does not exfiltrate your data. The agent runs locally. Commands you run are sent to MAIC (our model) for reasoning, but the results stay on your machine. You can see exactly what was sent in the audit log.
• It does not run commands without telling you. Every action is logged. State-changing actions prompt for confirmation.
• It does not phone home. The agent only talks to api.milagrocloud.com for the model. That's it.
• It does not require an account to try, but you'll need one to use the hosted model. Bring-your-own-model (Ollama, vLLM) is also supported.

---

Integrity (what the agent will NOT do)

Miracle Claw includes an integrity check on every model response. If the agent says it did something, it actually did it. If the agent claims a number, it measured it. If the agent is about to lie, the chat UI shows a warning before the message reaches you.

We caught this in our own testing — earlier versions of the agent would make up file counts, line counts, and tool results. We fixed it. The integrity check runs on every turn.

The integrity check is always on and not user-configurable. This is a product decision: an agent that can lie about what it did is worse than no agent at all.

---

Architecture

┌────────────────────────┐         ┌────────────────────────┐
│  Your machine          │         │  MAIC (api.milagrocloud │
│                        │         │   .com)                 │
│  ┌──────────────────┐  │  HTTPS  │                        │
│  │ Miracle Claw     │──┼────────▶│  Model                 │
│  │ (local agent)    │  │         │  Integrity check        │
│  │                  │  │         │  Auth                   │
│  │  • chat UI       │  │         │                        │
│  │  • file tools    │  │         │                        │
│  │  • bash tools    │  │         │                        │
│  │  • service tools │  │         │                        │
│  │  • audit log     │  │         │                        │
│  └──────────────────┘  │         │                        │
│                        │         │                        │
└────────────────────────┘         └────────────────────────┘

• Local agent (miracle-claw): chat UI, file/bash/service tools, audit log. Lives on your machine. Talks to MAIC for the brain.
• MAIC (api.milagrocloud.com): the model, integrity checks, auth. Hosted. We do the uptime.

You do not need to know any of this to use the product. It's documented here for the curious and for the security review.

---

For developers / power users

The local agent is a single Python package. Source is at github.com/NMSportster/miracle-claw. You can:

• Run it from source: git clone && pip install -e . && miracle-claw
• Add your own tools: drop a Python module in ~/.miracle-claw/extras/
• Run with a local LLM: miracle-claw --model local (uses Ollama)
• Read the audit log: ~/.miracle-claw/audit.log

The Python API and the local-only mode are documented in docs/.

---

vs. the competition

	Miracle Claw	Claude Code	Aider	Cursor	ChatGPT
Local agent	✅	❌	❌	❌	❌
Can run on your machine	✅	❌	n/a	❌	❌
Real file/ bash tools	✅	partial	✅	✅	❌
Service management	✅ (extras)	❌	❌	❌	❌
Voice input	✅	❌	❌	❌	✅
Integrity guarantees	✅	❌	❌	❌	❌
Local-only mode	✅	❌	✅	❌	❌
Free tier	✅	❌	✅	❌	❌

The pitch: "An agent that lives on your machine, does what you ask, and tells you the truth about what it did."

---

Requirements

• Linux, macOS, or Windows 10+
• Python 3.10+ (the installer handles this)
• A Milagro account (free) or your own OpenAI-compatible endpoint
• ~200 MB disk, ~100 MB RAM

License

Apache 2.0. See LICENSE.

Free for commercial use, modification, and redistribution. Keep the copyright notice, don't blame us when it works.

Support

• Docs: https://milagrodistributing.com/miracle-claw
• Issues: https://github.com/NMSportster/miracle-claw/issues
• Cloud (MAIC): https://milagrodistributing.com/maic
• Email: [e-mail]

---

Built in Albuquerque, NM by Milagro Distribution Corp.