umadev

UmaDev: A coding agent that works like a real dev team, commanding the Claude Code / Codex / OpenCode you already use.

English | 简体中文 | 繁體中文

umadev is a coding agent that works like a real dev team. It drives an AI coding CLI you already have — Claude Code, Codex, or OpenCode — as one continuous session, and owns no model of its own: the model your base is connected to is the brain.

What you get is a whole AI development team. Eight specialists — product manager, architect, UI/UX designer, frontend engineer, backend engineer, QA, security, and DevOps — plan, build, review, and sign off the way a real team does, borrowing your already-logged-in base as their shared brain. You describe what you want in plain language, and the team turns it into runnable, shippable, auditable software: it researches, writes the PRD, architecture, and UI/UX, builds the frontend and backend, runs the quality and governance checks, and hands back the code plus a delivery proof. It sizes itself to the task — a small edit stays a small edit; a full project convenes the full roster.

A ninth seat, the coordinator (the team's technical lead), routes the request, owns a visible plan, schedules the team, enforces the gates, and leaves the audit trail. It doesn't write code; the base — the AI coding CLI — is the engineer that does that. The roles coordinate through shared artifact files and structured verdicts, never by chatting to each other.

It's a single Rust binary. npm is just the delivery shell.

Table of Contents

• Install
• Quickstart
• Project Origin
• What Problem It Solves
• Features
• How It Works
• The Team
• Why You Can Trust the Output
• Runtime Modes
• The Full Delivery Flow
• Quality Gate
• Governance
• Knowledge Base
• Deliverables
• Commands
• Configuration
• Rust Architecture
• Development
• License

Install

npm install -g umadev

On Linux, don't reach for sudo. The default npm prefix (/usr/local) is root-owned, so npm i -g there fails with EACCES — and sudo npm i -g "fixes" it by writing a root-owned tree into the npm prefix, which then breaks every later non-root npm command on that prefix (npm update -g, npm i -g <anything>) with EACCES. npm aborts the whole transaction, so your other global packages — including your base CLI (@anthropic-ai/claude-code, @openai/codex) — can no longer be updated either. Use a prefix you own instead:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
npm install -g umadev

Or skip the global install entirely — no prefix, no sudo, nothing on PATH:

npx umadev                 # run it straight from the registry
npm i umadev && npx umadev # or as a project-local dependency

(npm i umadev without -g installs fine, but npm deliberately does not put a local command on PATH — bare umadev will say "command not found". That's npm, not a broken install: run it as npx umadev.)

Already hit the sudo trap? umadev doctor detects a root-owned install or npm cache and prints the exact repair (sudo chown -R $(whoami) ~/.npm, then reinstall under a user-owned prefix).

The npm package is a distribution shim. The actual program is a Rust binary. Prebuilt binaries ship for macOS (Apple Silicon and Intel), Linux (x86_64 and ARM64, glibc ≥ 2.31 — musl/Alpine needs a source build), and Windows (x86_64).

The binary and the curated knowledge corpus install from npm and work fully offline. The optional local embedding model (multilingual-e5-small, f16, ~224 MB) is not bundled in the npm package — it is fetched on first run to ~/.umadev/embed-model (a one-time download), then powers offline vector search locally with no API key and no runtime network. If that first-run download is unavailable (offline install, restricted network), umadev still works: retrieval falls back to BM25-only until the model is present, and it self-heals — a later run re-downloads it (a corrupt cache is re-fetched, not trusted).

Build from source:

git clone https://github.com/umacloud/umadev.git
cd umadev && cargo build --release --features vector-local
./target/release/umadev --version

Building from source? The embedding model is not in the repo (it's too large for git, ~224 MB). A plain cargo build --release gives a BM25-only binary; the local vector channel needs the --features vector-local flag and the model on disk. The prebuilt binaries and npm i bundle both automatically — for a source build, download multilingual-e5-small into ~/.umadev/embed-model/ once:

mkdir -p ~/.umadev/embed-model && cd ~/.umadev/embed-model
for f in config.json tokenizer.json model.safetensors; do
  curl -fsSL "https://huggingface.co/intfloat/multilingual-e5-small/resolve/main/$f" -o "$f"
done

umadev auto-discovers it there (or point UMADEV_EMBED_MODEL_DIR at any directory with those three files). Without the model, umadev still works — retrieval just falls back to BM25-only.

You also need one AI coding CLI installed and logged in — that's the brain umadev drives:

umadev injects nothing into the base. Whatever your base is configured with — an official login or your own third-party / local-model routing — is exactly what runs.

Quickstart

umadev                       # launch the chat UI; first run lets you pick a base

Tell it what you want built:

> add CSV export to the reports page
> build me a todo app with a Postgres backend
> /goal ship a working SaaS landing page       # keep working until the goal is met

Or run a build non-interactively:

umadev run "add CSV export to the reports page" --backend claude-code

umadev sizes the work to the request — you don't pick a mode. A build typed in chat earns the same planning, team review, governance, and delivery proof as a /run — there is no separate chat path and build path. All builds run on an isolated umadev/<slug> branch; your working branch is never touched, and umadev never merges or pushes on its own.

A full worked example

Suppose you run:

umadev init
umadev

Then type:

Build a course-booking mini app. Users can browse courses, pick a time, book,
cancel. Admins can manage courses and bookings.

umadev will:

1. Route the request. The base's own model judges this: a full build, not a quick edit. You see an intent card — "full build, entering the delivery flow" — before any code is written.
2. Clarify. Fill in sensible defaults for target platform, payment scope, and admin complexity. Auto mode self-resolves; manual mode lets you confirm each.
3. Research. When the base has web access, search competing booking apps — features, pricing, design trends, real user reviews — and merge that with built-in knowledge about booking systems, admin CRUD, permissions, and form validation. Everything lands in output/<slug>-research.md.
4. Draft three core documents. PRD (roles, scope, EARS acceptance criteria), architecture (data model, APIs, auth, deployment), UI/UX (design direction, tokens, typography, component states, icon library). Pause for your review.
5. Build an execution plan. A dependency plan (plan.json) rendered as a live checklist. Each task links back to its FR id.
6. Implement the frontend. The coordinator schedules each task, the base writes the code, each file is governance-checked as it lands.
7. Pause for preview. You see the running app before backend work starts.
8. Implement the backend and integration.
9. Run the full quality gate. Build, test, lint, contract check, runtime probe, governance scan.
10. Produce the delivery pack. Scorecard, proof pack, compliance mapping — on disk and ready to hand to a teammate, client, or reviewer.

You end up with real files on disk — the research note, the three docs, source, a quality report, and a proof pack.

Project Origin

umadev evolved from the original shangyankeji/super-dev project.

Early super-dev was closer to an AI coding governance tool. It focused on what AI-generated code must not contain: emoji icons, hardcoded colors, unsafe patterns.

umadev has grown that into a coding agent that works like a real dev team:

• From single-point governance to whole-pipeline governance. It no longer only checks code; every phase from requirement to delivery is brought under the process and its gates.
• From loose scripts to a spec-driven system. The source of truth is UMADEV_HOST_SPEC_V1, 32 clauses, ~112 governance rules.
• Rewritten in Rust. One binary, fast startup, low dependency surface, cross-platform distribution.
• From blocking bad output to delivering like a team. Claude Code / Codex / OpenCode are the brai