Metadata-Version: 2.4
Name: miracle-claw-extras
Version: 0.3.0
Summary: Companion CLI tools for Miracle Claw: config, doctor, stats, cost, export, share, restore, diff, bench, template.
Author-email: "Milagro Distribution Corp." <hello@milagrodistributing.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/NMSportster/miracle-claw-extras
Project-URL: Source, https://github.com/NMSportster/miracle-claw-extras
Project-URL: Issues, https://github.com/NMSportster/miracle-claw-extras/issues
Project-URL: Changelog, https://github.com/NMSportster/miracle-claw-extras/blob/main/CHANGELOG.md
Project-URL: Parent project, https://github.com/NMSportster/miracle-claw
Keywords: miracle-claw,mlg,ai,cli,agent,developer-tools,session-management,diagnostics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: CHANGELOG.md
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0; extra == "pdf"
Provides-Extra: voice
Requires-Dist: faster-whisper>=1.0.0; extra == "voice"
Provides-Extra: all
Requires-Dist: miracle-claw-extras[pdf,voice]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# Miracle Claw - Extras

**Companion CLI tools for [Miracle Claw](https://github.com/NMSportster/miracle-claw).**

Miracle Claw is a talk-to-LLM-and-run-code shell. This package adds 10
companion commands that make working with Miracle Claw easier, faster, and
more transparent.

```
$ pip install miracle-claw-extras
$ mlg-doctor          # diagnose your install
$ mlg-stats --period 30d    # show your usage
$ mlg-share           # bundle a session for sharing
```

## The 10 Commands

| Command | What it does |
|---|---|
| `mlg-config` | Interactive config generator. Walks you through setup, or show/edit/validate/reset/import/export your existing config. |
| `mlg-doctor` | Health check. Detects missing deps, broken configs, unreachable services. Can auto-fix common issues. |
| `mlg-bench` | Benchmark sub-agents. Runs standard prompts through each agent and reports timing + quality. |
| `mlg-export` | Export sessions. JSON, Markdown, HTML, plain text, or PDF. Useful for sharing, archiving, or posting to a blog. |
| `mlg-stats` | Usage statistics. Total turns, time, by-model, by-day, by-hour, by-status. From your local history, no MAIC needed. |
| `mlg-diff` | Compare things. Two sessions, two configs, two outputs. Shows unified diff, side-by-side, or JSON. |
| `mlg-template` | Project scaffolding. 5 built-in templates (python-cli, python-api, web-app, tauri-desktop, mlg-skill). Add your own from git. |
| `mlg-restore` | Restore a session from a `.mlgsnap` bundle. Verifies the bundle, imports it as a local snapshot, and lists/deletes existing snapshots. |
| `mlg-share` | Bundle a session. Creates a `.mlgsnap` zip archive with the session, code, and optional config. SHA256-checksummed for tamper detection. |
| `mlg-cost` | Cost breakdown. Estimated spend by model, by day. Configurable per-model pricing. |

Each command is also a standalone entry point, so you can type `mlg-doctor`
directly without `mlg-extras doctor`.

## Quickstart

```bash
# Install
pip install miracle-claw-extras

# Check your install
mlg-doctor

# See your usage this month
mlg-stats --period 30d

# Share a session with a teammate
mlg-share --output session.mlgsnap
# → send them session.mlgsnap
# → they run: mlg-restore session.mlgsnap
```

## Documentation

- [Installation guide](docs/installation.md)
- [Quickstart](docs/quickstart.md)
- [Command reference](docs/commands/) — one page per command
- [Development guide](docs/development.md) — how to add a new command
- [Troubleshooting](docs/troubleshooting.md)

## Requirements

- Python 3.10 or later
- A working [Miracle Claw](https://github.com/NMSportster/miracle-claw)
  install (some commands read from `~/.miracle_claw/`)
- The package itself is pure Python with three small deps: `click`, `rich`, `pyyaml`

## License

Apache 2.0. See [LICENSE](LICENSE).

Copyright 2026 Milagro Distribution Corp.

## Related projects

- [miracle-claw](https://github.com/NMSportster/miracle-claw) — the parent CLI
  (Apache 2.0, also by Milagro Distribution Corp.)
