Adopt Elide in an existing project

elide adopt launches an AI coding harness with a migration prompt tailored to the project in your current directory. It is designed primarily for Java and Kotlin projects, especially Spring Boot applications, but tells the harness to preserve and support any other languages it finds.

The harness edits the project; elide adopt does not rewrite files itself. Review the resulting diff and validation output as you would for any other AI-assisted change.

What works today

Adoption is aimed at JVM projects with a conventional Maven or Gradle layout. The production prompt has been exercised end to end against these project shapes:

Each evaluation starts from a fresh project, asks the harness to create an Elide build, and checks elide install, elide build, elide test, application startup or output, and the authoritative original build. These cases establish useful coverage, not a guarantee that every project with the same tools will migrate without review.

The Codex path has completed the full evaluation suite. Claude and OMP adapters are available, but have not yet completed the same benchmark suite. Multi-module projects, Android projects, and less conventional generated-source or annotation-processing setups are not yet represented by these cases; treat migrations with those characteristics as exploratory.

Before you start

Install and authenticate at least one supported harness, then run the command from the root of the project you want to migrate:

Commit or otherwise back up the existing project first. This gives you a clean diff to review and an easy way to discard an unsuccessful migration.

Build the project successfully with its existing build tool before adoption when possible. A known-good Maven or Gradle result gives both the harness and the reviewer a concrete baseline.

Interactive adoption

From the project root, run:

elide adopt

Elide asks three questions before it starts the harness.

Choose a build strategy

• Elide build asks the harness to create or update elide.pkl, adopt elide build, and validate with Elide’s build and test commands. The existing Maven or Gradle configuration stays in place until the Elide build has been validated.
• Existing build keeps Maven or Gradle as the primary build. The harness can adopt useful Elide runtime and toolchain commands, but it will not create elide.pkl solely to switch builds.

For a Spring Boot application that you want to build with Elide, choose Elide build. The prompt specifically calls out the application entry point, Spring dependencies and plugins, resources, tests, and packaging behavior so the harness checks each of them during migration.

For JVM migrations, the prompt also supplies verified source-set, Java compatibility, resource-map, and JAR schema forms. It asks the harness to keep effective-model and validation output compact and to repeat plain install, build, test, run-readiness, and the original build after the final manifest edit. Harness-specific guidance is composed ahead of any --prompt-append fragments; Codex receives a focused fallback when its patch helper is unavailable.

Choose a harness

Choose codex, claude, or omp. Elide passes the absolute project directory and a rendered migration prompt to the selected command. By default, Elide shows an animated adoption status while capturing the harness output in a durable temporary log. It prints the log path before migration starts so you can inspect the full transcript during or after the run. Pass --log to stream the harness output to the terminal as well. Manual approval always uses live output so you can respond to the harness.

The harness may inspect files, edit the project, download dependencies, and execute builds or the application according to its own permissions. Elide reports success only when the harness process exits successfully; it does not independently certify the resulting migration.

You can append additional Markdown guidance without replacing Elide’s base migration prompt:

$ elide adopt --prompt-append ./adoption-guidance.md

Repeat --prompt-append to compose multiple fragments in command-line order. This is useful when testing project- or harness-specific guidance while retaining the standard migration instructions.

Choose an approval mode

yolo gives the selected harness broad access to execute commands and change files. Do not use it in a project that contains secrets or credentials, or on a machine where the harness can reach resources you do not want it to modify.

Cancel any question to exit without launching a harness. Press Ctrl+C while the harness is running to terminate it; Elide cleans up the progress display, keeps the adoption log, and exits with status 130.

Run without questions

Automation and repeatable migration experiments can specify every choice explicitly:

elide adopt \
  --build elide \
  --harness codex \
  --approval auto-approve \
  --non-interactive

--non-interactive runs the harness in its batch or print mode and requires --build, --harness, and --approval. Manual approval is not available in this mode because there is no interactive approval loop. Use either auto-approve or yolo.

Without --non-interactive, you can still preselect one or more answers and let Elide ask for the rest:

elide adopt --build elide --harness claude

Validate the migration

The prompt asks the harness to validate its work, but you should run the relevant commands again after it finishes. Start by inspecting the complete change and checking that dependency versions, source and resource directories, the application entry point, test configuration, and packaging match the original build. For a project migrated to elide build, then run:

elide install
elide build
elide test

Also run the original Maven or Gradle build while its configuration remains in the repository. Comparing both paths catches missing resources, test configuration, annotation processors, and packaging differences before Elide becomes the primary build.

If adoption fails or produces an incomplete migration, use the printed log path to review the harness transcript. Keep the original build files in place, revert the attempted changes as needed, and rerun with more specific guidance in a --prompt-append file.

See Elide Projects, Build Tasks, and the elide.pkl Reference for the configuration the harness creates.

Evaluate adoption prompts

Contributors can run the digest-pinned Spring Petclinic evaluation without adding it to normal test targets or CI:

$ tools/scripts/adopt-spring-petclinic.sh --harness codex --variant combined --trials 1 --keep

The Rust evaluation runner supports repeated prompt variants across Codex, Claude, and OMP. It records wall-clock time, structured token usage and cost when available, source diffs, command logs, and a deterministic quality score covering manifest translation and the install, build, test, run, and original-build checks. Use --matrix to execute the complete randomized experiment.

Before running agents, contributors can calibrate the rubric by using adopt-eval reference to score an existing known-good conversion with the same criteria and validation commands. The control variant then measures the production prompt without appended harness or treatment advice.

Harness trials should run in the evaluator’s pinned OCI image. Baseline, adoption, and validation commands use the same image and a private dependency home for that trial, preventing host caches and tool versions from changing the score. The harness sees only the disposable project, private trial home, selected Elide distribution, harness executable, and minimal read-only authentication, so known-good conversions and previous reports cannot leak into a control. Fresh trial workspaces are also created outside the Elide source checkout so project discovery cannot inherit the checkout’s own elide.pkl during validation.

Results remain under .dev/reports/adopt-eval/. See tools/adopt-eval/README.md in the source tree for case, prompt-layer, external-adapter, pricing, report, and offline rescoring formats.