Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/affaan-m/ECC/llms.txt

Use this file to discover all available pages before exploring further.

Over time, AI harness configurations can drift: files may be edited manually, removed by tooling, or left stale after a profile change. ecc doctor performs a read-only audit comparing your currently-installed files against the install-state record written when you last ran ecc install. ecc repair then restores any drifted or missing files by re-applying from the original source manifest. Together they form the core of ECC’s installation lifecycle management.

​
ecc doctor

Reads every install-state file discoverable in the current home/project context and reports whether each ECC-managed file is present and unchanged. No files are written or deleted — ecc doctor is purely diagnostic.

​
Usage

ecc doctor [--target <harness>] [--json]

​
Flags

​
--target
string
Limit the diagnostic to a specific harness target. Repeatable — pass --target multiple times to check a subset of targets. When omitted, all discoverable install-state files in the current context are checked.
ecc doctor --target claude
ecc doctor --target cursor --target codex
​
--json
flag
Emit a machine-readable JSON report instead of the human-readable summary.

​
What doctor checks

For each install-state file found, doctor inspects every recorded file operation and classifies each managed file as one of:
  • ok — file is present and matches the ECC-managed content.
  • warning — file has been modified from the ECC-managed version (drift detected).
  • error — file is missing entirely from the target directory.

​
Output format

Doctor report:

- claude-global
  Status: ERROR
  Install-state: /Users/you/.claude/install-state/ecc-install-state.json
  - [error] file_missing: rules/ecc/core.md not found at /Users/you/.claude/rules/ecc/core.md
  - [warning] file_drifted: skills/ecc/tdd.md has been modified

- cursor-project
  Status: OK
  Install-state: .cursor/install-state/ecc-install-state.json
  Issues: none

Summary: checked=2, ok=1, warnings=1, errors=1

​
Exit codes

CodeMeaning
0All checked targets are healthy
1One or more warnings or errors were found
ecc doctor does not modify any files. It is safe to run at any time, including in read-only CI environments.

​
ecc repair

Rebuilds ECC-managed files recorded in install-state by re-applying file operations from the original source manifest. repair is the corrective action to run after doctor reports issues.

​
Usage

ecc repair [--target <harness>] [--dry-run] [--json]

​
Flags

​
--target
string
Limit repair to a specific harness target. Repeatable. When omitted, all discoverable install-state files in the current context are repaired.
ecc repair --target claude
​
--dry-run
flag
Preview which files would be restored without writing anything. Prints the list of planned repairs and the total count for each target.
ecc repair --dry-run
​
--json
flag
Emit a machine-readable JSON repair result including planned or applied paths and the summary counts.

​
Output format

Repair summary:

- claude-global
  Status: OK
  Install-state: /Users/you/.claude/install-state/ecc-install-state.json
  Repaired paths: 2

Summary: checked=1, repaired=2, errors=0
With --dry-run: 
Repair summary:

- claude-global
  Status: OK
  Install-state: /Users/you/.claude/install-state/ecc-install-state.json
  Planned repairs: 2

Summary: checked=1, planned=2, errors=0

​
Exit codes

CodeMeaning
0All repairs completed without errors
1One or more targets encountered an error during repair
ecc repair overwrites the current content of drifted files with the ECC-managed version. If you intentionally modified a managed file, use --dry-run first to review which files would be overwritten.

​
ecc auto-update

Pulls the latest ECC changes from the source and reinstalls all managed targets using their original install-state request. Designed for unattended use in CI and developer setup scripts.

​
Usage

ecc auto-update [--target <harness>] [--repo-root <path>] [--dry-run] [--json]

​
How it works

  1. Reads the install-state files for the current context.
  2. Derives the ECC repo root from the recorded sourcePath entries.
  3. Runs git pull (or equivalent) in that repo root to fetch the latest content.
  4. Replays the original install request for each managed target with the updated source.

​
Flags

​
--target
string
Limit auto-update to a specific harness target. Repeatable.
​
--repo-root
string
Explicitly provide the ECC repo root path instead of deriving it from the install-state sourcePath entries.
​
--dry-run
flag
Preview which targets would be updated and what operations would be replayed without making any changes.
​
--json
flag
Emit a machine-readable JSON result.

​
Examples

# Preview what would be updated
ecc auto-update --dry-run

# Update all managed targets
ecc auto-update

# Update only the Claude global target
ecc auto-update --target claude
ecc auto-update is safe to run frequently — it is idempotent and only touches files that are part of the recorded install state.

​
ecc list-installed

Shows all ECC-managed targets discovered in the current home/project context by reading their install-state files, without performing any health checks.

​
Usage

ecc list-installed [--target <harness>] [--json]

​
Flags

​
--target
string
Limit listing to a specific harness target. Repeatable.
​
--json
flag
Emit a machine-readable JSON array of install-state records.

​
Output format

Installed ECC targets:

- claude-global
  Root: /Users/you/.claude
  Installed: 2025-01-15T10:22:00.000Z
  Profile: developer
  Modules: tdd, hooks-core, mcp-patterns, security, research-apis
  Legacy languages: (none)
  Source version: 2.0.0

- cursor-project
  Root: .cursor
  Installed: 2025-01-14T09:00:00.000Z
  Profile: core
  Modules: hooks-core, mcp-patterns
  Legacy languages: (none)
  Source version: 2.0.0

​
Diagnostic-Repair Workflow

1

Check current health

Run ecc doctor to get a full picture of all install-state health across your context. Review the per-target issue list.
ecc doctor
2

Preview what repair would do

Use ecc repair --dry-run to see exactly which files would be restored before committing to any changes.
ecc repair --dry-run
3

Apply the repair

Run ecc repair (optionally scoped to a specific --target) to restore all drifted and missing files.
ecc repair
# or, for a single target:
ecc repair --target claude
4

Verify the fix

Re-run ecc doctor to confirm the summary shows ok=N, warnings=0, errors=0 for all targets.
ecc doctor

​
CI Integration

Use ecc doctor with --json and the implicit non-zero exit code to gate CI pipelines on install health: 
# .github/workflows/ecc-health.yml
- name: Check ECC installation health
  run: ecc doctor --json
  # exits 1 if any warnings or errors are found
To auto-remediate in CI: 
- name: Repair ECC installation drift
  run: ecc repair --json

Build docs developers (and LLMs) love

Get started for freeTalk to us