USM (Universal System Map) is a structured source of truth for agentic systems. A single .usm/ directory of YAML files describes your whole system and generates markdown docs, Mermaid diagrams, OpenAPI specs, AGENTS.md, Vitest test specs, ArchiMate, and TOGAF deliverables.

How does USM save tokens?

USM delivers structured, high-signal context via MCP tools instead of feeding entire codebases or Markdown vaults to AI agents. This uses approximately 10-20x fewer tokens while reducing hallucinations.

What tools does USM work with?

USM works with any MCP-compatible AI coding tool including Cursor, Claude Code, Claude Desktop, Continue.dev, Codex, and GitHub Copilot.

Yes, USM is free and open source under the MIT license. Self-hosting — your .usm files stay in your repo.

v0.6.0 — Free & open source

The source of truth for human + AI software development

.USM (Universal System Map) is a schema driven source of truth for agentic software development, that reduces token burn, persists system knowledge across coding sessions, and automatically generates, documentation and design artefacts in a spec first development cycle

10-20x fewer tokens Cross session memory Hot loading specs/docs

Install Now Try in 60 seconds

CLI

terminal — usm

Step 1 — Scan & Map

13 languages, 30+ frameworks — and extensible

Ships with built-in detectors for 13 languages and 30+ frameworks. Add your own via .usm/detectors/*.yaml — no fork required.

Next.jsExpressHonoNestJS

Route detection · TypeScript

app.get('/users', (req, res) => { ... })

Works with your editor

Supports 36 editors or any MCP compatible client

Agentic IDE

editor — auth-app

Explorer

▸.usm

·system.usm

▸features

▸auth

·login.usm+

▸cli

·scan.usm

▸src

▸auth

·login.ts+

·index.ts

Live docs

localhost:5173/features/auth/login

USM

Getting Started

Home

Getting Started

Agent Setup

Features

auth/login

cli/scan

cli/generate

mcp/write

Claude Code

Claude Desktop

Cursor

Windsurf

VS Code

JetBrains

opencode

Codex

Zed

Continue

Browse all editor setup guides

Sound familiar?

You spend the first 10 minutes of every agent session re-explaining your system

You iterate in chat, the agent gets it wrong, and the discussion is lost forever

Your docs went stale 3 sprints ago and nobody has time to update them

You can't remember what the agent was supposed to build vs what it actually built

You're burning thousands of tokens feeding your entire codebase for context

10,000+

tokens wasted per agent session re-establishing context that USM provides in <500

How it works

Three ways to use USM

Onboard an existing codebase, run the spec-first dev loop, or enrich specs with LLM.

Onboard an existing codebase

Init

Analyze repo, generate usmconfig.json

usm init

Scan

Detect services, routes, data models across 12 languages

usm scan

Enrich

Fill TODO placeholders with LLM (optional)

usm enrich

Generate

Produce docs, OpenAPI, Mermaid, test specs

usm generate

The spec-first dev loop

Discuss

Human and agent talk about the feature

Spec

Agent drafts a .usm feature spec via MCP

Review

Human reviews the generated markdown

Build

Agent implements from the approved spec

Documented

The spec IS the docs — always in sync

LLM enrichment

Scanned .usm files contain TODO: describeplaceholders. usm enrich calls an LLM to fill them in with source code context — preserving all human-written content.

PROVIDERS

OpenAI, Anthropic, Ollama, LiteLLM

MODELS

Any OpenAI-compatible model

PRESERVES

Human-written fields

CONFIGURABLE

Fields, model, temperature

usm enrich --model gpt-4o --dry-run

Benefits

What you get

Less time re-explaining. Fewer review cycles. Docs that match the code.

Ship features faster

Less back-and-forth with agents. The spec is the contract — agents build from it, humans approve before code is written.

Higher code quality

Contracts and tests defined upfront. Agents know what 'done' means before they start coding.

Always-up-to-date docs

No more stale documentation. The spec IS the docs — written first, never an afterthought.

10-20x fewer tokens

Stop feeding entire Obsidian vaults or codebases. USM delivers structured, high-signal context via MCP that uses ~10-20x fewer tokens while reducing hallucinations.

Token efficiency

Stop wasting tokens

USM delivers structured, high-signal context via MCP. No more feeding entire vaults or codebases.

Method	Tokens/Session	Quality	Maintenance
Raw Markdown / Obsidian	Very High	Noisy	Manual
Full Codebase	Extreme	Overwhelming	None
USM + MCP	Low	High-signal	Automatic

Comparison

Before USM vs With USM

Without USM

— Describe feature in chat, agent codes, discussion lost
— Re-explain system context every session
— Docs drift from code within days
— No review before agent builds
— Agent hallucinates unknown patterns
— Burn thousands of tokens on full codebase

With USM

+ Agent drafts spec, human reviews, agent builds
+ Agent reads system map via MCP before starting
+ Spec IS the docs — written first, never stale
+ Review markdown before any code is written
+ Agent follows established patterns from .usm
+ Structured MCP context — 10-20x fewer tokens

Outputs

One source, many outputs

A single .usm/ directory generates all of these.

Markdown docs

Review-quality specs with flows, contracts, and tests

Mermaid diagrams

Architecture, sequence, ER, and dependency graphs

OpenAPI 3.1

API specs from feature routes

AGENTS.md

AI agent context with system structure

Vitest specs

Test files from feature tests[] and flows[]

ArchiMate / TOGAF

Enterprise architecture deliverables

Both documentation sites below are generated from the same .usm/ directory — different audiences, zero separate maintenance:

Help Docs — docs.usm.dev Technical Docs — dev-docs.usm.dev

Quick start

See it in action

Install in 60 seconds. Scan your codebase. Generate docs.

npm install -g @smithgray/usm

usm init

usm scan

usm enrich --dry-run

usm generate

usm docs serve

usm mcp serve

Try it in 60 seconds

Use cases

Who is it for?

If you use AI agents to write code, USM gives you a shared artifact between human intent and agent output.

Solo devs using Cursor or Claude Code

Stop re-explaining your system to every new agent session. The .usm map gives instant context.

Teams adopting AI coding

Give every agent the same system context. Specs become the shared contract between human reviews and agent output.

Microservices & monorepos

Map services, dependencies, and features across the entire system. Auto-generate architecture diagrams.

Enterprise & compliance

Generate ArchiMate, TOGAF, and OpenAPI from the same source. Audit-ready architecture artifacts.

Start building with a spec

Free, open source, MIT licensed. Works with opencode, Cursor, Claude Code, Codex, and GitHub Copilot. Self-hosting — your .usm files stay in your repo.

Get Started Free Star on GitHub