Session & Discovery

These commands help you start a session, check project health, and discover what agents are available. Run them at the beginning of a session or whenever you need to re-orient.

/mx:prime

Prime agent with codebase context — reads key files, runs checks

/mx:prime

Warms up Claude by reading project configuration files (CLAUDE.md, package.json, tsconfig.json, and other key files) and running initial quality checks (lint, type-check, tests). After priming, Claude has a solid understanding of your project’s structure, conventions, and current state.

When to use it:

• At the start of every new session
• After pulling changes from a remote branch
• After switching branches
• When Claude seems to have lost context about your project

/mx:status

Show project status and available tools

/mx:status

Detects and displays available tools, configured settings, and project readiness for automated workflows. It scans for configuration files (like CLAUDE.md, package.json, Makefile) and checks whether lint, type-check, and test commands are available.

When to use it:

• At the start of a session, before running /mx:prime, to quickly see what is available
• To verify that your project is set up correctly for mx-workflow commands
• When you want to know what quality checks will run during /mx:validate

/mx:context-prime

Analyze a directory and create local context notes

/mx:context-prime src/auth
/mx:context-prime src/auth --learn
/mx:context-prime . --recursive

Reads the target directory’s key files, traces inbound/outbound dependencies, and writes a .claude/context.local.md file capturing non-obvious behavioral knowledge — hidden coupling, framework quirks, gotchas, and constraints that aren’t evident from code alone.

Context files are git-excluded and locally maintained. They act as a reference sheet that Claude reads before modifying code in that area, so it understands how things are tied together.

What it captures:

• Non-obvious consumers — who breaks if you change this module?
• Framework-specific constraints and bridge patterns
• State management gotchas (initialization ordering, shared state side effects)
• Fragile files or patterns with hidden dependencies
• Concrete verify commands (test, lint, build) specific to the module
• Things that broke unexpectedly and why

What it does NOT capture:

• Information obvious from imports, types, or file names
• Restatements of what the code does
• Gotchas already enforced by tooling (lint rules, TypeScript strict mode, pre-commit hooks, CI checks) — these are automatically filtered out
• TODO items or feature requests

Rules:

• Each context file stays under 40 lines — concise and high-signal only
• Time-sensitive entries get a date prefix: [2026-03] Migration in progress...
• If a context file already exists, it updates rather than overwrites
• Automatically ensures .claude/*.local* is git-excluded
• After writing, checks root CLAUDE.md for overlapping content and suggests pruning

--recursive flag — prime an entire project:

Use --recursive to discover and prime all significant directories in one pass. Instead of scanning immediate children, it finds module boundaries across the full tree by looking for index files and config files (package.json, Cargo.toml, go.mod, pyproject.toml). Each candidate is scored based on source file count, inbound imports, and gotcha signals — only directories scoring ≥ 5 get primed.

• Runs two project-wide Greps (not per-directory) for scalable scoring
• Caps at 20 directories per run — defers the rest with a note to run again
• Skips directories that already have context files
• Shows a scored plan and asks for confirmation before priming
• Each directory gets the full-quality analysis (up to 8 key files, dependency tracing, enforcement audit, 40-line context file)

--learn flag — retrospective mode:

Use --learn at the end of a session to record what surprised you. Instead of running static analysis, it prompts you for session learnings and merges them into the existing context file under the appropriate section. Learned entries are prefixed with [YYYY-MM] for traceability. If no context file exists yet, the full prime runs first.

When to use it:

• Before diving into unfamiliar code
• After getting burned by a hidden dependency you want to remember
• At the end of a session with --learn to capture what surprised you
• When onboarding into a new area of the codebase
• After a long time away from a module
• With --recursive when priming an entire project or large subtree for the first time

/mx:context-clean

Remove local context files

/mx:context-clean src/auth        # remove context for one directory
/mx:context-clean --all           # remove all context files in the project
/mx:context-clean                 # remove context in current directory

Finds and removes .claude/context.local.md files created by /mx:context-prime. Shows a preview of what will be removed and asks for confirmation before deleting. Also cleans up empty .claude/ directories left behind.

When to use it:

• When context files have gone stale and you want a fresh start
• When leaving a project and cleaning up local artifacts
• To remove context for a specific module that’s been refactored

/mx:agents

List available agents and their purposes

/mx:agents

Scans the agents/ directory and displays a formatted table of all available agents, their purposes, and which commands reference them. This gives you a quick overview of the specialized reviewers and analyzers that run automatically during commands like /mx:implement.

When to use it:

• When you want to know which agents are available for code review and analysis
• To understand what automated checks run during /mx:implement
• When exploring the plugin’s capabilities for the first time