nomArmy

Name: nomArmy
Author: rayson-tech

Local

nomarmy.devDeveloper Tools4Updated 1w ago

Repository Visit website

About nomArmy

nomArmy coordinates sandboxed coding workers for coding assistants and independently verifies their changes before committing them. Its checks include fresh-sandbox test runs, a test-revert check, and secret scanning.

Key features

01Delegate coding tasks to sandboxed workers
02Verify diffs and rerun tests in a fresh sandbox
03Revert changes to check that tests detect them
04Scan for secrets and flag test workarounds
05Commit verified work on a separate branch
06Run verification without a worker

Use cases

01Delegate a bug fix with acceptance criteria
02Check a branch's tests without starting a worker
03Verify feature work before reviewing and merging
04Flag secrets or weakened tests in worker changes

MCP support

The README lists an MCP server as part of the Reason plugin, but does not state that nomArmy exposes or uses MCP.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "rayson-tech-nomarmy": {
      "command": "npx",
      "args": [
        "-y",
        "nomarmy"
      ]
    }
  }
}

Run commandnpx -y nomarmy

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npmnomarmy0.1.0-beta.14stdio

Tools

Saved tool list · updated 1w ago

Parameter	Type	Required	Description
mode	enum	No	verify: run a required verification profile with no worker and no model tokens; base_ref selects the branch or commit (default current HEAD), task is a short record label, agent/model are unused and army_role is only a label. implement: edit in an isolated worktree, coordinator commits on a valid report. scout: read-only research; every finding must cite [path:start-end] and nomArmy attaches the cited lines after verifying them against the base commit. decompose: read-only; proposes 2+ independent, evidence-grounded subtasks for a broad objective instead of doing everything in one worker turn. Never auto-dispatched -- the proposal is reviewed like a scout's findings, and the coordinator makes its own separate dispatch call with whatever subtasks it chooses to use.scout \| implement \| decompose \| verify
task	string	Yes	implement: the OBJECTIVE the worker must achieve, not the edit it should make. scout: the QUESTION to answer from the repository. decompose: the broad OBJECTIVE to propose a split for.
agent	string	No	Run on this agent from the operator's agents.yml, by name (e.g. "codex", "grok", "local"): the local model, a metered api key, or one person's subscription. Omit agent and army_role to use the local model. Refuses an unknown name, never falls back. Mutually exclusive with army_role. A subscription agent also requires on_behalf_of.
model	string	No	The model to run on the job's agent (an api or subscription agent), e.g. "gpt-6-sol". Overrides the role's model and the agent's default. Required when the role's model is "auto" or the agent has no default. The `army` tool lists each agent's models. Refused on the local agent, whose model `nomarmy model` sets.
report	enum	No	How much the worker may report back, capped by its agent's tier: brief (today's local-sized report), standard (the default), full (the frontier ceiling: about 2k tokens for implement, 4k for a scout). An api or subscription scout defaults to full because its findings are the point; other jobs default to standard. The report lands in your own context and is re-read every later turn. No effect on the local model, whose caps are calibrated.brief \| standard \| full
run_id	string	No	The /feature run this job belongs to (from run_start). Admission then enforces the run's limits (jobs, api spend, hours) and refuses an agent the run has paused after a vendor usage-limit error; the finished job is recorded into the run.
stakes	enum	No	implement: how much a mistake would cost, separate from how hard the work is. high for anything touching security or access control, personal or tenant data, data loss, money, or changes that can't be undone: a verification profile is then required, the revert check can't be turned off, and the job always comes back needing review until an independent review (a scout on another vendor with reviews: <job id>, or a judge on another vendor) has looked at it. A one-line auth change is simple and high-stakes.normal \| high
reviews	string	No	scout: the job id this scout independently reviews, so the review is recorded against that job (nomarmy stats shows high-stakes jobs with and without one). Use a different vendor than the job's worker.
base_ref	string	No
criteria	array	No	implement: contract IDs from acceptance/*.yml served by this job.
evidence	string	No	implement only: facts YOU already resolved (e.g. via repo_evidence) that the worker should trust and not re-derive -- exact signatures, call sites, line ranges, existing behavior. Cuts exploration that would otherwise burn the worker's own context budget on something you already know. Not a substitute for a clear objective and acceptance criteria.
refactor	boolean	No	implement: declares a behavior-preserving change (moving or restructuring code). nomArmy then requires a passing verification profile and refuses to commit if any test file was added, changed or deleted: the existing tests passing unchanged is the evidence nothing changed. The revert check is skipped, since reverting a refactor restores working code and always passes. A job that changes behavior has to change tests, so it can't pass as a refactor.
army_role	string	No	Dispatch by army role (e.g. "sr-dev", "security-analyst"): nomArmy runs it on the agent this repo assigns to that role and puts the role's description at the top of the brief. Call the `army` tool first to see this repo's roles. Mutually exclusive with agent. Add on_behalf_of in case the role's agent is a subscription; it's ignored otherwise.
reasoning	enum	No	Thinking level passed to the worker model: off, minimal, low, medium, high, xhigh, adaptive, max or ultra (the higher ones only where the vendor offers them, e.g. xhigh on Codex models; a level the model lacks falls back once to its nearest supported level). Higher levels spend a subscription's usage limits faster. On the local model it takes effect when that model supports thinking (NOMARMY_MODEL_THINKING); on an api or subscription agent it applies per that agent's own `thinking` setting (false = off, a fixed level = always that level). Default is medium, not high, on real measured evidence: on an identical ticket, gpt-oss-20b at high took 318s with 21 tool calls and 4 failures, and at medium took 62s with 9 calls and 0 failures -- high did not produce a better answer, it thrashed. A separate open-ended task made Qwen3.6-27B time out completely at high (630s, zero output) and succeed at medium. Do not raise this to high by default reasoning that more thinking should help -- it has only ever hurt or timed out in testing so far. Reach for high only after a task has already failed once at medium and the failure looks like an under-thinking problem specifically (wrong root cause, not a formatting or scope issue).off \| minimal \| low \| medium \| high \| xhigh \| adaptive \| max \| ultra
worker_id	string	No
acceptance	array	No	implement: acceptance criteria the worker must satisfy. scout: points a complete answer must cover. decompose: constraints a good split must respect.
on_behalf_of	string	No	Required when the job's agent is a subscription: must exactly match that agent's owner in agents.yml, or nomArmy refuses the job. A self-reported attestation, not an independently verified identity check -- nomArmy has no caller-identity boundary today, so what this guarantees is explicit, auditable intent and hard refusal on mismatch or omission, not cryptographic proof of who issued the call. Ignored for a local or api agent.
verification	string	No	Verification profile NAME (e.g. quick, standard, browser). Semantic; nomArmy owns execution. Ignored by scouts.
continue_from	string	No	implement only: the job id of a retained, uncommitted implement job (partial, blocked, or failed verification) whose unfinished work this job should finish. The new worktree starts from that job's base with its changes in place, so brief only the correction; the finished whole, that work included, is verified and committed together. Use this instead of fixing a worker's files yourself, which would land them unverified. Leave base_ref out.
commit_subject	string	No	implement: the subject line of the commit nomArmy makes on the worker branch, e.g. "Keep held-back tables in the list_tables cache". Defaults to the task's first sentence; the body is the worker's NOTE, and the job id is a trailer.
timeout_seconds	integer	No	Default 600; 1200 for a review scout (one with `reviews`, or an army role in the review phase), since a real security review read for the full 10 minutes and was cut off.
verify_regression	boolean	No	implement only: after the diff passes `verification` and touches production files, temporarily revert just those production files, re-run the SAME verification profile (expected to fail without the fix), then restore them. A re-run that still PASSES proves no test would catch this regression, and the outcome is downgraded to NEEDS_REVIEW regardless of the worker's report -- never silently committed as done. This is the ONLY mechanism that catches a verification profile that passes for the wrong reason (a test-selection flag that accidentally excludes the changed file's own tests reports a real, honest, green run that never touched the diff -- exit-code checking alone cannot see the difference). Defaults to true whenever `verification` is set, since that gap is exactly what nomArmy's trust boundary claims to close; pass `false` explicitly to skip the doubled wall-clock cost (can matter on repos with thousands of tests) and accept the risk instead. No effect with no `verification` profile -- there is nothing to re-run. Ignored by scouts.
confirm_over_limit	boolean	No	Override a reached usage limit: the General must ask the operator before resubmitting with confirm_over_limit: true, or send the job to another agent. nomArmy never sets it itself.

Details

From the project README

Every byte verified. 🍪

nomarmy.dev · Docs · Sponsor

Your coding assistant plans; sandboxed workers build; nothing counts until nomArmy has checked it.

AI coding workers are confident. Their "done, all tests pass" is a claim, not evidence. nomArmy lets your coding assistant (Claude Code, Codex or Cursor) hand work to workers called noms, then checks every change itself before anything is committed: the real diff, your tests run in a fresh sandbox, a check that those tests actually catch the change, and a secret scan.

TL;DR

Have Git, Node 24.16+ (or 26.1+), Podman, and Claude Code, Codex or Cursor installed and signed in. On macOS, give Podman 8 GiB: brew install podman && podman machine init --memory 8192 && podman machine start. Windows is supported with the engine in WSL2. Follow the Windows setup.

Install and set up:

npm install -g nomarmy
cd your-project
nomarmy setup

nomarmy setup is a playbook. It shows a checklist and runs the next step each time you say yes:

✓ Where models run: hosted
✓ Installed: OpenClaw 2026.10.3
→ Agents: add a hosted agent
  Roles: add an agent first
  This repo: configure this project
  Check: verify the installation
Run `nomarmy agents add` now? [Y/n]

Stop anytime; nomarmy setup picks up where you left off. Want every step spelled out? Example setup: Claude Code, Codex and an API key goes command by command.

Use it: restart Claude Code in the project and ask it to use nomArmy for one small bug that has a test. When that works, try /feature <what you want built>.

Prefer a plugin? After step 2, Claude Code users can run /plugin marketplace add rayson-tech/nomarmy and /plugin install nomarmy@nomarmy instead of using nomarmy connect; Codex works too (plugins).

Stuck? nomarmy doctor checks the machine and nomarmy health checks everything nomArmy runs on. Upgrading later? nomarmy update.

How every byte gets verified

Your coding assistant, the General, briefs a job: a task, acceptance criteria, and the tests that prove it.
nomArmy creates a git worktree from your branch and runs the nom in a Podman sandbox with no network and no host credentials. (One exception, the Claude subscription: see Security posture.)
The nom edits, runs tests, and ends with a four-line report: STATUS, TESTS, NOT_DONE, NOTE.
nomArmy treats that report as a claim and checks the evidence itself:
- reads the real diff from git, not the nom's description of it
- runs your verification profile in a fresh sandbox
- reverts the production change and reruns the tests: a test that still passes proves nothing, so the job goes to review instead of being committed
- blocks on secrets, and flags tests made to pass (new skips, stubbed imports) and code nothing calls
Only then does it commit, on the nom's own branch. It never merges into yours: reviewing and integrating stay with the General, and with you.

Failing verification stays failed, unconditionally. A malformed report isn't automatically a failure: if the repository changed, nomArmy verifies independently and may recover the work. And the checks aren't the General's to waive: a repo's .nomarmy.yml policy (on by default for new repos) makes verification and the revert check mandatory for every job.

Showing what was checked. When a /feature run finishes, the General gets a "Verified by nomArmy" block for the pull request: how many "done, tests pass" claims held up, how many nomArmy caught and why, and the new tests shown to fail without their change. nomarmy stats --share prints the same for any period, and nomarmy stats --badge writes a README badge like nomArmy | 78 claims checked · 11 caught. Every number comes from the verified records.

Checking without building costs nothing: mode: verify runs a verification profile against any branch, with no worker and no model tokens.

Want deeper checks? Three optional validators go further, each only adding review flags: mutation testing (do the tests pin down the changed lines?), Jev (do a scout's citations support its findings, does a report match its diff?, on TypeSafe or a compatible server on your own machine) and a model judge (acceptance criteria, weakened tests).

Where the work runs

Agents say where a job can run: an API key, your own Claude, ChatGPT, Muse Code or Grok subscription (or another OpenClaw provider), or a local model on llama.cpp.
The army says which role runs on which agent: Sr and Jr devs build, a security analyst and a data architect review, a PM checks the plan, a PO accepts.
/feature runs a whole feature end to end, from plan through build, review and acceptance, and hands you a branch to merge.
Harnesses give each repo the right sandbox: Go, Rust, Python and Node (mixed repos too), Playwright browser tests, and fake services like a mock login server, all offline. Adding one never touches core code.

What you get is work you don't have to take on faith, not cheaper work. Delegating costs the General tokens too, for briefing and review: on small, already-diagnosed tickets we measured 4 to 8 times more of the General's tokens than fixing the bug directly, with break-even around 150 lines of context a fix needs to read (the measurements). It pays off on bigger tickets, parallel work, and anywhere you'd otherwise trust an agent's say-so.

Have a GPU or a Mac with plenty of memory? Choose "a local model" in nomarmy setup: no per-token bill and your code stays home, but you pay in hardware, power and speed. nomarmy sizing tells you what fits. A shared model server works too.

Developed and maintained by Rayson Technologies. This is a beta (0.1.0-beta): settings carry across upgrades (see config compatibility).

Docs


Install	Every setup: hosted (API keys and subscriptions), a local model on macOS, Linux, Windows with the engine in WSL2 or DGX Spark, a shared model server, Bedrock
Example setup	Claude Code, Codex and an API key, command by command
Agents and the army	Where a job can run, who does what, usage limits, picking an agent
`/feature` runs	A feature end to end, and watching what nomArmy is doing
Your repository	`.nomarmy.yml`, verification, dependencies, private registries, what nomArmy checks
Validators	Optional deeper checks: mutation testing, Jev, a model judge
Harnesses	Ecosystem registry, detection, network levels, and requirements
Configuration	Settings, swapping the local model, sizing, admission
Reference	Every CLI command and MCP tool
Security posture	What the sandbox holds back, and the one exception
FAQ	Which model for which role, switching models, usage limits
Troubleshooting	Symptoms and fixes

Security

A nom gets a writable git worktree inside a Podman sandbox and nothing else: no network, no host credentials, no Podman socket. Every model call is made by OpenClaw on your machine, never from inside the sandbox. Verification can climb a network ladder one rung at a time (fake services on a private network, then an allowlist you approve for a test tenant), but noms never leave network none. The exception is a Claude subscription, whose tools run on your machine, so nomArmy refuses build jobs on it unless you allow it. Never hand a nom production credentials, deployment access or SSH keys. Details: Security posture; to report a vulnerability, SECURITY.md.

Status

Capability	Status
Verification core: worktrees, nomArmy-owned git, independent verification, the revert check, kept failed worktrees	Working, end-to-end tested
`mode: verify`, secret scanning (secretlint, hard block), test-workaround and unwired-code checks	Unit and live tested; the heuristics are review flags
Scout and decompose modes, `auto_union`	Unit and live tested
Agents: API keys	Live-verified with xAI; other providers built to OpenClaw's documented interface
Agents: subscriptions	ChatGPT (Codex) and Muse Code sandboxed and live-verified; Claude live-verified, but its tools run on the host (scout and review by default)
Local (llama.cpp) and Bedrock profiles	Working
The army and `/feature`	Used daily on nomArmy itself and our own products: 783 jobs from September 18 to October 10, 2026 (measured results)
Harnesses: Go, Rust, Python, Node and mixed repos; Playwright; fake services	Live-verified offline
Private registries and a verification-only network allowlist	Live-verified; each passed an independent security review
Validators: mutation testing, Jev, a model judge	Unit and live tested; Jev and the judge evaluated on real job records
`nomarmy stats`	Checked against a hand-built report on real job records

What we've learned from real runs, including where delegating pays and where it doesn't, is in docs/findings.md.

Known limitations

A Claude subscription isn't sandboxed. Its tools run on your machine, so implement jobs on it are refused unless you set allow_host_tools: true. See Security posture.
Your own compose services aren't started yet. A verification profile that needs a real database from your compose file (environment: basic or higher) reports not_run rather than running without it (and the compose parser doesn't resolve YAML anchors). Fake services from harnesses, like the mock login server, do run.
Private registries don't cover Poetry or Yarn Berry yet: Poetry can't guarantee a credentialed install runs no package code, and Yarn Berry doesn't read .npmrc. uv, pip wheels, npm, pnpm, Yarn Classic and bun work. See Private registries.
A model a vendor lists but refuses is caught at dispatch, with a test call. The first job on a model that has never worked for its agent waits a few seconds for a one-token test call; a refusal (gpt-6-sol on a ChatGPT plan) is reported and remembered instead of costing the job. An inconclusive test call (a timeout) lets the job through.
Claude subscription token counts come from the Claude CLI's own session log, since OpenClaw sees only the final reply; totals include cache reads and writes.
Test-workaround detection is a flag, not a verdict: a legitimate new skip still gets flagged.
Deploy-time failures need your own check. See Add a check for what unit tests can't see.
Same-host sandboxes: the MCP server, OpenClaw and every job's sandbox run on the machine with the coordinator. Only the model can be elsewhere.

docs/findings.md: what real runs taught us.
docs/experiments: the measured write-ups behind them.
policies: how scouts and reviewers are held to account.
CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md.

Configuration variables are NOMARMY_*; a legacy RAYSON_* variable is translated once at load, with a deprecation warning.

Licensed under Apache 2.0.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.