maapp turns an app's screens, flows, state, navigation and side-effects into a typed knowledge graph an AI coding agent queries instead of reading source or prose.
Early release. MIT licensed.
Install (no sudo, lands in ~/.local/bin):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yangsi7/maapp/releases/latest/download/maapp-installer.sh | shValidate a graph. The repo ships 8 example app graphs under examples/;
all of them validate clean:
$ maapp validate examples/checkout.json
CLEAN — examples/checkout.json: 0 errors, 0 warnings. (65 nodes, 88 edges)Ask what breaks before you touch a store:
$ maapp query blast-radius store:CheckoutStore examples/checkout.json
BLAST-RADIUS store:CheckoutStore
DEPENDENTS (depend ON it; break if it changes) [10]:
act:address/SaveAndContinue
act:card/SaveCard
act:pay/SelectMethod
act:review/PlaceOrder
act:shipping/Continue
assert:pay/CardSelected
assert:pay/WalletSelected
assert:shipping/AddressPresent
comp:checkout/AddressCard
screen:checkout/Payment
DEPENDENCIES (it depends on) [0]:Render the backend pull spine, which surface pulls which store, down to the backend-op floor:
$ maapp render spine examples/checkout.json
BACKEND PULL SPINE — STALACTITE VIEW (downward data-pull only)
================================================================================
...
PER-COLUMN PULL SUMMARY
--------------------------------------------------------------------------------
surface depth fanin floor ticks
LineItemList 1 1 . #
OrderSummary 1 1 . #
AddressCard 1 1 . #
AddressForm 1 0 .
Complete 3 1 YES #
Payment 1 1 . #
STALACTITE GRID (shared substrate rows; | = spine, o = tick,
# = stage/op tick)
--------------------------------------------------------------------------------
|LI OS AC AF CO PA
+------------------
SURFACE |[] [] [] [] [] []
bind[0] | o o o o o o
OrderStore | o
op:PlaceOrder | #
+================== <- floor (BackendOps)
...Add --json to validate or any query for byte-stable machine-readable output. Bare
maapp prints the full help, and every subcommand's --help ends with copy-runnable
examples.
- Typed, validated, not remembered. Screens, flows, stores, navigation, guards and
side-effects are typed nodes and edges under a versioned schema.
maapp validateenforces the contract: on the eval battery it catches 25 of 25 injected defect classes with zero false positives. - Scoped structural queries. Blast-radius before a refactor, trace from a UI trigger to the backend, N-hop neighborhoods, nav topology, orphans. An agent pulls the slice it needs instead of reading whole files, or the whole graph.
- A living loop with drift detection.
maapp check-driftmaps the graph's source anchors onto the commits since the lastmaapp stamp, so a stale graph tells on itself instead of silently rotting. A CI gate and a Claude Code hook back it up. - Agent harness wired in one command.
maapp initcreates.maapp/, installs the drift-nudge hook, and adds a routing section toCLAUDE.mdorAGENTS.md. Idempotent, previewable with--dry-run. - Profiles are data, never plugins. Stack- or category-specific vocabulary and lint rules ship as declarative schema overlays; there is no code-execution surface.
- Deterministic
--json. Byte-stable output with no timestamps, floats, randomness or absolute paths in any artifact; safe to snapshot, diff and gate in CI.
When to reach for maapp, each with a command that runs against the shipped examples/:
- Blast radius before a refactor. See every node that depends on a store or component
before you touch it, so a rename or deletion never breaks something silently.
maapp query blast-radius store:CheckoutStore examples/checkout.json - Trace a UI bug to its backend operation. Follow a screen through its triggers,
actions and stores down to the backend op it invokes, without opening a source file.
maapp query trace screen:checkout/Review examples/checkout.json - Onboard an agent to an unfamiliar codebase. Hand a cold agent the whole-app
blueprint hub as its first read: screens, flows and stores at a glance, not grepped source.
maapp render hub examples/dashboard.json - Drift detection at review time. After a feature lands, check the graph's anchors
against the repo so a stale map tells on itself before anyone trusts it.
maapp check-drift examples/checkout.json --repo . --since HEAD - Spec-first blueprint an agent builds against. Turn a PRD into a validated graph
first, then read it back as the screen-by-screen plan the agent implements to.
maapp render storyboard examples/wizard.json
Generated graphs hold 93% of the human cross-author agreement ceiling on held-out apps, backed by a validator that catches 25 of 25 injected defect classes with zero false positives and an engine that is byte-identical to its proven prototype; see docs/BENCHMARKS.md for every number, including the negative real-codebase pilot we published anyway.
| Result | Value | n | Details |
|---|---|---|---|
| Held-out spec-to-graph parity | 0.9306 (bar 0.90, PASS; all graphs validate 0/0) | 3 held-out apps, 6 seeded runs | BENCHMARKS |
| Validator mutation recall / FP | 25/25 recall, 0/7 false positives | 25 injectors, 7 valid graphs | BENCHMARKS |
| Deterministic ground-truth battery | 21/21 | 21 tasks | BENCHMARKS |
| Rust vs prototype-oracle differential | 0 divergences | 19 committed CI differential snapshots | BENCHMARKS |
| Real-codebase ingest pilot | K1 PASS, K2 FAIL (baseline at ceiling; graph won only the 2 hard tasks, +20/+25 pp) | 48 runs (12 tasks x 2 arms x 2 seeds) | BENCHMARKS |
Every row links to its protocol, sample size, reproduce command and limitations. Negative results are published with the same prominence as positive ones.
1. Install the CLI.
Use the Quickstart one-liner above or any rung of the install ladder below.
No sudo: installs to ~/.local/bin (override with MAAPP_INSTALL). Verify with
maapp --version.
2. Wire your agent.
maapp init --dry-run # preview, touches nothing
maapp init # idempotent; re-running is all skips
Creates .maapp/, installs the drift-nudge hook and merges it into
.claude/settings.json when .claude/ exists (the original is backed up to
.claude/settings.json.bak), and adds a marker-fenced routing section to CLAUDE.md
(else AGENTS.md, created if needed). Claude Code users add the /maapp skill with
/plugin marketplace add yangsi7/maapp then /plugin install maapp@maapp. Cursor,
OpenAI Codex (via the AGENTS.md convention), and every other harness: see
docs/INTEGRATIONS.md.
3. Init your graph.
Author or ingest a graph with the /maapp skill into .maapp/graph.json, then:
maapp validate .maapp/graph.json
maapp stamp .maapp/graph.json --repo .Commit the stamped graph. The living loop keeps it honest from there: validate, check-drift, stamp (green means 0 stale candidates and 0 rotted anchors).
All paths install to ~/.local/bin; override with MAAPP_INSTALL. No sudo, ever.
1. Shell one-liner (macOS / Linux):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yangsi7/maapp/releases/latest/download/maapp-installer.sh | shWindows:
powershell -ExecutionPolicy Bypass -c "irm https://github.com/yangsi7/maapp/releases/latest/download/maapp-installer.ps1 | iex"Prefer an auditable script? This one checksum-verifies the release artifact and falls back to a source build:
curl -fsSL https://github.com/ghraw/yangsi7/maapp/main/install.sh | sh2. cargo binstall (fetches the prebuilt release binary instead of compiling):
cargo install cargo-binstall # one-time, if you don't already have it
cargo binstall maappRelease assets are named maapp-<target-triple>.tar.xz, matching binstall's defaults,
so no extra metadata is needed.
3. cargo install (compiles from the published crate):
cargo install maapp4. Build from source (needs Rust):
git clone https://github.com/yangsi7/maapp && cd maapp && ./install.shRuns cargo build --release --locked under the hood.
Prebuilt binaries cover Apple Silicon and Intel macOS, x86_64 Linux (gnu), and x86_64
Windows. Releases are built by dist (cargo-dist) v0.32.0 on tag push; every artifact
ships with a .sha256 and a unified sha256.sum.
- docs/BENCHMARKS.md: every measured number, with protocol, sample size, reproduce command and limitations per result
- docs/INTEGRATIONS.md: wiring maapp into Claude Code, Cursor, Codex / AGENTS.md agents, and any other harness
- docs/ADOPTION.md: cutting over from bespoke graph tooling, cold-starting a graph on an existing app, and the drift-baseline ratchet
- docs/EDGE-VOCABULARY.md: every edge type, its required from/to node kinds and attrs, one example line each
- CONTRIBUTING.md: dev setup and the 5-command verification gate (fmt, clippy -D warnings, nextest + doc tests, cargo deny, wasm32 build)
- examples/: 8 example app graphs (chat, checkout, dashboard, maps, media, onboarding-variant, settings-account, wizard); all validate clean
Run maapp schema for the canonical, machine-readable vocabulary: every node kind, edge
type, and required attribute, generated from the engine's own tables (never hand-maintained,
so it can't drift from what maapp validate enforces).
Node kinds, by layer, with the slug prefix convention the shipped examples/ use (a
convention, not a schema rule; run maapp schema for the authoritative kind list):
| Layer | Kinds | Slug prefix |
|---|---|---|
| surface | Screen, Component, NavContainer | screen:, comp:, nav: |
| logic | Trigger, Assertion, ViewState, EffectAction / MutationAction / NavAction / QueryAction / ViewStateAction | trig:, assert:, vs:, act: |
| policy | Policy | policy: |
| substrate | StateStore, BackendOp, DataSource, PipelineStage, SideEffect | store:, op:, ds:, stage:, fx: |
Edge attrs (mode, awaits, event, present, artifact, and friends) are flat
top-level keys on the edge object, not nested; see
docs/EDGE-VOCABULARY.md for the full set per edge type.
MIT; see LICENSE. Copyright (c) 2026 Simon Yang.