ilo: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What ilo is

ilo is a small CLI that manages reproducible build environments by wrapping a container runtime (Podman, nerdctl, or Docker). ilo shell opens an (interactive) shell inside a container built from your project's image or Containerfile; ilo compose does the same backed by a compose file, and ilo devcontainer / ilo devfile build on those by reading a devcontainer.json or devfile.yaml and injecting its lifecycle commands. It is a single-binary tool (picocli + GraalVM native image), written in Java 25.

This repository is the source of ilo itself.

Build & test

.breto.edn installs GraalVM 25, Maven and Hugo; inside breto env:

breto run website   # build the docs/ site
breto run serve     # hugo dev server for docs/ at http://localhost:1313

The Maven commands:

mvn verify                          # full verification, native build skipped
mvn verify -Dtest=ShellRuntimeTest  # one test class
mvn verify --define skipNativeBuild=false   # include the native image

mvn verify is the canonical gate — it runs JUnit 5 tests, the ArchUnit architecture tests, and JaCoCo coverage. The coverage gate is a 0.75 bundle instruction ratio plus CLASS MISSEDCOUNT = 0 (every class must be touched): the ratio is below 1.0 on purpose because OS-gated code (@EnabledOnOs(WINDOWS) PowerShell paths, @EnabledOnOs(LINUX/MAC) expansion) is uncovered on whichever single OS the build runs on, so the per-class MISSEDCOUNT = 0 rule plus PIT is what actually guards test quality. PIT mutation testing (65% threshold, currently ~87%) runs in a dedicated CI job (mutation in verify.yml), not in mvn verify; run it locally with mvn test-compile org.pitest:pitest-maven:mutationCoverage.

Do not add a .ilo.rc / .ilo/ilo.rc to this repo: ilo auto-loads those as argument files on every invocation in this directory, which would inject unwanted args into every ilo run here.