Marvin Pilot

Your AI plans. You approve—or preauthorize a small limit. Marvin Pilot applies.

Why · Quick start · First plan · Safety · Full reference · Sponsors

Marvin Pilot is a local safety layer between an AI assistant and Amazing Marvin. The AI drafts an exact change plan; Pilot validates it against live state, shows you the result, applies only what you approve, and writes a receipt that can be reverted.

Your full-access Marvin credential stays on the Pilot side of the workflow instead of being placed in an AI prompt, plan, MCP configuration, command-line argument, or environment variable.

✨ Why Marvin Pilot?

• Review the whole change. Inspect a terminal summary or local before/after visualizer before anything is written.
• Catch stale plans. Account, title, hierarchy, timestamp, recurrence, and other locks are checked against live Marvin data.
• Keep an escape route. Every apply creates an integrity-checked receipt for conflict-aware full or selective revert.
• Choose the approval boundary. Confirm each normal apply, or explicitly preauthorize a small account-pinned impact limit for routine work.
• Keep private data local. Plans, backups, receipts, credentials, and the visualizer stay on your machine.

🧭 How it works

Marvin context  →  AI draft  →  prepare + validate  →  review  →  apply
                                                                  │
                                                                  └─ receipt → revert

1. An AI reads current work through a limited-access MCP, verified Pilot context, or a local Marvin backup.
2. The AI writes a strict plan or compact draft. prepare fills verified locks and produces the exact review artifact.
3. You run offline and read-only live validation, then inspect the terminal or browser preview.
4. Pilot rechecks current state immediately before each write, verifies the result, and journals a receipt.

🚀 Quick start

Marvin Pilot requires Python 3.11 or newer. Install the stable release from PyPI with pipx:

pipx install "marvin-pilot==1.0.1"
marvin-pilot --version

To install the current source checkout instead:

git clone https://github.com/rajpiskala/marvin-pilot.git
cd marvin-pilot
pipx install .

In Amazing Marvin, open Settings → API and create both credentials:

• Give the read/discovery MCP only the limited API_TOKEN.
• Store FULL_ACCESS_TOKEN for Marvin Pilot, preferably in your operating system credential store.

marvin-pilot config set-credential-mode keyring
marvin-pilot config set-full-access-token
marvin-pilot doctor

doctor makes one read-only identity request and confirms which Marvin account the credential belongs to. See the setup reference for MCP launcher configuration, platform-specific commands, and stricter credential modes.

🛫 Your first plan

Start small. Ask your AI:

Read my Marvin tasks through the Amazing Marvin MCP. Draft a Marvin Pilot change plan with at most 10 low-risk operations and save it under plans/. Do not use MCP mutation tools and do not run marvin-pilot apply or marvin-pilot revert; I will review and run those myself.

Then review the same artifact at every stage:

marvin-pilot validate plans/first-plan.json
marvin-pilot validate plans/first-plan.json --live
marvin-pilot describe plans/first-plan.json
marvin-pilot visualize plans/first-plan.json
marvin-pilot apply plans/first-plan.json

If you need to undo it:

marvin-pilot revert path/to/applied-receipt.json

The full guide covers compact draft preparation, bounded unattended apply, backup-powered historical context, and dependent plan sets.

🧰 Core commands

Run marvin-pilot --help, marvin-pilot COMMAND --help, or read the complete command reference.

🛡️ Safety at a glance

• Normal apply and every revert require an interactive terminal and explicit approval. apply --yes skips only the final prompt after review; it does not skip validation or verification.
• Optional unattended apply must be enabled by a human in advance and is pinned to one account and a maximum impact. It is an accident guard, not a security boundary against malicious local software.
• The full-access credential is loaded only for live commands and is never written to a plan or receipt.
• Pilot-managed deletion uses Marvin's document API, not Marvin's native Trash UI. Recovery depends on the private receipt snapshot, so keep receipts secure and backed up.
• Plans and receipts may contain personal task content. plans/, local history, backups, and development artifacts should never be committed casually.

Read the full safety model and security policy before using Marvin Pilot on important workflows.

📚 Documentation

• Comprehensive user and behavior reference
• Live contract-test runbook
• Release notes
• Security policy

GitHub automatically provides an outline for this README. The compact links at the top cover the common path; detailed navigation lives in the reference guide.

💖 Sponsors

If Marvin Pilot saves you time, sponsor its continued development. Sponsorship helps fund maintenance, testing across Marvin workflows, and safer automation features.

🧑‍💻 Development

python -m venv .venv
python -m pip install -e ".[dev]"
python -m pytest --cov=marvin_pilot
python -m ruff format --check src tests
python -m ruff check src tests

See the development reference before running browser or live-account contract tests.

📌 Project status

Marvin Pilot is an independent community project and is not affiliated with or endorsed by Amazing Marvin. The repository, CLI command, import package, and PyPI distribution all use the Marvin Pilot name.

Released under the MIT License.