commit-discipline-mcp

<p align="center"> <img src="./assets/hero.svg" alt="commit-discipline-mcp — plan, test, and commit agent work safely" width="100%" /> </p>

<p align="center"> <a href="https://www.npmjs.com/package/commit-discipline-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/commit-discipline-mcp?style=flat-square&color=cb3837" /></a> <a href="https://www.npmjs.com/package/commit-discipline-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/commit-discipline-mcp?style=flat-square&color=3178c6" /></a> <a href="https://github.com/ayush-singh-0601/commit-discipline-mcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ayush-singh-0601/commit-discipline-mcp?style=flat-square&color=f5b83d" /></a> <a href="https://github.com/ayush-singh-0601/commit-discipline-mcp/actions/workflows/ci.yml"><img alt="cross-platform CI" src="https://img.shields.io/github/actions/workflow/status/ayush-singh-0601/commit-discipline-mcp/ci.yml?branch=main&style=flat-square&label=Windows%20%7C%20Linux%20%7C%20macOS" /></a> <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/commit-discipline-mcp?style=flat-square&color=2ea44f" /></a> <a href="https://nodejs.org"><img alt="Node 18 or newer" src="https://img.shields.io/node/v/commit-discipline-mcp?style=flat-square" /></a> </p>

<p align="center"><strong>Small commits. Passing tests. Predictable agent workflows.</strong></p>

<p align="center"> A cross-platform MCP server and CLI that turns one coding task into 2–4 ordered,<br /> test-gated Git commits—without pushing, rewriting history, or sending telemetry. </p>

<p align="center"> <a href="#quick-start"><strong>Quick start</strong></a> · <a href="#how-it-works"><strong>How it works</strong></a> · <a href="./docs/quickstart.md"><strong>Guided demo</strong></a> · <a href="#configuration"><strong>Configuration</strong></a> </p>

---

Why commit discipline?

Coding agents can solve large tasks quickly, but their Git history often arrives as one oversized commit—or a trail of commits made before tests ran. commit-discipline-mcp puts a small, deterministic control loop around that work.

Common failure mode	Built-in guardrail
One giant, hard-to-review commit	Every task is planned into 2–4 ordered stages
Tests are run after the commit	The detected test suite must pass before staging
Unrelated files sneak into a commit	Files outside the active stage block the operation
An agent skips ahead	Only the next pending stage can be committed
Manual commits invalidate the plan	Unexpected HEAD movement is detected
A tool silently pushes code	This package never pushes or rewrites Git history

It works with Codex, Claude Code, Cursor, and any MCP client that supports stdio tools. The same workflow is also available as a regular CLI.

Quick start

Requirements: Node.js 18+, Git, and a clean Git repository.

npx -y commit-discipline-mcp@latest init --client all --yes

That command adds project-scoped MCP configuration and a reusable commit-discipline skill. Commit the generated files, reload your coding client, and ask:

Use commit-discipline to split this task into small test-gated stages. Commit each completed stage and finish the task when the worktree is clean.

Choose clients explicitly when needed:

npx -y commit-discipline-mcp@latest init --client codex --yes
npx -y commit-discipline-mcp@latest init --client claude --yes
npx -y commit-discipline-mcp@latest init --client cursor --yes

Client	MCP configuration	Installed skill
Codex	.codex/config.toml	.codex/skills/commit-discipline/SKILL.md
Claude Code	.mcp.json	.claude/skills/commit-discipline/SKILL.md
Cursor	.cursor/mcp.json	.cursor/skills/commit-discipline/SKILL.md

Use --dry-run to preview changes. Existing configuration is merged and backed up; --force is required to replace a conflicting entry.

How it works

flowchart LR
    A[Clean repository] --> B[Plan 2–4 stages]
    B --> C[Work on current stage]
    C --> D{Tests pass?}
    D -- No --> C
    D -- Yes --> E[Validate scope and limits]
    E --> F[Create focused commit]
    F --> G{Stages left?}
    G -- Yes --> C
    G -- No --> H[Finish with clean worktree]

The MCP server exposes four focused tools:

Tool	Purpose
plan_task	Record 2–4 stages with exact repository-relative files
commit_stage	Test, validate, stage, and commit only the active stage
task_status	Report progress and the next permitted stage
finish_task	Verify all stages are complete and the worktree is clean

Plan state is stored locally in .commit-discipline/plan.json and ignored by default.

CLI workflow

Prefer a terminal? Install the binary globally:

npm install --global commit-discipline-mcp

Create a stage file:

[
  {
    "id": "core",
    "title": "Build the core",
    "description": "Implement the service layer",
    "files": ["src/core.ts"]
  },
  {
    "id": "tests",
    "title": "Add coverage",
    "description": "Cover the service behavior",
    "files": ["tests/core.test.ts"]
  }
]

Then run the lifecycle:

commit-discipline plan-task --description "Build the feature" --stages-file stages.json
commit-discipline task-status
commit-discipline commit-stage core --message "feat: add core service"
commit-discipline commit-stage tests --message "test: cover core service"
commit-discipline finish-task

See the guided throwaway-repository demo for copy-pasteable PowerShell and Bash examples.

Configuration

Add commit-discipline.config.json to the repository root when the defaults need adjustment:

{
  "schemaVersion": 1,
  "enforcement": "strict",
  "maxFiles": 15,
  "maxLines": 400,
  "testTimeoutMs": 900000,
  "planVisibility": "local",
  "testCommand": {
    "command": "npm",
    "args": ["test"]
  }
}

Option	Default	Behavior
enforcement	warn	Use strict to block stages over configured limits
maxFiles	15	Maximum changed files per stage
maxLines	400	Maximum added and deleted lines per stage
testTimeoutMs	900000	Test-process timeout in milliseconds
planVisibility	local	Store plan state locally or as tracked project state
testCommand	auto-detected	Override the test command and arguments

Without an override, the tool detects one JavaScript, Python, Go, Rust, or Make test ecosystem. If several ecosystems are present, set testCommand explicitly. Failed tests always block a commit.

<details> <summary><strong>Useful CLI options</strong></summary>

• --file <path> commits a subset of the active stage's declared files.
• --max-files N and --max-lines N apply one-off limits.
• --dry-run validates a stage without tests, staging, commits, or state changes.
• --json returns machine-readable output for scripts and agents.

</details>

Safety by design

• Plans start only from a clean worktree.
• Absolute paths and path traversal are rejected.
• Pre-existing staged files and out-of-scope changes are blocked.
• Tests run before staging; scope is checked again afterward.
• Dry runs do not mutate Git or plan state.
• No runtime network calls and no telemetry.
• No git push, force operations, resets, or history rewriting.

Platform support

Every release is exercised across Windows, Ubuntu, and macOS on Node.js 18, 20, and 22. Packed-package smoke tests cover the full CLI lifecycle and the MCP stdio handshake.

Platform	Native launch path	Status
Windows	cmd.exe + npm shim	Tested in PowerShell and Command Prompt
Linux	npx	Tested in Bash
macOS	npx	Tested in Zsh

For implementation details and trust boundaries, read the architecture overview. Reusable starting points are available in examples/.

Development

git clone https://github.com/ayush-singh-0601/commit-discipline-mcp.git
cd commit-discipline-mcp
npm ci
npm run verify
npm run smoke:package
npm run benchmark:git

The release gate includes type checking, 46+ unit and integration tests, package installation, a complete CLI/MCP lifecycle, and a Git-overhead benchmark against the PRD's 300 ms target.

Community

• Read CONTRIBUTING.md before opening a pull request.
• Report vulnerabilities privately using SECURITY.md.
• Get usage help through SUPPORT.md.
• See CHANGELOG.md for release history.
• Track upcoming directions in ROADMAP.md.

If this project makes your agent-generated Git history easier to review, consider starring it—it helps other developers discover the tool.

License

MIT © Ayush Singh