commit-discipline-mcp

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.

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.

Related MCP server: Development Workflow MCP Server

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

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:

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"]
  }
}

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.

• --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.

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.

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