Metadata-Version: 2.4
Name: miracle-claw
Version: 0.1.18
Summary: Agentic CLI coding assistant with voice input, background commands, and local LLM fast-path.
Author-email: "Milagro Distribution Corp." <hello@milagrodistributing.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://milagrodistributing.com/claw
Project-URL: Source, https://github.com/NMSportster/miracle-claw
Project-URL: Issues, https://github.com/NMSportster/miracle-claw/issues
Project-URL: Changelog, https://github.com/NMSportster/miracle-claw/blob/master/CHANGELOG.md
Keywords: ai,cli,coding,agent,voice,local-llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: CHANGELOG.md
License-File: INSTALL.md
License-File: CLAW.md
Requires-Dist: httpx>=0.27
Provides-Extra: voice
Requires-Dist: faster-whisper>=1.0.0; extra == "voice"
Provides-Extra: serve
Requires-Dist: aiohttp>=3.9; extra == "serve"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
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/](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](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: <david@milagrodistributing.com>

---

Built in Albuquerque, NM by Milagro Distribution Corp.
