umadev

UmaDev: A coding agent that works like a real dev team, commanding one of five AI coding CLIs you already use.

English | 简体中文 | 繁體中文

umadev is a coding agent that works like a real dev team. It drives one of five first-class AI coding CLIs you already have — Claude Code, Codex, OpenCode, Grok Build, or Kimi Code — and owns no model endpoint of its own: the model your selected base is connected to is the brain.

What you get is role-based team orchestration over that borrowed brain. For work whose depth warrants it, bounded sessions take product, architecture, UI/UX, frontend, backend, QA, security, and DevOps assignments; a small edit stays a small edit. These roles are not independent people and their verdicts are advisory. UmaDev owns the plan and deterministic acceptance floor, produces depth-appropriate artifacts/evidence, and reports failed or incomplete work honestly rather than promising that every request becomes shippable software.

A ninth seat, the coordinator, routes the request, owns a visible plan for deliberate work, schedules the selected roles, evaluates gates, and leaves the audit trail. It doesn't generate code; the base CLI does. Roles exchange bounded blackboard artifacts and structured verdicts rather than free-form cross-talk.

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

Or skip npm entirely — the native installer needs no Node, no npm, and never sudo. It downloads the official release binary for your platform, verifies its published SHA-256, and installs to a directory you own (~/.local/bin, or %LOCALAPPDATA%\Programs\umadev on Windows):

# macOS / Linux
curl -fsSL https://umadev.goder.ai/install.sh | bash

# Windows (PowerShell)
irm https://umadev.goder.ai/install.ps1 | iex

(Pin a version by setting UMADEV_VERSION / $env:UMADEV_VERSION to the release you need; override the target directory with UMADEV_INSTALL_DIR. Every release binary embeds and stages the curated knowledge corpus. The npm launcher additionally fetches the optional embedding model on demand; a native install starts with BM25 retrieval and can use a manually provisioned local model through UMADEV_EMBED_MODEL_DIR. umadev doctor reports the active retrieval path and anything missing.)

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 or musl/Alpine), and Windows x86_64; Windows on ARM uses that x64 build through the OS compatibility layer.

The Rust binary and curated corpus need no cloud knowledge service. Real coding still requires an installed, authenticated base CLI. The optional local embedding model (multilingual-e5-small, f16, ~224 MB) is not inside the npm tarball: the npm launcher fetches the version-matched, checksummed release asset on the first command that needs retrieval and stores it in ~/.umadev/embed-model. Later local inference needs no API key or network. If the fetch is unavailable, retrieval continues as BM25-only and a later eligible launch retries; a corrupt cache is rejected and re-fetched.

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 repository. A plain cargo build --release supports BM25 and the explicitly opted-in remote vector backend, but does not compile the local candle backend. Local vectors require --features vector-local and a compatible config.json, tokenizer.json, and model.safetensors on disk. Point UMADEV_EMBED_MODEL_DIR at that directory, or place it at ~/.umadev/embed-model. The npm launcher provisions version-matched, verified release assets automatically; a source-built binary does not download them. Without a usable vector backend, engine = "hybrid" safely executes as BM25-only.

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

The curl | bash/sh entries are the Unix install hints understood by the current driver. On Windows, use each vendor's official Windows installation instructions; do not paste those Unix commands into PowerShell.

UmaDev itself needs no additional model API key. You still install and authenticate the selected base, and that base keeps ownership of its account, subscription, credentials, model, and any third-party/local-model routing. UmaDev does not run login flows or open an authentication browser for you. It sends the task and governance context, but never stores or silently replaces the base's credentials or model endpoint. umadev doctor confirms authentication where a reliable probe exists; for Grok Build, only a successfully opened real session proves readiness — “installed” does not mean “logged in.”

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 have to select an intent class. A request classified as Build enters the same owned Director contract whether it came from chat or umadev run; the plan, simulated role reviews, checks, and delivery artifacts remain proportional to its depth. On a clean Git worktree UmaDev can create a derived umadev/<slug> isolation branch. A non-Git or already-dirty worktree reports why isolation was skipped and preserves pre-existing changes. 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, dep