Setup and diagnostics

Commands that install noomoo into a repository, remove it again, and report the state of the installation. All of them run as npx noomoo <command> from the repository root.

setup

Prints the plan of an installation and, with --yes, applies it. The plan lists the documents and the CI workflow it would create, the scripts it would add to package.json, the git settings and the .gitignore lines it would touch, the consent record it would write for the repository, and what it would do with core.hooksPath. Applying the plan writes .noomoo/setup-manifest.json, which rollback reads. Among the documents is .codex/config.toml: the Codex settings of the project with the noomoo MCP server (see mcp). Codex reads them only in a project the user has marked as trusted; setup never changes the user's own Codex configuration, and an existing .codex/config.toml stays as it is and is named in the plan. A core.hooksPath that already points elsewhere stays as it is unless --hooks=replace is given.

npx noomoo setup [--yes] [--hooks=keep|replace] [--json]

Flags: --yes applies the plan, --hooks chooses between keep (default) and replace for a foreign core.hooksPath, --json prints the plan as JSON.

Exit: 0 — the plan was printed or applied; 2 — an unknown argument or a --hooks value other than keep or replace.

rollback

Prints what the setup manifest allows noomoo to remove and restore and, with --yes, does it. Files you changed after setup are left in place unless --include-modified is given. Applying a rollback requires the repository's consent record and revokes it. Files that git ignores are removed even without --include-modified; without the consent record the command refuses.

npx noomoo rollback [--yes] [--include-modified] [--json]

Flags: --yes applies the plan, --include-modified also removes files changed after setup, --json prints the plan as JSON.

Exit: 0 — the plan was printed, the rollback was applied, or there was nothing to roll back; 1 — applying was refused because the repository has no consent record; 2 — an unknown argument.

init

Deploys or refreshes the document skeleton in the current repository. It is setup --yes with the default hooks policy: the same plan, applied at once, and the same manifest. The output lists created (+), updated (~) and skipped (·) paths, and says so when a foreign core.hooksPath was left alone.

npx noomoo init

Flags: none.

Exit: 0 — the structure is in place.

doctor

Reports whether the installation is complete: the document skeleton, the project commands, the CI workflow, the git hooks, the configured roles, the decision stamps, the issue tracker, the Claude CLI used by the judge, and the version of the package. Items that are information only do not affect the exit code. In a repository you consented to it also asks the GitHub API how merges are configured. Without --fix it writes nothing; with --fix it deploys the same skeleton as setup --yes, writes the setup manifest and the consent record for the repository (so rollback undoes it), adds missing keys of config/pipeline.json and config/tracker.json, refreshes copies of skills that differ from the package, and removes obsolete scaffolding.

npx noomoo doctor [--fix] [--json]

Flags: --fix applies the repairs, --json prints the report, the lists of added, updated, skipped and removed paths and whether the consent was written (trust) as JSON.

Exit: 0 — every required item is in place; 1 — at least one required item is missing.

claude-hook-docs

The hook entry used by Claude Code after an edit. It reads the hook event as JSON from standard input; when the edited file is under docs/ (and not under docs/validation/), it runs the quick edit profile and prints the findings of that file, with a count of the others. It never fails the edit: whatever happens, it exits 0. The hook of the plugin calls this command after its own check of the manifest and of your consent. Running the profile writes the artifacts of the run to docs/validation/.

npx noomoo claude-hook-docs < event.json

Flags: none.

Exit: 0 — always.

contour-config

Prints the resolved project configuration as JSON: the defaults of noomoo merged with config/pipeline.json. Commands in commands that cannot run in the project are listed on standard error, so the JSON on standard output stays clean. See Configuration for every key.

npx noomoo contour-config

Flags: none.

Exit: 0 — the configuration was resolved; 1 — config/pipeline.json cannot be parsed or a section is not an object.

context-status

Shows the merge state of the current branch against the configured target branch and the state of the project context: the package version and the counts of documents. With --write it saves the same data to .agent/context/status.md, replacing the file atomically. With both --json and --write only the JSON is printed and nothing is written.

npx noomoo context-status [--json] [--write]

Flags: --json prints the model as JSON, --write saves the table to .agent/context/status.md.

Exit: 0 — the status was built.

status

Shows the state of the project in one read: the project, branch and revision; whether the noomoo hooks guard the repository; whether the last check is current for this revision or stale; the open work — tasks, backlog with the entries that are done and ready to archive named, requirements and proposals, with implicit default statuses counted apart; and the findings that need attention — blockers, unavailable checks and warnings, each with its rule, text, run revision and place. Findings of the baseline are not counted as warnings; the attention block names their number as Known. The command only reads: it runs no check and writes nothing, not even a line in the event log. Colours follow the theme chosen in Claude Code; NO_COLOR turns them off and FORCE_COLOR turns them on without a terminal.

npx noomoo status [--json] [--short] [--details]

Flags: --json prints the status model as JSON, --short prints one line for a status line — a traffic light, the state in words, the current task (named by the branch, else the task in progress) with its backlog entry, warnings and the todo count; when the last check predates the current tree, the light keeps the verdict of that check and the state reads ↻ checked <age> — and --details lists every finding that needs attention instead of one group per rule with its count and an example.

Exit: 0 — the status was built, whatever the state of the project; 1 — the directory is not a noomoo project or the status could not be collected; 2 — an unknown flag, --json with --short, or --details with --short.

next

Prints the next step of the project, computed from its files: what to do, why, and the command that does it. A project without setup gets setup; a project with neither requirements nor raw materials gets the interview of /noomoo:start; a red gate comes before new raw materials; then requirements without a chain, tasks ready to start and tasks in progress. A task waiting for an open dependency is listed with --all but never recommended. A task written against a requirement that has changed since is not started or repaired as it stands: next recommends revisiting it against the new requirement first. The command only reads: the gate runs without writing, and the same files give the same answer.

npx noomoo next [--json] [--all]

Flags: --json prints the answer as JSON (schema version, stage, recommended action, all actions), --all lists every open action with its status.

Exit: 0 — the step was computed; 2 — the project could not be read, and the reason goes to standard error.

mcp

Runs an MCP server over standard input and output for agents without the Claude plugin, such as Codex. Each line is one JSON-RPC 2.0 message; standard output carries protocol messages only. The server offers six tools, each running its command in the directory where the server started: noomoo_status (status --json), noomoo_next (next --json), noomoo_validate (validate), noomoo_doctor (doctor --json) — all four without arguments — and noomoo_evidence (evidence TASK-NNN --json), which takes the task id as task; and noomoo_gate, which takes gate (task-ready, or plan-ready, run with --judge) and task and returns the verdict of that gate. An id not of the form TASK-NNN, another gate or any other field is refused before any command runs. A red gate, a decision left to a person and an unavailable judge are verdicts, not tool errors. A failed check of validate or doctor is a normal result; a tool reports an error when its command gave no answer — it could not run, or evidence did not find the task. noomoo_validate writes the check record under docs/validation/, as validate does from the terminal; the other tools write nothing. Nothing that stamps, approves, merges or applies setup is reachable through the server.

A gate with the AI judge takes from seconds to several minutes. When the client gives up on a call and sends notifications/cancelled, the server stops the command with its whole process tree, judge included, and does not answer that call. The same happens to every call in flight when the client closes the server's input or stops the server. A cancelled call leaves no gate round, command record or telemetry. Codex waits for a tool call tool_timeout_sec seconds, 60 by default; for gates raise it, for example to 900, under [mcp_servers.noomoo] in its configuration.

npx noomoo mcp

With Codex: setup writes .codex/config.toml into the project with the server under [mcp_servers.noomoo], started by the project's package manager without the registry (npx --offline --no-install noomoo mcp for npm), tool_timeout_sec = 900, default_tools_approval_mode = "approve" and enabled_tools naming the six tools, so a tool added in a later version is not approved until setup runs again. Codex loads it once you mark the project as trusted in Codex. Without the approval setting codex exec cannot ask and refuses every tool call. A project that keeps its own .codex/config.toml adds the same section to it by hand. A project set up by an earlier version gets the file from a repeated setup --yes; its AGENTS.md is not rewritten, so the Codex section of the new template is copied into it by hand. doctor does not require the file: a project without Codex may delete it.

Flags: none.

Exit: 0 — the client closed its input, stopped reading, or stopped the server; calls in flight were cancelled.

identity

Prints the GitHub login that owns the token in use, the kind of run (human, agent or CI) and the roles the login holds in config/pipeline.json. The token comes from GITHUB_TOKEN, GH_TOKEN or the authorization of the gh CLI. The login is resolved with a request to the GitHub API and cached in the settings directory. The token itself is never printed. Decision stamps take the author from this identity, not from text.

npx noomoo identity [--json]

Flags: --json prints the identity, the roles and the reason for a failure as JSON.

Exit: 0 — the identity is established; 1 — it is not established, and the reason goes to standard error; 2 — an unknown argument.

locale-parity

Compares a translation of the message catalog with the Russian catalog. The file is either a flat object of message keys and texts or the export of files, keys and {ru, en} cells; only the en text is read. The report names missing keys, empty translations and keys that are not in the Russian catalog, and checks the form of every translated text: the set of {placeholders}, leading spaces and line breaks, guillemets, and the flags, document identifiers and emoji of the Russian text. A partial translation is accepted and reported, not rejected.

npx noomoo locale-parity <file.json> [--json]

Flags: --json prints the report as one JSON object.

Exit: 0 — no form mismatch and no extra key, missing and empty keys are only reported; 1 — a form mismatch or a key that is not in the Russian catalog; 2 — wrong arguments or a file that cannot be read.

public-artifact-check

Checks a directory that is about to be published as a package. It reports telemetry-sending modules, secrets and, given a forbidden list, references to infrastructure and receiver addresses that must not ship — in plain text, concatenated literals, base64 and hex. Findings are printed one per line as kind file[:line] — description, with a [glued], [base64] or [hex] tail for the non-plain forms. Without the forbidden list those references are not checked, and the output says so. References that are known and justified can be listed in a JSON file given with --allow; each entry has file, match and reason.

npx noomoo public-artifact-check <directory> [--allow <file.json>] [--forbidden <file.json>]

Flags: --allow names a JSON array of permitted references; --forbidden names the list of identifiers to look for ({ "schema": 1, "literals": [...], "patterns": [{ "pattern", "flags" }], "hosts": [...] }). Each flag is accepted at most once.

Exit: 0 — the artifact is clean; 1 — there are findings or the directory could not be read; 2 — wrong arguments.