Skip to content
mx-workflow

Getting Started

mx-workflow is the review-grade quality layer for AI-generated code for Claude Code. Generating code is table stakes; mx-workflow is the layer that interrogates it — pushing back on hallucinated APIs, silent failures, suppressed errors, and type rot before they ship. Eight review-grade agents do the interrogating, backed by a full dev-lifecycle toolkit (planning, implementation, conventional commits, PRs, and multi-agent builds) underneath.

Prerequisites

Section titled “Prerequisites”

Before installing mx-workflow, make sure you have:

  • Claude Code CLI installed and working
  • git configured with SSH or HTTPS access to your repositories

Installation

Section titled “Installation”

There are three ways to install mx-workflow. Choose the one that fits your setup.

Section titled “Option A: Marketplace install (recommended)”

Register the mx-workflow repository as a plugin marketplace, then install:

Terminal window
# 1. Add the marketplace (one-time)
/plugin marketplace add https://github.com/joshtune/mx-workflow.git


# 2. Install the plugin
/plugin install mx@joshtune-mx-workflow

When prompted, choose a scope:

ScopeWhere it’s storedWho has access
user~/.claude/settings.jsonYou, in all projects
project.claude/settings.jsonEveryone on the team
local.claude/settings.local.jsonYou, on this machine only (gitignored)

Option B: Clone and load per-session

Section titled “Option B: Clone and load per-session”
Terminal window
# Clone the repo
git clone https://github.com/joshtune/mx-workflow.git ~/mx-workflow


# Load for current session
claude --plugin-dir ~/mx-workflow

This is temporary — the plugin is only available for that session.

Option C: Clone and configure permanently

Section titled “Option C: Clone and configure permanently”
Terminal window
# Clone the repo
git clone https://github.com/joshtune/mx-workflow.git ~/mx-workflow

Then add the path to your Claude Code settings. Edit ~/.claude/settings.json:

{
  "plugins": ["~/mx-workflow"]
}

The plugin will load automatically in every session.

Verify installation

Section titled “Verify installation”

Once installed, type /mx: in Claude Code and you should see all commands in autocomplete.

Test with:

/mx:help

This displays the full command reference card.

Try it first: /mx:review

Section titled “Try it first: /mx:review”

The fastest way to understand what mx-workflow is for is to point it at some code. On any branch with changes — yours or an AI’s — run:

/mx:review

It bundles all eight review-grade agents into a single verdict — PASS, PASS WITH WARNINGS, or REJECT — with per-agent findings and a recommendation. Reviewing a PR an AI generated (Claude, Cursor, Copilot)? Use /mx:second-look <PR number>. Suspect an invented API? /mx:hallucination-check. See the Demo: catching a hallucinated API for a concrete walkthrough.

A full session

Section titled “A full session”

mx-workflow also covers the lifecycle that produces the code it reviews. Here is a typical end-to-end walkthrough:

1. Load codebase context

Section titled “1. Load codebase context”
/mx:prime

This reads key project files (like CLAUDE.md, package.json, tsconfig.json) and runs initial quality checks so Claude understands your project’s structure, conventions, and current health.

2. Check project readiness

Section titled “2. Check project readiness”
/mx:status

See what tools are available (linter, type checker, test runner) and whether the project is in a clean state. Fix any blockers before writing code.

3. Pick a task and plan

Section titled “3. Pick a task and plan”

If you have a ticket, create a branch first:

/mx:branch EIT-42 add-user-auth

Then create an implementation plan:

/mx:plan

The plan analyzes your codebase and produces a step-by-step implementation guide.

4. Implement

Section titled “4. Implement”
/mx:implement

This executes the plan step by step, running validation after each change and invoking specialized agents to review your code.

5. Validate

Section titled “5. Validate”
/mx:validate

Confirm that lint, type-checks, and tests still pass after your changes.

6. Commit

Section titled “6. Commit”
/mx:commit

Creates a conventional commit with auto-inferred scope, type, and ticket reference. No need to write the commit message yourself.

7. Open a PR

Section titled “7. Open a PR”
/mx:pr

Creates a pull request with an auto-generated summary. Use /mx:pr --draft if it is not ready for review yet.

What’s next

Section titled “What’s next”