Skip to main content

Quick Start

Get dmx running in a project in under 10 minutes.

Prerequisites​

  • Python 3.11 or later
  • uv installed (provides uvx) — dmx runs via uvx, so there's nothing to install globally
  • An agentic IDE: Cursor, Claude Code, or any MCP-compatible IDE
  • A Git repository

Step 1: Connect your IDE​

dmx runs as an MCP server. You need to tell your IDE where to find it.

Cursor: add to ~/.cursor/mcp.json (or your project's .cursor/mcp.json):

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
    }
  }
}

Claude Code: add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
    }
  }
}

Restart your IDE after saving. See MCP Setup for other IDEs and advanced options.

Step 2: Initialise your project​

In your IDE, run:

/dmx/init

This command walks you through a one-time setup:

  1. Ticketing system: Jira, GitHub Issues, or none
  2. Branching strategy: integration branch, production branch
  3. Tech stack auto-detection: reads your pyproject.toml, package.json, or Cargo.toml
  4. Scaffolds .dmx/: creates the memory bank with your project context

The .dmx/ directory is committed to your repo. Every developer on your team gets the same project context automatically.

Step 3: Run your first Spec Loop​

Start it directly with a short description of the work:

/dmx/run-loop spec

Add rate limiting to the public inference endpoint.

The loop's one skill, create-ticket, uses that description to scaffold the ticket, branch, and spec.

dmx will:

  1. Create a ticket in your configured ticketing system (or generate a local ID)
  2. Create a branch and check it out
  3. Scaffold a spec.md pre-filled with your project context, including a Q&A section
  4. Pause for your review — this is the human gate

Answer the Q&A directly in spec.md, then resume the loop:

/dmx/loop-continue

This is what actually triggers the Spec Loop validator (check_spec_complete), which checks that:

  • spec.md exists and is non-empty
  • All Q&A questions have answers (not just "TBD")
  • The Technical Approach section is filled in
  • The Scope section is defined

If all checks pass, dmx automatically chains to the Plan Loop.

Step 4: Approve the plan​

The Plan Loop starts automatically as soon as the Spec Loop succeeds. It runs the plan skill, which reads your spec.md and generates a phased tasks.md, then pauses for your review — the human gate.

Review tasks.md. When it looks right, resume:

/dmx/loop-continue

dmx validates tasks.md, then chains to the Dev Loop.

Step 5: Build​

The Dev Loop runs /dmx/implement-next-phase. It executes every task in the first unchecked phase of tasks.md, checks each one off as it completes, and then stops.

Review the output. When you're happy with the phase:

/dmx/loop-continue

The loop repeats until all phases are complete, runs the validators (test runner + spec adherence), then chains to the Validate Loop.

What just happened​

You just ran a complete AI SDLC workflow:

  • Every phase had a human gate. The AI stopped and waited for your approval before proceeding.
  • Validators ran automatically at the boundary between Build and Validate.
  • Job state was persisted in .dmx/. Close your IDE and resume tomorrow.

Next steps​