# Marv

> Drive the marv language toolchain — author, check, repair, run, verify, and commit .mv programs via the generate→check→repair loop. Use when working with .mv source, .core.json Core-IR snapshots, the `marv` CLI, or the marv MCP server / JSON-RPC protocol.

- Skill: `joaoh82/marv` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joaoh82/marv`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joaoh82/marv/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: joaoh82 (https://skillmd.com/u/joaoh82)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joaoh82/marv

---


# Driving marv

marv is a compiled language whose author is a coding agent and whose auditor is a human. The
compiler is a service (JSON-RPC, salsa-incremental) plus a CLI. Your job is to run the loop
tightly and respect the invariants. Full context: [`docs/agents.md`](../../../docs/agents.md),
[`README.md`](../../../README.md), and `spec/03` (the protocol).

## The loop

1. **check** the file(s) you generated (`marv check <file>`, or the `marv_check` MCP tool).
2. If there are errors, prefer **applying the fix** a diagnostic carries (confidence ≥ 0.8)
   over regenerating; otherwise regenerate the offending definition using the message.
3. **fmt** to canonical form (`marv fmt --write`) — never hand-format; there is exactly one form.
4. **verify** pure / verified-subset definitions (`marv verify`); on `failed`, use the
   counterexample to repair, then re-verify. `unsupported` is fine (falls back to runtime checks).
5. **run / build** with an explicit capability grant (`marv run --grant …`, `marv build`).
6. **commit** to freeze reproducible hashes (`marv commit`); already-reviewed hashes need no re-audit.

## Two ways to call it

- **CLI** — `marv fmt|check|run|build|verify|commit` (see `docs/cli.md`). Good for one-shot work.
- **MCP server** (`marv-mcp`) — tool-call access with a persistent snapshot: `marv_open_snapshot`
  then `marv_check` / `marv_signature` / `marv_error_set` / `marv_effects` / `marv_core` /
  `marv_verify` / `marv_apply_fix` / `marv_format` / `marv_commit`. Wiring: `docs/agents.md`.

## Invariants (do not fight these)

- **No ambient authority** — power enters only through capability parameters (`Io`, `Fs`,
  `Net`, `Http`, `Clock`, `Rand`, `Alloc`, `Spawn`); pass a function only what it needs. A
  function with no `Net`/`Http` parameter cannot reach the network or an HTTP request.
- **One canonical form** — run `fmt`, don't argue about style.
- **Local reasoning** — every signature is fully annotated; annotate.
- **Determinism** — same source ⇒ same hashes/diagnostics.
- **Honesty** — don't claim a check/verify passed that you didn't run; the tools report
  `unsupported` rather than guessing, and so should you.

## What parses today

`mod`/`import`, local source module sets, `struct`/`enum`/`fn`/`interface`/`impl` (including
`pure fn`, generics, bounds, and capability interfaces), `let`/`var`, assignment, `if`/`else`,
`match`, loops, early `return`, errors (`!T`, `?`), collection literals, string/bytes/JSON
helpers, capability method calls from source, `unsafe fn` audit metadata, calls/recursion,
field projection, and `requires`/`ensures` contracts. For raw FFI operations, production
listener/resource lifecycles, recursive materialized JSON, or not-yet-supported backend forms,
use a `*.core.json` snapshot or check `docs/roadmap.md` before generating source.