monochange

manage versions and releases for your multiplatform, multilanguage monorepo

monochange is a release-planning toolkit for monorepos that span more than one package ecosystem.

It discovers packages, normalizes dependency data, applies group rules, turns explicit change files into release plans, and can run config-defined release preparation from those same inputs.

Use it when your repository has outgrown one-ecosystem release tooling and you want one model for Cargo, npm/pnpm/Bun, Deno, and Dart/Flutter.

Who monochange is for

• maintainers of monorepos that span more than one package ecosystem
• teams replacing ad hoc release scripts with explicit, reviewable change files
• people who want one safe release-planning model before adding provider automation

First 10 minutes

Install the prebuilt CLI from npm:

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

If you prefer a Rust-native install, use cargo install monochange instead.

Then run one safe local walkthrough:

Generate a starter config from the packages monochange detects:

mc init

mc init writes an annotated monochange.toml, so most first-time users can start with the generated file instead of hand-authoring config. If you later want editable copies of the built-in CLI commands, run mc populate to append any missing default command definitions to monochange.toml.

For automated CI setup, include the --provider flag:

mc init --provider github

This configures the [source] section, generates CLI commands for commit-release and release-pr, and creates GitHub Actions workflows.

Validate the workspace:

mc validate

Discover the package ids you will use in commands and changesets:

mc discover --format json

Create one change file for a package id:

mc change --package <id> --bump patch --reason "describe the change"

Most changes should target a package id. Use group ids only when the change is intentionally owned by the whole group.

Preview the release plan safely:

mc release --dry-run --format json

Add --diff when you want unified file previews for version and changelog updates without mutating the workspace:

mc release --dry-run --diff

This first run is safe: nothing is published. Stop here until you are ready to prepare release files locally.

When you are ready to prepare the release locally, run mc release.

If you do not know which package id to target, rerun mc discover --format json and copy an id directly from the output.

Next steps

• Start here — the shortest beginner path through installation, mc init, and --dry-run
• Installation — npm, Cargo, optional assistant tooling, and repository-development setup
• Your first release plan — a fuller walkthrough built around generated config
• Discovery — what monochange finds and how ids are rendered
• Configuration reference — evolve the generated config once the basics feel familiar
• Groups and shared release identity — when to reach for group ids instead of package ids

Why use monochange?

• use one release-planning model across several language ecosystems
• replace ad hoc scripts with explicit change files and deterministic release output
• keep related packages synchronized with [group.<id>]
• propagate dependent bumps through one normalized dependency graph
• expose top-level CLI commands from [cli.<command>] entries in monochange.toml

Advanced workflows

GitHub automation

monochange can promote one prepared release into several source-provider automation flows without changing the underlying release-plan model.

• mc release --dry-run --format json refreshes the cached manifest and shows downstream automation data, including authored changesets plus linked release context metadata
• mc publish-release --dry-run --format json previews provider release payloads before publishing
• mc release-pr --dry-run --format json previews the release branch, commit, and release-request body
• mc release-record --from <tag> inspects the durable release declaration stored in the release commit body
• mc repair-release --from <tag> --dry-run previews a release-retarget plan before mutating tags
• changelog templates can render linked change owners, review requests, commits, and closed issues through {{ context }} or fine-grained metadata variables
• mc affected --format json --changed-paths ... evaluates pull-request changeset policy from CI-supplied paths and labels
• mc diagnostics --format json shows all discovered changeset context or restricts to explicit inputs

Assistant setup and MCP

Assistant tooling is optional.

When you want AI-assisted workflows, monochange ships built-in setup guidance and an MCP server:

npm install -g @monochange/skill
monochange-skill --print-install
mc assist pi
mc mcp

See Advanced: Assistant setup and MCP for the full setup flow.

What monochange can do today

• discover Cargo, npm/pnpm/Bun, Deno, Dart, and Flutter packages
• normalize dependency edges across ecosystems
• coordinate shared package groups from monochange.toml
• compute release plans from explicit change input
• expose top-level CLI commands from [cli.<command>] definitions
• run config-defined release commands from .changeset/*.md
• render changelogs through structured release notes and configurable formats
• emit stable release-manifest JSON for downstream automation
• preview or publish provider releases and release requests from typed command steps and shared release data
• inspect durable release records from tags or descendant commits with mc release-record
• repair a recent source/provider release by retargeting its release tags with mc repair-release
• inspect changeset context and review metadata with mc diagnostics for both human and automation workflows
• apply Rust semver evidence when provided
• expose built-in assistant setup guidance with mc assist and a stdio MCP server with mc mcp
• publish the CLI as @monochange/cli and the bundled agent skill as @monochange/skill
• publish end-user documentation through the mdBook in docs/

Workspace crates

• monochange — end-user CLI and orchestration layer for discovery, planning, and CLI-defined release commands.
  • 
• monochange_core — shared domain model for packages, dependency edges, groups, change signals, and release plans.
  • 
• monochange_config — loads monochange.toml, parses .changeset/*.md, and validates CLI command inputs.
  • 
• monochange_graph — propagates release impact through dependency edges and synchronized groups.
  • 
• monochange_github — converts release manifests into GitHub release payloads and publishing operations.
  • 
• monochange_semver — merges requested bumps with compatibility-provider evidence.
  • 
• monochange_cargo — Cargo discovery plus Rust semver evidence integration.
  • 
• monochange_npm — npm, pnpm, and Bun workspace discovery.
  • 
• monochange_deno — Deno workspace and package discovery.
  • 
• monochange_dart — Dart and Flutter workspace discovery.
  • 

Repository development

Enter the reproducible development shell and install workspace tooling:

devenv shell
install:all
mc validate
mc discover --format json
mc change --package monochange --bump minor --reason "add release planning"
mc diagnostics --format json
mc release --dry-run --format json
mc publish-release --dry-run --format json
mc release-pr --dry-run --format json
mc release-record --from v1.2.3
mc repair-release --from v1.2.3 --target HEAD --dry-run
mc release

Useful commands:

monochange --help
mc --help
docs:check
docs:update
mc validate
lint:all
test:all
coverage:all
build:all
build:book

See docs/ for user-facing guides and CONTRIBUTING.md for contribution expectations.