A language for WHAT.
Blueprints for HOW.

The syntax at a glance

===
Billing APIs   #blueprint(api-nestjs-monorepo)
====
+ Billing

=== Billing ===

Subscription
============
** _id: String
*  plan: Plan
*  owner: Customer
*  startDate: Date
-  cancelledAt: Date
~  cancel(): void
~  renew(months): Subscription

Syntax excerpt — Plan and Customer definitions omitted. A runnable model defines every referenced type.

Define. Validate. Inspect. Compile. Extend.

1. 01
   Define

   Describe application concepts and supported behaviors in the modeling language.

2. 02
   Validate

   Check supported structural and semantic rules with compiler diagnostics.

3. 03
   Inspect

   Explore entities, operations, dependencies, and generated artifacts.

4. 04
   Compile

   Transform supported definitions into source code using implementation blueprints.

5. 05
   Extend

   Write conventional code for algorithms and behavior better expressed imperatively.

The pipeline

Six phases. The model load path is shared by every command.

• Discover — find all .modelhike files
• Load — parse into the in-memory model
• Hydrate — post-load refinements and annotation cascade
• Validate — semantic checks with structured diagnostics; never halts
• Render — run the blueprint's templates and scripts
• Persist — write generated files to the output directory

CLI examples

A non-interactive Smart CLI: human-readable by default, --format json for structured output, stdin via --input -, no prompts.

# the model references CustomerProfile, which is never defined
$ printf '===\nAPIs\n====\n+ Billing\n\n=== Billing ===\n\nSubscription\n============\n* _id: String\n* owner: CustomerProfile\n' \
    | .build/debug/modelhike validate --input -

→ W301  Type 'CustomerProfile' referenced by property 'owner' in 'Subscription' not found.
# fix the model, or let `modelhike fix` attempt supported corrections first

$ modelhike dry-run --input model.modelhike --blueprint api-nestjs-monorepo --container APIs

# previews the generated file tree and manifest without writing anything

$ modelhike generate --input model.modelhike --blueprint api-nestjs-monorepo --container APIs --output ./generated

# without --output, files are written to ./modelhike-output
# with --blueprint, also pass a target: --container (here) or --system-view

$ modelhike explain --input model.modelhike

# summarizes what the model means: containers, entities, APIs, relationships

$ modelhike what-depends-on Payment --input model.modelhike

# reverse dependencies across model references —
# supports rename/remove impact analysis

$ modelhike fix --input model.modelhike --codes W301

# attempts supported auto-fixes and returns corrected model text with an audit trail

$ modelhike preflight --input model.modelhike --blueprint api-nestjs-monorepo

# generation-readiness checklist: validation state, module references, blueprint assignment

Exit codes: 0 success · 1 warnings · 2 errors · 3 parse failure · 4 generation failure.

Run it yourself: clone github.com/modelhike/modelhike and swift build. Outputs shown here are transcribed from the reference docs unless labeled recorded.

MCP tools for AI agents

The MCP server runs over stdio — no HTTP, no networking config. Agents in Cursor, Windsurf, or Claude Code call structured JSON tools directly.

"mcpServers": {
  "modelhike": {
    "command": "/path/to/.build/debug/modelhike-mcp",
    "transportType": "stdio"
  }
}

Blueprints

A blueprint is a folder of templates and scripts that compiles a model into a specific stack. Add your own with --blueprints <path>.

Blueprints have different capabilities and surfaces. A model preserves your definitions; it does not make frameworks identical.

The spec became the source of truth. But the AI still has to guess.

Spec-driven development is an important step forward. It places requirements and design decisions before implementation. But a specification interpreted by an AI and a specification understood by a compiler are not the same thing.

Interpretation leaves implementation decisions open. Probabilistic generation may produce different implementations from the same requirements. And someone must verify not only what changed, but whether the implementation still reflects intent.

Specification
  → AI interpretation
  → Source Code

Typed Source Model
  → Compiler + Blueprints
  → Source Code

Fix the source. Not the symptoms.

AI still finds the right change. Once a decision is in a blueprint, nobody reinvents it.

Update spec
  → AI interpretation
  → Generated changes
  → Review and correct

Update supported Source Model
  → Validate
  → Compile
  → Verify

Subscription
============
** _id: String
*  plan: Plan
*  owner: Customer
*  startDate: Date
-  cancelledAt: Date

*  startDate: Date
+  -  pausedAt: Date
-  cancelledAt: Date

$ modelhike validate --input billing.modelhike

$ modelhike generate --input billing.modelhike --blueprint api-nestjs-monorepo --container "Billing APIs"

$ modelhike inspect Subscription --input billing.modelhike

Prompts propose. Compilers enforce their rules.

AI is good at exploration, interpretation, and proposing solutions. A compiler is good at applying rules that have already been defined. ModelHike brings both into one development workflow.

Agents drive the loop: draft → validate → diagnose → fix → explain → approve → generate.

Every MCP call returns structured JSON. Every diagnostic carries a stable code and a source location. The agent drives validation and error-correction; a developer approves the important decisions.

Use intelligence where judgment is needed. Use determinism where the rules are known.

Deterministic means repeatable output from fixed model, blueprint, toolchain, and configuration inputs. It does not make an incorrect specification correct.

From modeling structure to modeling outcomes.

Application types and relationships are a foundation. But business software ultimately exists to produce meaningful outcomes. A payment is authorized. An order is fulfilled. A reservation is cancelled. A refund respects its limits.

ModelHike is evolving toward richer outcome and constraint modeling — business behavior expressed more directly, without the model prescribing every implementation algorithm.

Not simply more code from fewer lines. More application meaning, expressed before implementation.

Roadmap: outcome/constraint modeling, packaged CLI distribution, VS Code extension, plugin system.