Installation

If you want the fastest path to a first successful run, install the prebuilt CLI from npm.

Fastest path: npm

npm install -g @monochange/cli
monochange --help

Then continue with Start here or Your first release plan.

Alternative: Nix / devenv

If you use devenv or the Nix package manager, monochange is available via the ifiokjr/nixpkgs flake:

# flake.nix
inputs = {
  ifiokjr-nixpkgs.url = "github:ifiokjr/nixpkgs";
};

Then add monochange to your devenv packages:

# devenv.nix
let
  extra = inputs.ifiokjr-nixpkgs.packages.${pkgs.stdenv.system};
in
{
  packages = [ extra.monochange ];
}

Or run directly without adding to your flake:

nix run github:ifiokjr/nixpkgs#monochange

Alternative: Cargo

If you prefer to install from Rust tooling instead:

cargo install monochange
monochange --help

Optional: assistant skill package

You do not need assistant tooling to use monochange.

When you want reusable agent guidance for Pi or other assistants, install the bundled skill into the current project with:

monochange help skill
monochange skill
monochange skill read configuration
monochange skill install --dir ./.claude/skills/monochange

The skill ships inside the binary, so it needs no network access or npm install. monochange skill read serves any bundled topic as raw Markdown, and monochange skill install --dir writes the whole tree into an agent runtime’s skills directory.

After copying the bundled skill, you get a small documentation set that is designed to load in layers:

• SKILL.md: concise entrypoint for agents
• REFERENCE.md: broader high-context reference with more examples
• skills/README.md: index of focused deep dives
• skills/adoption.md: setup-depth questions, migration guidance, and recommendation patterns
• skills/change-classification.md: release-aware severity decisions, uncertainty, and ecosystem review
• skills/changesets.md: changeset authoring and lifecycle guidance
• skills/commands.md: built-in command catalog and workflow selection
• skills/configuration.md: monochange.toml setup and editing guidance
• skills/linting.md: [lints] presets, monochange check, and manifest-focused examples
• examples/README.md: condensed scenario examples for quick recommendations

This layout keeps the top-level skill small while still making the richer guidance available when an assistant needs more context.

Assistant-specific setup is covered in Advanced: Assistant setup and MCP.

CLI name

The CLI executable is monochange. The old mc binary alias was removed, so repository automation should call monochange directly.

Repository development

If you are working on the monochange repository itself, use the reproducible development shell:

devenv shell
install:all
monochange step validate
monochange step discover --format json
monochange run change --package monochange --bump minor --reason "add release planning"
monochange step diagnose-changesets --format json
monochange run release --dry-run --format json
monochange step publish-release --dry-run --format json
monochange step open-release-request --dry-run --format json
monochange step release-record --from v1.2.3
monochange step tag-release --from HEAD --dry-run --format json
monochange step publish-readiness --from HEAD --output .monochange/readiness.json
monochange step placeholder-publish
monochange step publish-readiness --from HEAD --output .monochange/readiness.json
monochange step plan-publish-rate-limits --readiness .monochange/readiness.json --format json
monochange step publish-packages --output .monochange/publish-result.json
monochange step retarget-release --from v1.2.3 --target HEAD --dry-run
monochange run release

Useful repository-development commands:

monochange --help
docs:check      # verify mdt shared-doc synchronization
docs:update     # synchronize shared docs via mdt update
schema:check    # verify committed JSON schemas are current
schema:update   # regenerate schema assets from source
monochange step validate
lint:all
test:all
coverage:all
coverage:patch
build:all
build:book