Thank you for your interest in contributing to NVIDIA NemoClaw. This guide covers how to set up your development environment, run tests, and submit changes.

All participants are expected to follow our Code of Conduct.

We welcome many types of contributions:

Security vulnerabilities must follow SECURITY.md — not GitHub issues.

New contributors should start with issues labeled good first issue. These are scoped tasks with clear acceptance criteria that do not require deep project knowledge.

Before starting larger work:

• Search open issues and pull requests to avoid duplicates.
• Start a GitHub Discussion before writing code for significant changes.
• Open an issue after the proposal has enough scope and design detail for maintainer review.
• For questions, open a GitHub Discussion or comment on a related issue.

Open an issue when you encounter one of the following situations.

• A real bug that you confirmed and could not fix.
• A feature proposal with a design — not a "please build this" request.
• Security vulnerabilities must follow SECURITY.md — not GitHub issues.

Use GitHub Discussions for questions, design exploration, and larger feature proposals before implementation. Maintainers may ask you to move broad or still-forming proposals from an issue to a discussion so the design can settle before code review.

NemoClaw is an alpha project, and maintainer availability varies with release, security, and stability work. Issues, discussions, and pull requests are reviewed on a best-effort basis. The project does not publish guaranteed response or review timelines.

Maintainers prioritize work using severity, security impact, release readiness, reproducibility, maintainer capacity, and community impact. For public roadmap context and current priorities, see Current Priorities. That section is a planning aid, not a commitment that a specific issue or feature will ship in a specific release.

Install the following before you begin.

• Node.js 22.16+ and npm 10+
• Python 3.11+ (for blueprint and documentation builds)
• Docker (running)
• uv (for Python dependency management)
• hadolint (Dockerfile linter — brew install hadolint on macOS)

Install the root dependencies and build the TypeScript plugin:

# Install root dependencies (OpenClaw + CLI entry point)
npm install

# Install and build the TypeScript plugin
cd nemoclaw && npm install && npm run build && cd ..

# Install Python deps for the blueprint
cd nemoclaw-blueprint && uv sync && cd ..

The TypeScript plugin lives in nemoclaw/ and compiles with tsc:

cd nemoclaw
npm run build        # one-time compile
npm run dev          # watch mode

The CLI (bin/, scripts/) is type-checked separately:

npm run typecheck:cli   # or: npx tsc -p tsconfig.cli.json

After building, return to the repository root and link the CLI so the nemoclaw command is available locally. If you followed the build step above, you are still inside nemoclaw/ and must cd .. first:

cd ..                   # back to the repo root (from nemoclaw/ subdirectory)
npm link
nemoclaw --version      # verify the linked version

To unlink when you are done: npm unlink -g nemoclaw

These are the primary make and npm targets for day-to-day development:

All git hooks are managed by prek, a fast, single-binary pre-commit hook runner installed as a devDependency (@j178/prek). The npm install step runs prek install automatically via the prepare script, which wires up the following hooks from .pre-commit-config.yaml:

For PR preparation, normal commit and push hooks are valid verification when they ran without --no-verify. If hooks were skipped, missing, failed, or uncertain, use a scoped fallback: npx prek run --from-ref <base> --to-ref HEAD. Reserve npx prek run --all-files for whole-repository baselines, such as hook, formatter, generated-check, or repo-wide validation changes.

For TypeScript changes under src/, test/, scripts/, bin/, or nemoclaw-blueprint/scripts/ (and for tsconfig.cli.json updates), the pre-push hook runs npm run typecheck:cli before the branch is pushed. CI runs this unconditionally. If the pre-push hook was skipped or unavailable, run npm run typecheck:cli manually before opening a PR.

If you still have core.hooksPath set from an old Husky setup, Git will ignore .git/hooks. Run git config --unset core.hooksPath in this repo, then npm install so prek install (via prepare) can register the hooks.

make check remains the primary documented linter entry point.

For doc-only changes, you do not need to run the full test suite by default. Commit and push normally so the hooks run, then run the docs build:

npm run docs

Leave npm test unchecked in the PR verification checklist unless you actually ran it. If hooks were skipped or unavailable, run npx prek run --from-ref main --to-ref HEAD before opening the PR. For code changes, run targeted tests for the changed behavior. Reserve full npm test for broad runtime changes, test harness changes, or cases where targeted coverage is hard to justify.

The repository is organized as follows.

All new source files must be TypeScript. Do not add new .js files to the project. When modifying an existing JavaScript file, prefer migrating it to TypeScript in the same PR.

Only a small CommonJS launcher/compatibility layer remains in bin/, while the main CLI implementation now lives in src/lib/ and compiles to dist/. Tests in test/ may remain ESM JavaScript for now but new test files should use TypeScript where practical.

Shell scripts (scripts/*.sh) must pass ShellCheck and use shfmt formatting.

If your change affects user-facing behavior (new commands, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under docs/ in the same PR.

If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the nemoclaw-contributor-update-docs skill that drafts doc updates. Use it before writing from scratch and follow the style guide in docs/CONTRIBUTING.md. During release prep, run that skill first, make any doc version bumps, regenerate user skills, then open the docs refresh PR.

To build and preview docs locally:

$ npm run docs                 # validate Fern docs with the pinned Fern CLI version
$ npm run docs:live            # serve Fern docs locally with auto-rebuild
$ npm run docs:preview:watch   # publish branch-based Fern previews on file changes

Use these npm scripts when validating docs for a PR.

See docs/CONTRIBUTING.md for the full style guide and writing conventions.

For user-skill definitions, docs-to-skills validation, release-prep regeneration, and script flags, see Doc-to-Skills Pipeline.

We welcome contributions. Every PR requires maintainer review before merge. To keep the review queue healthy, limit the number of open PRs you have at any time to fewer than 10. Maintainers review pull requests according to project priority, security impact, release readiness, and reviewer availability. PRs that solve issues with Priority set to Urgent or High are more likely to receive earlier review when maintainers have capacity. For substantial features or behavior changes, start with a GitHub Discussion before opening a large implementation PR.

This project requires a Developer Certificate of Origin (DCO) sign-off declaration in every pull request description. Add the following trailer at the bottom of the PR description:

Signed-off-by: Your Name <your.email@example.com>

CI will reject PRs whose descriptions are missing this declaration.

This project also requires every PR commit to appear as Verified in GitHub. Configure your local Git client or GitHub web editor to create verified signed commits before you open a pull request. Maintainers do not repair contributor signature failures.

Use GitHub's official documentation to set this up:

• About commit signature verification
• Signing commits

If the PR description is missing the DCO declaration, update the PR description before requesting review. If any commit is missing GitHub verification, fix the branch before opening a PR. If force-push is not allowed after an unverified commit is published, open a fresh branch and fresh PR with a clean compliant history.

Do not add links to third-party code repositories, community collections, or unofficial resources in documentation, README files, or code. This includes "awesome lists," community template repositories, wrapper projects, and similar community-maintained resources — regardless of popularity or utility.

Links to official documentation for tools we depend on (e.g., Node.js, Python, uv) and industry standards (e.g., Conventional Commits) are acceptable.

Why: External repositories are outside our control. They can change ownership, inject malicious content, or misrepresent an endorsement by NVIDIA. Keeping references within our own repo avoids these risks entirely.

If you believe an external resource belongs in our docs, open an issue to discuss it with maintainers first.

Follow these steps to submit a pull request.

1. Create a feature branch from main.
2. Make your changes with tests.
3. Run the relevant checks. Let normal commit and push hooks provide hook verification, run targeted tests for changed behavior, and run npm run docs for doc changes. If hooks were skipped or unavailable, run npx prek run --from-ref main --to-ref HEAD.
4. Confirm the PR description includes the DCO declaration and every commit appears as Verified in GitHub.
5. Open a PR.

This project uses Conventional Commits. All commit messages must follow the format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• chore - Maintenance tasks (dependencies, build config)
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• ci - CI/CD changes
• perf - Performance improvements

Examples:

feat(cli): add --profile flag to nemoclaw onboard
fix(blueprint): handle missing API key gracefully
docs: update quickstart for new install wizard
chore(deps): bump commander to 13.2