Quick start with Copilot: in VS Code, switch Copilot Chat to Agent mode and say:
set up MasterCompiler from https://github.com/kraudy/MasterCompiler
Copilot walks you through the rest. Details in docs/Copilot.md. Claude Code, Codex, Grok or OpenCode? Same idea from the terminal: docs/Agents.md. What changed in each release: CHANGELOG.md.
Agents, before anything else: read the setup guide at the latest release, not from master (its raw copy can be
cached for minutes and be out of date). Get tag_name from https://api.github.com/repos/kraudy/MasterCompiler/releases/latest
and read https://raw.githubusercontent.com/kraudy/MasterCompiler/<tag_name>/skills/mastercompiler-vscode/SKILL.md
(Copilot in VS Code) or .../skills/mastercompiler-setup/SKILL.md (Claude Code, Codex, Grok, OpenCode, any terminal agent);
download the jar and demo files at that same tag.
MasterCompiler is not Tool X, but for IBM i. It is an actual IBM I specific compilation tool built from first principles based on how the system handles object compilation. It is a completely different approach to answer the compilation sphinx.
YAML-based, sensible, open-source, modern, clean, and elegant approach to automate and streamline object compilation.
Setup guide for AI-assisted install:
skills/mastercompiler-vscode/SKILL.md, the step-by-step setup (Java, downloading MC, connecting it to Copilot as an MCP server with the Code for IBM i connection, a demo project, and what to confirm with the user before writing anything). For Claude Code, Codex, Grok or OpenCode:skills/mastercompiler-setup/SKILL.md. Agents: read it at the latest release tag, as said at the top.
MasterCompiler (MC) aims to give the whole IBM i community a standard way to describe the compilation flow of objects and allow easy integration with any DevOps pipeline to be run locally (just upload the JAR file) or remotely in a Docker container.
-
Download the jar and check it. Java 8 or newer runs it, on your PC or in PASE on the IBM i.
curl -LO https://github.com/kraudy/MasterCompiler/releases/latest/download/MasterCompiler.jar curl -LO https://github.com/kraudy/MasterCompiler/releases/latest/download/MasterCompiler.jar.sha256 sha256sum -c MasterCompiler.jar.sha256 # MasterCompiler.jar: OK -
Try it without an IBM i: in your project folder, scan the sources and write the build spec, targets in dependency order.
java -jar MasterCompiler.jar --scan . --generate-only -o build.yaml -
Connect: put
IBMI_HOSTNAMEandIBMI_USERNAMEin a.envin that folder (the password is asked in the terminal, or comes from--password-command/IBMI_PASSWORD_FILE), or add--code4i [--connection <name>]to every command below to reuse your Code for IBM i connection. Check it:java -jar MasterCompiler.jar --doctor. -
Build from your PC over SSH:
--remoteuploads MC and the project to your IBM i home folder and builds there.--dry-runprints the commands without running them (it already signs on); without it MC compiles into the current library, so give it your own development library.java -jar MasterCompiler.jar --remote --project . --curlib MYDEVLIB --dry-run java -jar MasterCompiler.jar --remote --project . --curlib MYDEVLIB
Already in PASE on the IBM i, with the sources in the IFS:
java -jar MasterCompiler.jar -f build.yaml --curlib MYDEVLIB.
Every release is on the releases page; the rest of this page explains the spec, the CLI and the agent setup. Each release also has a build provenance attestation (from v0.3.29). This checks the jar was built by this repository's release workflow:
gh attestation verify MasterCompiler.jar --repo kraudy/MasterCompiler --signer-workflow kraudy/MasterCompiler/.github/workflows/release.ymlgit clone git@github.com:kraudy/MasterCompiler.git./mvnw clean package(Maven wrapper: only a JDK 11 or newer is needed for the build and its tests, Maven downloads on first run; the jar it builds runs on Java 8+). The jar istarget/MasterCompiler.jar, the same name as the release's.
Build official TOBi recursive example on real hardware on any server with zero proprietary tools, zero licensing and zero cost as showcase.
Only for a person running the integration tests by hand: an agent in VS Code never creates this file
and never asks for the password. Create a .env file like this
IBMI_HOSTNAME=BIGIRON.COM
IBMI_USERNAME=BIGBOY
IBMI_PASSWORD=BIGMONEYThen, run the integration test to watch a thing of beauty. Note that this is the heavy test.
./mvnw clean verify -Pintegration-heavy
To compile an object, it must be defined as a target key of the form: mylib.hello.pgm.rpgle.
| Target key | Library | Object name | Object type | Source type |
|---|---|---|---|---|
| mylib.hello.pgm.rpgle | MYLIB | HELLO | PGM |
RPGLE |
The ObjectType and SourceType part of the Target key defines the compilation command to be executed.
| Object type | Source type | Compilation command |
|---|---|---|
PGM |
RPGLE |
CRTBNDRPG |
Besides the compilation itself, an object often requires other CL commands to be performed on the same job to set up the appropriate environment:
- Library list
- Files overrides
- Binding directories, etc.
MC calls this a compilation flow. Which can be easily defined in a Yaml spec file.
before: # optional | Global pre-compilation system commands
chglibl: # Set library list before targets compilation
libl: mylib1 mylib2
chgcurlib: # Set curlib before targets compilation
CURLIB: mylib1
CrtBndDir: # Lets create a bind dir
BNDDIR: BNDHELLO
targets: # Required | Ordered sequence of compilation targets. At least one target is required in the spec
# First create the modules. We can specify curlib as the target library. Convenient.
"curlib.modhello1.module.rpgle":
params: # Per-target compilation command params
SRCSTMF: /home/sources/hello2.modhello1.module.rpgle
*curlib.modhello2.module.rpgle:
params:
SRCSTMF: /home/sources/modhello2.module.rpgle
# Create service program with the modules
"CurLib.srvhello.srvpgm.bnd":
params:
SRCSTMF: /home/sources/srvhello.srvpgm.bnd
MODULE:
- modhello1
- modhello2
# Ile rpgle with binding dir
curlib.hello.pgm.rpgle:
before: # optional | Per-target pre-compilation system commands
AddBndDirE: # Add entry to bnd dir before target compiling
BndDir: BNDHELLO
Obj: SRVHELLO
params:
# Target's compilation params
SRCSTMF: /home/sources/HELLO.RPGLE
DFTACTGRP: no
ACTGRP: QILE
STGMDL: Snglvl # note how params names and values are flexible
OPTION: EVENTF
DBGVIEW: *source
REPLACE: yes
USRPRF: user
TGTRLS: V7R5M0
PRFDTA: nocol
after: # optional | Global post-compilation system commands
DltObj: # After all target are build, we delete the bind dir to have a clean slate
OBJ: BNDHELLO
OBJTYPE: BndDirAfter defining the spec, just call MasterCompiler with unix style parameters
java -jar MasterCompiler.jar -xv -f /home/user/clean_spec.yamlUnix base style Cli with short and long parameters.
Provide either a YAML spec {-f, --file} or a source root to scan {--scan}:
# Classic: hand-written YAML
java -jar MasterCompiler.jar -xv -f /home/user/clean_spec.yaml
# Scan sources → dependency order → generate YAML (and optionally build)
java -jar MasterCompiler.jar --scan /home/user/sources --generate-only -o build.yaml
java -jar MasterCompiler.jar --scan /home/user/sources -xvA project folder works too (--project <dir> uses its build.yaml, a TOBi Rules.mk or a scan; --spec <file> picks
another YAML spec in it), --target NAME builds only the matching target(s) of that name in one library (NAME.TYPE narrows it), without their dependencies or dependents, to repeat it after a one-line edit.
--call LIB/PGM runs a program in one job with the library list you give (--libl, --curlib) and prints its
parameters, its messages and the spooled output of that job (QPRINT; the job log when the user can read it).
Parameters are typed JSON in
--call-params: char, varchar (an RPG VARCHAR, e.g. a JSON text), packed, zoned and int.
java -jar MasterCompiler.jar --call MYLIB/MYPGM --libl "MYLIB QGPL" \
--call-params '[{"type":"varchar","length":2000,"value":"{\"id\":1}"},{"type":"int","bytes":4}]'
java -jar MasterCompiler.jar --sql "SELECT * FROM MYLIB.RESULTS" # read what the probe wroteA program that ends in error inside the call's server job (QZRCSRVS, owned by QUSER) does not have its stderr or
job-log line in the answer; the user's profile usually cannot read that job's log. A program that must report a
failure should write its details to a stream file (read with --fetch) or to QPRINT.
Over SSH, --remote --project <dir> --call LIB/PGM needs no host servers. The MCP call_program tool takes the same
parameters for programs the project builds in the current library, with a preview and a confirmation first; only the
command line --call also collects the job's spooled output. debug_program adds breakpoints and reads variables at
each stop. See the Cli doc.
Params are enum based, this allows for automatic param conflict resolution and validation in O(1) time along with instant validation at deserialization.
Scan writes the resolved params: map (defaults + inspection + overlay), not just SRCSTMF, plus a paste-ready CRT* comment above each target. You can also paste a full CRT* command as command: (Docker-style array or CL string); MC parses it back into params. params: still wins.
MC encourages git usage by automatically migrating source members to ifs stream files and stream files to source members for OPM objects.
Can be disabled with flag --no-migrate
If available, metadata is extracted from compiled objects to infer compilation params. The same inspection is applied when generating YAML if IBM i is connected.
Fully transparent and traceable flow of execution and changes.
Teams on Windows with VS Code and Code for IBM i can let Copilot's agent mode build and fix IBM i code with MC, reusing their Code for IBM i connection. Once per PC, give Copilot MC's setup skill (PowerShell, no Java needed):
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
New-Item -ItemType Directory -Force "$env:USERPROFILE\.copilot\skills\mastercompiler-vscode" | Out-Null
$tag = (Invoke-RestMethod -UseBasicParsing https://api.github.com/repos/kraudy/MasterCompiler/releases/latest).tag_name
Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/kraudy/MasterCompiler/$tag/skills/mastercompiler-vscode/SKILL.md" -OutFile "$env:USERPROFILE\.copilot\skills\mastercompiler-vscode\SKILL.md"Then, in any repository, ask Copilot in Agent mode: "set up MasterCompiler for this repository". It checks Java,
downloads MC (on Windows with its own Java, nothing else to install), previews the setup with you and writes
.vscode/mcp.json. See docs/Copilot.md.
The agent can also open a 5250 session (green screen) to run and check display file programs: MC signs on over TLS
(port 992), reads the screens, fills fields and presses keys, and writes each screen to .mc/screen.txt so you can
watch it in VS Code.
Skills for AI coding agents live in skills/:
mastercompiler: specs, scan,--dry-run,--jsonreports and the edit-compile-fix loop.mastercompiler-vscode: setting MC up as an MCP server for Copilot in VS Code.mastercompiler-setup: setting MC up as an MCP server for Claude Code, Codex, Grok Build and OpenCode.ibm-i-pase: working on an IBM i over SSH/PASE (CL, SQL, IFS, CCSID, EVFEVENT).
java -jar MasterCompiler.jar --install-skills [--agent copilot|claude|agents|all] copies them into your agent's skills
directory (~/.copilot/skills by default, ~/.claude/skills, ~/.agents/skills for Codex, Grok and OpenCode), or copy
a skill folder yourself. See docs/Agents.md.
Here is the rule: You want to reduce complexity, increase readability, and provide functionality.
Everything we do is a reflection of ourselves; even the world as we know it is a reflection of humanity... But that's a talk for another time.
