|
| 1 | +# OpenCode Integration |
| 2 | + |
| 3 | +OpenCode is a fully supported AI integration for mxcli. It gets deep support: a dedicated configuration directory, project-level context in `AGENTS.md`, skill files that teach the AI MDL patterns, slash commands for common operations, and Starlark lint rules. |
| 4 | + |
| 5 | +## Initializing a project |
| 6 | + |
| 7 | +Use the `--tool opencode` flag: |
| 8 | + |
| 9 | +```bash |
| 10 | +mxcli init --tool opencode /path/to/my-mendix-project |
| 11 | +``` |
| 12 | + |
| 13 | +To set up both OpenCode and Claude Code together: |
| 14 | + |
| 15 | +```bash |
| 16 | +mxcli init --tool opencode --tool claude /path/to/my-mendix-project |
| 17 | +``` |
| 18 | + |
| 19 | +## What gets created |
| 20 | + |
| 21 | +After running `mxcli init --tool opencode`, your project directory gains: |
| 22 | + |
| 23 | +``` |
| 24 | +my-mendix-project/ |
| 25 | +├── AGENTS.md # Universal AI assistant guide (OpenCode reads this) |
| 26 | +├── opencode.json # OpenCode configuration file |
| 27 | +├── .opencode/ |
| 28 | +│ ├── commands/ # Slash commands (/create-entity, etc.) |
| 29 | +│ └── skills/ # MDL pattern guides (OpenCode skill format) |
| 30 | +│ ├── write-microflows/ |
| 31 | +│ │ └── SKILL.md |
| 32 | +│ ├── create-page/ |
| 33 | +│ │ └── SKILL.md |
| 34 | +│ └── ... |
| 35 | +├── .claude/ |
| 36 | +│ └── lint-rules/ # Starlark lint rules (shared with mxcli lint) |
| 37 | +├── .ai-context/ |
| 38 | +│ ├── skills/ # Shared skill files (universal copy) |
| 39 | +│ └── examples/ # Example MDL scripts |
| 40 | +├── .devcontainer/ |
| 41 | +│ ├── devcontainer.json # Dev container configuration |
| 42 | +│ └── Dockerfile # Container image with mxcli, JDK, Docker |
| 43 | +├── mxcli # CLI binary (copied into project) |
| 44 | +└── app.mpr # Your Mendix project (already existed) |
| 45 | +``` |
| 46 | + |
| 47 | +### opencode.json |
| 48 | + |
| 49 | +The `opencode.json` file is OpenCode's primary configuration. It points to `AGENTS.md` for instructions and to the skill files in `.opencode/skills/`: |
| 50 | + |
| 51 | +```json |
| 52 | +{ |
| 53 | + "instructions": ["AGENTS.md", ".ai-context/skills/*.md"], |
| 54 | + "model": "anthropic/claude-sonnet-4-5" |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +### Skills |
| 59 | + |
| 60 | +Skills live in `.opencode/skills/<name>/SKILL.md` and use YAML frontmatter that OpenCode understands: |
| 61 | + |
| 62 | +```markdown |
| 63 | +--- |
| 64 | +name: write-microflows |
| 65 | +description: MDL syntax and patterns for creating microflows |
| 66 | +compatibility: opencode |
| 67 | +--- |
| 68 | + |
| 69 | +# Writing Microflows |
| 70 | +... |
| 71 | +``` |
| 72 | + |
| 73 | +Each skill covers a specific area: microflow syntax, page patterns, security setup, and so on. OpenCode reads the relevant skill before generating MDL, which significantly improves output quality. |
| 74 | + |
| 75 | +### Commands |
| 76 | + |
| 77 | +The `.opencode/commands/` directory contains slash commands available inside OpenCode. These mirror the Claude Code commands: `/create-entity`, `/create-microflow`, `/create-page`, `/lint`, and others. |
| 78 | + |
| 79 | +### Lint rules |
| 80 | + |
| 81 | +Lint rules live in `.claude/lint-rules/` regardless of which tool is selected — this is where `mxcli lint` looks for custom Starlark rules. OpenCode init writes the rules there so `mxcli lint` works the same way for both tool choices. |
| 82 | + |
| 83 | +## Setting up the dev container |
| 84 | + |
| 85 | +The dev container setup is identical to the Claude Code workflow. Open your project folder in VS Code, click **"Reopen in Container"** when prompted, and wait for the container to build. |
| 86 | + |
| 87 | +### What's installed in the container |
| 88 | + |
| 89 | +| Component | Purpose | |
| 90 | +|-----------|---------| |
| 91 | +| **mxcli** | Mendix CLI (copied into project root) | |
| 92 | +| **MxBuild / mx** | Mendix project validation and building | |
| 93 | +| **JDK 21** (Adoptium) | Required by MxBuild | |
| 94 | +| **Docker-in-Docker** | Running Mendix apps locally with `mxcli docker` | |
| 95 | +| **Node.js** | Playwright testing support | |
| 96 | +| **PostgreSQL client** | Database connectivity | |
| 97 | + |
| 98 | +## Starting OpenCode |
| 99 | + |
| 100 | +With the dev container running, open a terminal in VS Code and start OpenCode: |
| 101 | + |
| 102 | +```bash |
| 103 | +opencode |
| 104 | +``` |
| 105 | + |
| 106 | +OpenCode now has access to your project files, the mxcli binary, the skill files in `.opencode/skills/`, and the commands in `.opencode/commands/`. |
| 107 | + |
| 108 | +## How OpenCode works with your project |
| 109 | + |
| 110 | +The workflow mirrors Claude Code exactly: |
| 111 | + |
| 112 | +### 1. Explore |
| 113 | + |
| 114 | +OpenCode uses mxcli commands to understand the project before making changes: |
| 115 | + |
| 116 | +```sql |
| 117 | +-- What modules exist? |
| 118 | +SHOW MODULES; |
| 119 | + |
| 120 | +-- What entities are in this module? |
| 121 | +SHOW ENTITIES IN Sales; |
| 122 | + |
| 123 | +-- What does this entity look like? |
| 124 | +DESCRIBE ENTITY Sales.Customer; |
| 125 | + |
| 126 | +-- What microflows exist? |
| 127 | +SHOW MICROFLOWS IN Sales; |
| 128 | + |
| 129 | +-- Search for something specific |
| 130 | +SEARCH 'validation'; |
| 131 | +``` |
| 132 | + |
| 133 | +### 2. Read the relevant skill |
| 134 | + |
| 135 | +Before writing MDL, OpenCode reads the appropriate skill file from `.opencode/skills/`. If you ask for a microflow, it reads the `write-microflows` skill. If you ask for a page, it reads `create-page`. |
| 136 | + |
| 137 | +### 3. Write MDL |
| 138 | + |
| 139 | +OpenCode generates an MDL script based on the project context and skill guidance: |
| 140 | + |
| 141 | +```sql |
| 142 | +/** Customer master data */ |
| 143 | +@Position(100, 100) |
| 144 | +CREATE PERSISTENT ENTITY Sales.Customer ( |
| 145 | + Name: String(200) NOT NULL, |
| 146 | + Email: String(200) NOT NULL, |
| 147 | + Phone: String(50), |
| 148 | + IsActive: Boolean DEFAULT true |
| 149 | +); |
| 150 | +``` |
| 151 | + |
| 152 | +### 4. Validate |
| 153 | + |
| 154 | +```bash |
| 155 | +./mxcli check script.mdl |
| 156 | +./mxcli check script.mdl -p app.mpr --references |
| 157 | +``` |
| 158 | + |
| 159 | +### 5. Execute |
| 160 | + |
| 161 | +```bash |
| 162 | +./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'" |
| 163 | +``` |
| 164 | + |
| 165 | +### 6. Verify |
| 166 | + |
| 167 | +```bash |
| 168 | +./mxcli docker check -p app.mpr |
| 169 | +``` |
| 170 | + |
| 171 | +## Adding OpenCode to an existing project |
| 172 | + |
| 173 | +If you already ran `mxcli init` for another tool and want to add OpenCode support: |
| 174 | + |
| 175 | +```bash |
| 176 | +mxcli add-tool opencode |
| 177 | +``` |
| 178 | + |
| 179 | +This creates `.opencode/`, `opencode.json`, and the lint rules without touching any existing configuration. |
| 180 | + |
| 181 | +## Tips for working with OpenCode |
| 182 | + |
| 183 | +- **Be specific about module names.** Say "Create a Customer entity in the Sales module" rather than just "Create a Customer entity." |
| 184 | +- **Mention existing elements.** If you want an association to an existing entity, name it: "Link Order to the existing Sales.Customer entity." |
| 185 | +- **Let the AI explore first.** OpenCode will run SHOW and DESCRIBE commands to understand what's already in the project. This leads to better results. |
| 186 | +- **Review in Studio Pro.** After changes are applied, open the project in Studio Pro to verify the result visually. |
| 187 | +- **Use `mxcli docker check`** to catch issues that `mxcli check` alone might miss. |
| 188 | + |
| 189 | +## Next steps |
| 190 | + |
| 191 | +To understand what the skill files contain and how they guide AI behavior, see [Skills and CLAUDE.md](skills.md). For other supported tools, see [Cursor / Continue.dev / Windsurf](other-ai-tools.md). |
0 commit comments