Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / installer-orchestration

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

TriggerConsequenceGuard
Node dependencies cannot be installed by the shell or PowerShell bootstrapThe JavaScript installer does not startThe wrappers stop on dependency failure and return the package-manager error
A requested module does not support the selected targetThe plan skips that module or a dependent requestManifest target checks and dependency resolution report skipped content before apply
A guided install loses its install-state ownership or the state changes after preflightThe managed write is refused to avoid replacing unowned contentGuided preflight fingerprints state and rechecks it before each write
A destination or parent path is outside the adapter root or uses an unsafe symlinkThe operation fails without writing through the pathTrusted-root, contained-parent, and no-follow checks protect apply, repair, and uninstall
A Copilot agent lacks valid name or description metadataThe target-specific agent copy is not createdThe Copilot transform requires both fields and keeps only supported metadata
A managed file was edited after installationUninstall or stale-file reconciliation retains the file and returns a partial result or warningRecorded content digests distinguish unchanged managed bytes from user changes
A selected module no longer plans a previously managed fileThe stale state record is removed after apply and an unchanged copy is deletedReconciliation checks module selection, target containment, regular-file status, digest, and file identity
A JSON target is invalid or conflicts with unowned fieldsThe plan cannot safely merge configurationJSON parsing and ownership conflict checks stop the operation
The SQLite projection cannot open or closeFiles and canonical JSON can complete, but derived health data has a warningProjection errors are reported as warnings and do not replace canonical state

Key files

FileWhy to read it
install.shUnix and Git Bash entrypoint behavior and dependency bootstrap
install.ps1Windows-native entrypoint behavior
scripts/ecc.jsPublic command routing and compatibility handling
scripts/install-apply.jsMain JavaScript install runtime and output modes
scripts/install-guided.jsGuided choices, confirmation, dry run, and retry output
scripts/install-plan.jsRead-only plan inspection
scripts/…/request.jsRequest normalization, hook consent, and mode selection
scripts/…/runtime.jsMapping normalized requests to legacy and manifest planning paths
scripts/…/install-manifests.jsProfile, component, module, dependency, and target resolution
scripts/…/plan.jsConversion of resolved content into file operations and state preview data
scripts/…/copilot-agent.jsCopilot agent metadata adaptation
scripts/…/install-executor.jsTarget-specific operation planning and state preview creation
scripts/…/apply.jsFile application, JSON merge, safety checks, state recording, and reconciliation
scripts/…/contained-fs.jsTrusted-root file access and safe removal primitives
scripts/…/stale-operations-reconciliation.jsRemoval of obsolete managed files after a successful reinstall
scripts/…/install-state.jsCanonical install-state shape and validation
scripts/…/install-lifecycle.jsInstalled-state discovery, repair, health checks, migration, and uninstall
scripts/setup.jsSeparate Claude plugin scope and hook setup flow
scripts/…/package-manager.jsPackage-manager detection and preference precedence
scripts/setup-package-manager.jsPackage-manager setup commands
scripts/…/index.jsDerived SQLite state-store lifecycle
scripts/uninstall.jsPublic uninstall command and legacy cleanup switch