miracle-claw 0.1.1

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

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)

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)

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

For one-shot mode:

mlg "list all files modified today"

For the interactive REPL:

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.

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: [e-mail]

---

Built in Albuquerque, NM by Milagro Distribution Corp.