An open standard for describing an app's information architecture — screens, navigation, flows, UI elements, states, and data dependencies — in one YAML (or JSON) document that is equally readable by humans and operable by agents.
maias: "0.3"
app:
name: Todo List
navigation:
primary:
screens: [home, settings]
flows:
- name: main
entry_screen: home
screens: [home, task_detail, task_new]
screens:
- id: home
title: My Tasks
type: list
path: /tasks
description: All tasks, newest first.
elements:
- label: Buy milk
type: list_item
target: task_detail
Why: a common language for human–agent collaboration on app development. An agent can build the described app from the document (implementation guide), create and edit documents as safe machine operations (CLI, MCP), and a human can read and review the same file.
What's in this repo
| |
|---|
| The spec | docs/spec/ — 11 chapters · llms.txt (one-context-window agent reference) · schema/maias.schema.json |
@maias/core | packages/core — parse → typed model → serialise with round-trip fidelity (comments survive edits), graph utilities, safe edits (cascading renames, element batches), canonical formatter, Hermes-safe validation |
maias CLI | packages/cli — maias validate (schema + semantic lint, --json), maias fmt, maias rename |
| MCP server | packages/mcp — validate / query / edit / edit_elements tools for any MCP-capable agent |
| MAIAS Browser | MAIAS_browser — Expo app that opens any MAIAS document at runtime and renders it: dynamic tab bar, pluggable design-system adapters (wireframe · shadcn-style · blueprint), in-app validation errors |
| Examples | examples/ — calculator · todo_list · social_network · ecommerce — collectively covering every core element and screen type |
| Claude skills | .claude/skills/ — maias-create, maias-edit, maias-review, maias-wireframe · installable anywhere as the maias plugin |
Quick start
Requires Node.js 20.19.4+ / 22.13+ / 24.3+ (CI runs 22). No clone or install needed — the packages are on npm:
npx -y @maias/cli validate my-app.maias.yaml
npx -y @maias/cli fmt my-app.maias.yaml --write
npx -y @maias/cli rename my-app.maias.yaml old_screen new_screen
Prefer a plain maias command? npm i -g @maias/cli.
In Claude Code, one install delivers the three skills plus the MCP server:
/plugin marketplace add MAIAS-project/maias-plugin
/plugin install maias@maias
In any MCP client, add the server with claude mcp add maias -- npx -y @maias/mcp (or the JSON equivalent — see packages/mcp); it is also listed in the official MCP registry as io.github.MAIAS-project/maias.
The MAIAS Browser (render any document as a working app, web/iOS/Android) runs from a clone:
git clone https://github.com/MAIAS-project/maias.git && cd maias
npm install && npm run build
npx maias validate examples/todo_list/maias.yaml
npm run web --workspace maias-browser
Working from a clone, npm run link-tools symlinks the workspace CLI (and the
maias-mcp server) onto your PATH, tracking your local build; undo with
npm rm -g @maias/cli @maias/mcp.
To author a document, start from docs/spec/llms.txt — it is sufficient on its own — or, in Claude Code, just ask: "create an IA for a recipe app" (the maias-create skill takes it from there).
Project documentation
Project architecture: docs/ARCHITECTURE.md · the browser as built: MAIAS_browser/ARCHITECTURE.md · local agent setup (MCP, offline validation): docs/ARCHITECTURE_LOCAL_SETUP.md · building an app from a document: docs/implementation-guide.md · design-system adapters: docs/adapters.md.
Status
Pre-release. MAIAS is pre-1.0: the format and tooling may change in breaking ways between 0.x versions. Spec v0.3 (0.2 + the capabilities/deep_links renames and the elements-first link rule); all six project deliverables implemented (spec + schema, validator/linter, browser, examples, skills, agent-interop toolkit). Tests: npx vitest run (core round-trip/lint/fmt, CLI, MCP).