Installer orchestration
ECC installation orchestration turns a user request into a target-specific plan, applies the plan to a home or project environment, and records enough state for later inspection, repair, and removal. It supports a guided multi-harness path and a planned profile or module path. It does not install or authenticate provider command-line tools.
Parent: Installation and distribution
Related: Installation manifests and schemas
Installation entrypoints
The installation entrypoints give users one shell-friendly interface and one JavaScript runtime. The shell wrappers prepare the runtime, while the JavaScript commands select the install mode and target.
Shell and PowerShell entrypoints
The repository-root install.sh is the Unix and Git Bash entrypoint. It resolves symlinked paths, installs Node dependencies when run from a clone, and delegates to scripts/install-apply.js. On MSYS2 it converts the script path before starting Node. The Windows-native install.ps1 performs the same delegation with PowerShell path handling and the same dependency bootstrap.
These wrappers are compatibility surfaces. The install behavior belongs to the JavaScript runtime, so changes to target selection or state handling normally belong below the wrappers rather than in shell code.
References: install.sh• L1-32 install.ps1• L1-53
JavaScript command routing
The primary JavaScript runtime is scripts/install-apply.js. It accepts legacy language arguments, manifest selections, locale selections, configuration files, dry-run output, and JSON output. It builds a plan first, then applies the plan and projects the resulting state into the health store. The ecc command in scripts/ecc.js routes ecc install and install-like arguments to this runtime. It also keeps ecc-install as a compatibility name.
ecc setup is a related but separate entrypoint for the Claude native plugin. It manages Claude plugin scope and hook choices. It is not the general content installer used by install.sh.
References: scripts/install-apply.js• L24-79 scripts/install-apply.js• L157-216 scripts/ecc.js• L9-20 scripts/ecc.js• L146-165 scripts/setup.js• L28-59
Installation modes
The installer has two current user-facing paths and one compatibility path. Each path produces a plan before it changes a target, but the source of the selection differs.
The installation flow turns a command or guided choice into a normalized request. It then resolves supported content and target operations before it writes files or records ownership.
flowchart LR
A[Shell or JavaScript entrypoint] --> B[Normalized request]
B --> C[Resolved install plan]
C --> D{Dry run?}
D -->|Yes| E[Plan output]
D -->|No| F[Apply target operations]
F --> G[Canonical install-state]
G --> H[Derived health projection]
Guided installation
ecc install --guided collects harness and policy choices, shows the resulting plan, and asks for confirmation before applying it. The guided path supports Claude, Codex, and Kimi. Claude uses a native plugin with user, project, or local scope and a hook preference. Codex uses its native plugin and its own hook trust flow. Kimi receives a managed project install under .kimi-code; ECC does not configure its hooks, model, provider, or authentication settings.
The guided planner prepares each selected harness before applying it. It applies harnesses in order. If one fails, completed harnesses remain completed and the result gives the user the remaining harnesses and their choices for a retry. Non-interactive runs must name their harnesses and policy choices. JSON mutation requests also require --yes. Dry runs stop after planning.
Advanced adapters remain available through explicit target installation. They are not part of the guided three-harness choice.
References: scripts/install-guided.js• L24-55 scripts/install-guided.js• L158-205 scripts/install-guided.js• L248-331 scripts/…/multi-harness-setup.js• L387-441
Planned installation
The planned path selects content by profile, module, component, skill, or an ecc-install.json request. scripts/…/plan.js turns the resolved manifest selection into target operations. scripts/install-plan.js resolves and displays the plan without changing files, while scripts/install-apply.js uses the same selection process and then applies the plan.
Profiles provide named bundles such as minimal, core, developer, security, research, and full. Components provide smaller user-facing choices. Module dependencies are resolved before target filtering. A target can skip content that it does not support, while an excluded dependency can make a dependent module unavailable. OpenCode has a target-specific default profile and keeps the hook runtime opt-in.
The request normalizer combines command-line and config intent into one request and prevents ambiguous combinations. Legacy language arguments cannot be combined with manifest selections. Hook consent is also part of the request, so declining hooks cannot be paired with an explicit hook-runtime module. A config file can be found in the current project by default or loaded from an explicit path. Locale content is limited to Claude home and Claude project targets.
References: scripts/…/plan.js• L258-360 scripts/install-plan.js• L18-45 scripts/…/install-manifests.js• L545-738 scripts/…/request.js• L101-171 scripts/…/runtime.js• L11-61 manifests/install-profiles.json• L2-103
Legacy compatibility installation
The positional form, such as install.sh typescript, preserves the older language-based user experience. The installer normalizes language aliases, maps them to rule namespaces and shared modules, and adds the baseline content for the selected target. This path is called legacy compatibility because it uses the current plan and state system while preserving the old request shape.
Bare language syntax is limited to the legacy target set: Claude home, Claude project, Cursor, and Antigravity. Other supported targets require a profile, module, component, or skill selection. This distinction prevents a supported target from being mistaken for a supported legacy-language destination.
References: scripts/…/request.js• L6 scripts/…/install-manifests.js• L42-154 scripts/…/install-manifests.js• L488-542 scripts/…/install-executor.js• L42-57 scripts/…/install-executor.js• L522-557
Target application
After request normalization, the installer resolves content into file operations for one target. Target adapters keep the selection model shared while allowing each coding harness to receive the shape it expects.
Target adapters
An install target is a named home or project destination. The adapter for that target defines its root, install-state location, supported modules, and path mapping. The supported set includes Claude, Cursor, Antigravity, Codex, Gemini, OpenCode, CodeBuddy, JoyCode, Qwen, Zed, Hermes, OpenClaw, Kimi, and Adal.
The same source content can therefore have different destinations. Claude namespaces managed rules under rules/ecc; project adapters write below the current project; some targets flatten rules or sync children into a native root. Target adapters can also adapt content to a harness contract. For example, Copilot agent copies keep only the metadata that Copilot uses and do not carry Claude-only fields. Platform-owned source paths are filtered so one harness does not receive another harness's native configuration.
References: scripts/…/install-manifests.js• L7-8 scripts/…/registry.js• L1-31 scripts/…/helpers.js• L5-18 scripts/…/helpers.js• L256-349 scripts/…/claude-home.js• L12-89 scripts/…/kimi-project.js• L47-108 scripts/…/plan.js• L99-123 scripts/…/copilot-agent.js• L20-65
Plan application
The plan contains operations such as managed file copies and JSON merges. Applying a plan creates the target directories, writes the selected content, resolves Claude hook paths, and records the result. Target-specific content changes are applied as part of the plan, while markdown links can be adjusted to the installed locations so installed documents keep working across path remapping.
The application boundary protects the target root. It rejects unsafe destinations and symlinked paths, avoids replacing unowned content in managed preflight flows, and treats JSON configuration as a merge rather than a whole-file replacement. Reinstall also reconciles stale managed files: when a selected module no longer provides a previously installed file, ECC removes its state record and deletes the file only if its content is unchanged. Modified or unverifiable files remain in place with a warning. The result includes warnings when a migration or derived state update needs review. A partial migration can first record bridge state so a later failure remains retryable and uninstall can remove only content owned by that attempt.
References: scripts/…/apply.js• L708-740 scripts/…/apply.js• L743-1081 scripts/…/contained-fs.js• L8-115 scripts/…/contained-fs.js• L128-196 scripts/…/stale-operations-reconciliation.js• L11-29 scripts/…/stale-operations-reconciliation.js• L60-125 scripts/…/multi-harness-setup.js• L294-358 scripts/…/install-executor.js• L751-933
Install-state recording
Each applied target has an install-state file inside its target root. The record identifies the target, the original request and hook decision, the modules selected or skipped, the source version, and the managed operations with content digests. Reinstall keeps ownership for earlier selected modules, then removes records for stale files after a successful reconciliation. The record is the ownership boundary for later commands: list-installed reads it, doctor checks it, repair uses it to restore content, and uninstall uses it to decide what it may remove.
The canonical record uses schema version ecc.install.v1. ECC also projects install state into a private SQLite state store under the user's Claude directory. That store is a derived view for health and status queries. A projection warning does not make a completed file install fail or replace the canonical JSON record.
References: scripts/…/install-state.js• L228-309 scripts/…/apply.js• L123-155 scripts/list-installed.js• L42-63 scripts/…/install-state-store-sync.js• L22-60 scripts/…/index.js• L184-194 scripts/…/index.js• L334-366
Package-manager selection
Package-manager setup controls how supported development commands are described and run. It is separate from target installation and does not choose which harness receives ECC content.
ECC supports npm, pnpm, Yarn, and Bun. Selection follows a clear order: CLAUDE_PACKAGE_MANAGER, project .claude/package-manager.json, the packageManager field in package.json, a project lock file, the global ~/…/package-manager.json preference, and finally npm. Engineers can inspect the choice with --detect, set a global or project preference, or list available managers.
The shell and PowerShell clone bootstrap still use npm install directly. A saved package-manager preference affects command selection after the runtime is available; it does not change that wrapper bootstrap step.
References: scripts/setup-package-manager.js• L25-57 scripts/setup-package-manager.js• L60-93 scripts/…/package-manager.js• L59-65 scripts/…/package-manager.js• L152-238 scripts/…/package-manager.js• L244-283
Uninstall behavior
Uninstall is state-driven. It discovers install-state files for the current home and project context, removes only operations recorded as managed, and then reconciles the derived state view.
Managed uninstall
ecc uninstall can target one or more adapters and supports a dry run. For a normal copy, ECC removes the file only when its recorded content still matches. Modified, missing, unverifiable, or symlinked content is retained rather than silently destroyed. A retained path keeps install-state in place and produces a partial result for review.
For merged JSON, uninstall removes ECC-owned values or restores recorded prior content when that information exists. It removes empty parent directories inside the trusted target root. A missing or invalid install-state produces an error instead of a broad directory delete.
References: scripts/uninstall.js• L13-22 scripts/uninstall.js• L121-185 scripts/…/install-lifecycle.js• L2053-2181 scripts/…/install-lifecycle.js• L786-967
Compatibility cleanup
The older Codex sync cleanup is opt-in through --legacy-codex-sync and cannot be combined with a target selection. Older standalone CodeBuddy and Trae installers use a local .ecc-manifest instead of the current install-state contract. Their uninstall scripts remove listed files, preserve user-added content, and require confirmation before removing an entire target directory when the manifest is absent.
Antigravity and OpenCode legacy layouts are also conservative. If provenance cannot be checked, ECC preserves the content and reports a partial result so an engineer can review it before removal. A normal install or repair can migrate verified legacy content to the current layout.
References: scripts/uninstall.js• L97-121 scripts/uninstall.js• L128-170 .codebuddy/uninstall.js• L149-191 .codebuddy/uninstall.js• L194-285 .trae/uninstall.sh• L75-111 scripts/…/install-lifecycle.js• L1313-1382 scripts/…/install-lifecycle.js• L2053-2085
Change checklist
When these files or sections are changed, remember to consider these:
- When a target is added or renamed, update the supported-target list, adapter registry, module target declarations, target help text, discovery, and uninstall selection together.
- When an operation destination or strategy changes, keep install-state recording, content digests, repair, drift checks, stale-operation reconciliation, and uninstall removal rules aligned.
- When a profile, component, or module ID changes, check config normalization, dependency resolution, target filtering, and the plan output contract.
- When guided harness choices change, keep the interactive prompts, non-interactive validation, sequential retry behavior, and native setup channels consistent.
- When package-manager precedence or config paths change, update detection, global and project setters, and the command descriptions as one contract.
- When a harness-specific content transform changes, keep the source metadata contract, transformed destination format, and target operation type aligned.
- When legacy manifest cleanup changes, preserve its path boundary and its rule for retaining user or modified files.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Node dependencies cannot be installed by the shell or PowerShell bootstrap | The JavaScript installer does not start | The wrappers stop on dependency failure and return the package-manager error |
| A requested module does not support the selected target | The plan skips that module or a dependent request | Manifest target checks and dependency resolution report skipped content before apply |
| A guided install loses its install-state ownership or the state changes after preflight | The managed write is refused to avoid replacing unowned content | Guided preflight fingerprints state and rechecks it before each write |
| A destination or parent path is outside the adapter root or uses an unsafe symlink | The operation fails without writing through the path | Trusted-root, contained-parent, and no-follow checks protect apply, repair, and uninstall |
A Copilot agent lacks valid name or description metadata | The target-specific agent copy is not created | The Copilot transform requires both fields and keeps only supported metadata |
| A managed file was edited after installation | Uninstall or stale-file reconciliation retains the file and returns a partial result or warning | Recorded content digests distinguish unchanged managed bytes from user changes |
| A selected module no longer plans a previously managed file | The stale state record is removed after apply and an unchanged copy is deleted | Reconciliation checks module selection, target containment, regular-file status, digest, and file identity |
| A JSON target is invalid or conflicts with unowned fields | The plan cannot safely merge configuration | JSON parsing and ownership conflict checks stop the operation |
| The SQLite projection cannot open or close | Files and canonical JSON can complete, but derived health data has a warning | Projection errors are reported as warnings and do not replace canonical state |
Key files
| File | Why to read it |
|---|---|
| install.sh | Unix and Git Bash entrypoint behavior and dependency bootstrap |
install.ps1 | Windows-native entrypoint behavior |
| scripts/ecc.js | Public command routing and compatibility handling |
| scripts/install-apply.js | Main JavaScript install runtime and output modes |
| scripts/install-guided.js | Guided choices, confirmation, dry run, and retry output |
| scripts/install-plan.js | Read-only plan inspection |
| scripts/…/request.js | Request normalization, hook consent, and mode selection |
| scripts/…/runtime.js | Mapping normalized requests to legacy and manifest planning paths |
| scripts/…/install-manifests.js | Profile, component, module, dependency, and target resolution |
| scripts/…/plan.js | Conversion of resolved content into file operations and state preview data |
| scripts/…/copilot-agent.js | Copilot agent metadata adaptation |
| scripts/…/install-executor.js | Target-specific operation planning and state preview creation |
| scripts/…/apply.js | File application, JSON merge, safety checks, state recording, and reconciliation |
| scripts/…/contained-fs.js | Trusted-root file access and safe removal primitives |
| scripts/…/stale-operations-reconciliation.js | Removal of obsolete managed files after a successful reinstall |
| scripts/…/install-state.js | Canonical install-state shape and validation |
| scripts/…/install-lifecycle.js | Installed-state discovery, repair, health checks, migration, and uninstall |
| scripts/setup.js | Separate Claude plugin scope and hook setup flow |
| scripts/…/package-manager.js | Package-manager detection and preference precedence |
| scripts/setup-package-manager.js | Package-manager setup commands |
| scripts/…/index.js | Derived SQLite state-store lifecycle |
| scripts/uninstall.js | Public uninstall command and legacy cleanup switch |