Alpha v0.1.0 — Free & open source

The shared focused brain for
human + AI development

Write specs first. Agents build from them. Docs stay perfectly in sync — using far fewer tokens than bloated Markdown vaults.

Spec-first workflow 12 MCP tools 10-20x fewer tokens LLM enrichment
Install Now Try in 60 seconds
terminal — usm
$ usm draft_feature \
--summary 'Login with email' \
--flows '[{"id":"login","steps":[...]}]'
 
✓ validation_status: valid
✓ yaml: 247 bytes generated
✓ markdown: 1.2kb preview ready
 
→ Show human the markdown for review...

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

01
Init

Analyze repo, generate usmconfig.json

usm init
02
Scan

Detect services, routes, data models across 12 languages

usm scan
03
Enrich

Fill TODO placeholders with LLM (optional)

usm enrich
04
Generate

Produce docs, OpenAPI, Mermaid, test specs

usm generate

The spec-first dev loop

01
Discuss

Human and agent talk about the feature

02
Spec

Agent drafts a .usm feature spec via MCP

03
Review

Human reviews the generated markdown

04
Build

Agent implements from the approved spec

05
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.

MethodTokens/SessionQualityMaintenance
Raw Markdown / ObsidianVery HighNoisyManual
Full CodebaseExtremeOverwhelmingNone
USM + MCPLowHigh-signalAutomatic

Language support

Scans 12 languages, 30+ frameworks

Click a language to see supported frameworks and route detection patterns.

Next.jsExpressHonoNestJS
Route detection · TypeScript
app.get('/users', (req, res) => { ... })

Works seamlessly with

Cursor
Claude Code
Claude Desktop
GitHub Copilot
Codex
Grok Code
OpenCode
Windsurf
Continue.dev
Zed

Any MCP-compatible AI coding tool

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

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 Cursor, Claude Code, and Codex. Self-hosting — your .usm files stay in your repo.

Get Started FreeStar on GitHub