Metadata-Version: 2.4
Name: miracle-claw
Version: 0.1.3
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
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 (mlg)

**An agentic CLI coding assistant that runs anywhere Python runs. Free, source-available, BYO model.**

mlg is a terminal-first AI coding tool. It has slash commands, voice input,
background job control, inline `@file` mentions, tab completion, and routes
to any OpenAI-compatible endpoint — local Ollama, your own gateway, or
managed cloud.

It is the open-source alternative to Claude Code and Aider, with two things
neither of them have:

1. **Push-to-talk voice input** — speak a task, get a shell command.
2. **Local-first fast path** — point it at Ollama and skip the cloud entirely.

---

## Quick start

### Path 1 — Docker (works on Windows, macOS, Linux)

```bash
git clone https://github.com/milagro-distribution/miracle-claw.git
cd miracle-claw
echo "MILAGRO_API_KEY=sk-..." > .env
docker compose run --rm mlg
```

For the browser frontend: `docker compose --profile serve up` → http://localhost:7777

### Path 2 — pip install (Linux/macOS/WSL)

```bash
pip install miracle-claw[voice]
export MILAGRO_API_KEY=sk-...
mlg
```

For one-shot mode:

```bash
mlg "list all files modified today"
```

For the interactive REPL:

```bash
mlg
⚡ miracle_claw
  model : milagro-dev
  url   : http://localhost:8080/v1
  cwd   : /home/you
  help  : type '?' or 'help'  ·  quit: 'exit'  ·  raw: '!cmd'

⚡ how do I find large files?
```

---

## Features

### Slash commands (19)

| | | |
|---|---|---|
| `/help` | `/read PATH` | `/edit PATH` |
| `/diff A B` | `/tree [N]` | `/pwd` |
| `/model [NAME]` | `/url [URL]` | `/history [N]` |
| `/clear` | `/run CMD...` | `/git SUBCMD` |
| `/cd [PATH]` | `/alias [NAME CMD]` | `/voice [SECS]` |
| `/jobs` | `/tail ID [N]` | `/kill ID` · `/wait ID` |

### Inline mentions

Type `@somefile.py` anywhere in a prompt and mlg will read the file
(4 KB cap per file, 16 KB total) and include it as context:

```
⚡ @jobs.py explain the reaper thread
```

### Voice input

```
⚡ /voice
  ▸ listening... (press Enter to stop)
▸ make me a directory tree of mlg's repo
  send to LLM? [Y/n/e(dit)]: y
  ✓ 4.2s · maic:milagro-dev
```

Requires `arecord` (ALSA) and a one-time pip install of `faster-whisper`
into a side venv. mlg finds it automatically.

### Background commands

```
⚡ ! make test &
  ▸ background job j3a7 (pid 48291): make test
    log: ~/.miracle_claw/jobs/j3a7.log
    /jobs · /tail j3a7 · /kill j3a7 · /wait j3a7

⚡ /jobs
  ID     PID     STATUS        ELAPSED   CMD
  j3a7   48291   ● running     12s       make test

⚡ /tail j3a7
  ── j3a7 (✓ exit 0, 47s) ───────────────
  Building...
  test_jobs.py ........... PASSED
  ✓ all 14 tests passed
```

### Local LLM fast path

```
⚡ /model
  current: milagro-dev → milagro-dev via maic
  Local fast-path aliases (Ollama, no MAIC):
    local          → llama3.2
    local-big      → mistral
    local-huge      → gemma4
    coder-local    → llama3.2
  Switch with:  /model <name|alias>

⚡ /model local
  ✓ model → local  →  llama3.2  via ollama  (no MAIC hop)
```

No MAIC hop means **no API key needed** for local models. Cold start
~20s (disk load); hot path 2-5s on CPU.

### Session persistence

mlg saves your cwd, model, URL, and aliases to `~/.miracle_claw/session.json`
on exit and restores them on next start. Run `mlg --reset-session` to clear.

---

## Architecture

```
miracle_claw/
├── mlg              # main entry: arg parsing, REPL loop, atexit
├── mlg-serve        # WebSocket + xterm.js browser frontend
├── llm.py           # MAIC + Ollama clients, model resolution
├── turn.py          # one full turn: prompt → call → parse → run → log
├── commands.py      # slash command dispatch (19 commands)
├── completion.py    # tab completion (slash + paths, no readline)
├── repl.py          # custom line editor (raw mode, ANSI-aware)
├── safety.py        # risk classification (SAFE / NORMAL / DANGEROUS)
├── runtime.py       # bash/python/perl subprocess wrappers
├── history.py       # session log reader (JSONL)
├── mentions.py      # @file inline mention resolver
├── session.py       # cwd/model/url persistence
├── aliases.py       # user-defined command aliases
├── jobs.py          # background job registry
├── voice.py         # arecord + faster-whisper
├── ui.py            # ANSI color helpers
├── context.py       # project context builder
├── CLAW.md          # system prompt (user-editable)
└── CLAW.md.example  # fallback system prompt
```

**Design choices:**

- One file per concern, ~100-400 lines each. Easy to read, easy to swap out.
- The custom line editor in `repl.py` replaces Python `readline` because
  `readline` + PTY canonical mode + ANSI prompts fight each other (tabs
  get eaten, `input()` blocks on `\n`).
- LLM client (`llm.py`) is the only module that does HTTP. Mocking for
  tests, swapping gateways, and adding retry/backoff all happen in one place.
- `urllib.request` everywhere (no extra HTTP deps).

---

## vs. the competition

| | mlg | Claude Code | Aider | Cursor |
|---|---|---|---|---|
| Free, source-available | ✅ | ❌ | ✅ | ❌ |
| Voice input | ✅ | ❌ | ❌ | ❌ |
| Background commands | ✅ | ❌ | ❌ | ❌ |
| Local model routing | ✅ | ❌ | ✅ | ❌ |
| Inline `@file` mentions | ✅ | ✅ | ✅ | ❌ |
| Tab completion | ✅ | ❌ | ❌ | n/a |
| Browser frontend | ✅ | ❌ | ❌ | n/a |
| Vendor lock-in | none | Anthropic | none | OpenAI |

**The pitch**: "Claude Code's UX, Aider's openness, and two features nobody
else has. Free if you bring your own model."

---

## Requirements

- Python 3.10+
- `urllib` (stdlib only)
- Optional: `arecord` + `ffmpeg` for voice input
- Optional: `ollama` running locally for the fast-path
- Optional: a TTY for the REPL (works fine in the browser via `mlg-serve`)

## License

Apache 2.0. See [LICENSE](LICENSE).

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

## Support

- Issues: <https://github.com/milagro-distribution/miracle-claw/issues>
- Docs: <https://milagrodistributing.com/miracle-claw>
- Cloud (MAIC): <https://milagrodistributing.com/maic>
- Email: <david@milagrodistributing.com>

---

Built in Albuquerque, NM by Milagro Distribution Corp.
