# Everything Claude Code (ECC) Administrator & Developer Guide

## 1. Architecture Overview

Everything Claude Code (ECC) is a polyglot configuration framework that layers skills, rules, hooks, agents, commands, and MCP server definitions onto Claude Code and compatible AI-assisted coding tools. It operates as a curated knowledge distribution system — not a runtime service — shipping structured markdown, JSON, and shell scripts that shape how AI agents behave during development sessions.

The project consists of two distinct systems: **ECC 1.x** (the npm-distributed configuration pack written in Node.js and Python) and **ECC 2.0** (a Rust-based TUI and session orchestration engine). Both share the same repository but serve different operational layers.

```text
┌─────────────────────────────────────────────────────────┐
│                    ECC Repository                       │
├──────────────────────┬──────────────────────────────────┤
│   ECC 1.x (npm)      │   ECC 2.0 (Rust TUI)            │
│                      │                                  │
│  skills/   (130+)    │  ecc2/src/main.rs   (CLI)        │
│  rules/    (13 langs)│  ecc2/src/session/  (management) │
│  hooks/    (hooks.json)│  ecc2/src/worktree/ (git)      │
│  commands/ (80+)     │  ecc2/src/tui/      (dashboard)  │
│  agents/   (19+)     │  ecc2/src/config/   (TOML)       │
│  manifests/(install) │  ecc2/src/observability/ (logs)  │
│  schemas/  (JSON)    │  ecc2/src/comms/    (messaging)  │
│  mcp-configs/        │  ecc2/src/notifications/ (alerts)│
│  scripts/  (tooling) │                                  │
├──────────────────────┼──────────────────────────────────┤
│  install.sh / .ps1   │  cargo build --release           │
│  scripts/ecc.js      │  ecc-tui binary                  │
│  ecc_dashboard.py    │                                  │
└──────────────────────┴──────────────────────────────────┘
```

### Component Inventory

| Component | Path | Role |
|---|---|---|
| Skills | `skills/` | 130+ domain knowledge modules (SKILL.md per directory) |
| Rules | `rules/` | Layered coding standards (common + 13 language-specific) |
| Hooks | `hooks/hooks.json` + `scripts/hooks/` | Event-driven automation (PreToolUse, PostToolUse, Stop, SessionStart, PreCompact) |
| Commands | `commands/` | 80+ slash command definitions (markdown) |
| Agents | `agents/` + `AGENTS.md` | 19+ specialized agent personas |
| MCP Configs | `mcp-configs/mcp-servers.json` | 20+ pre-configured MCP server definitions |
| Schemas | `schemas/` | JSON Schema validation for hooks, installs, skills, agents, commands |
| Manifests | `manifests/` | Install component and module definitions |
| Install System | `scripts/lib/install*.js` + `manifests/` | Profile-based, component-driven installer |
| ECC 2.0 TUI | `ecc2/` | Rust-based session management, worktree orchestration, merge queues |
| Python Dashboard | `ecc_dashboard.py` + `scripts/lib/ecc_dashboard_runtime.py` | TkInter GUI for browsing components |
| LLM Abstraction | `src/llm/` | Python LLM provider abstraction layer |
| CI Scripts | `scripts/ci/` | Catalog sync, schema validation, Unicode safety checks |

### Technology Stack

| Layer | Technology |
|---|---|
| Configuration Distribution | Node.js (npm package `ecc-universal`) |
| Hook Runtime | Node.js scripts, shell wrappers |
| Install System | Node.js (`scripts/ecc.js`, `scripts/install-apply.js`) |
| Session Management (ECC 2.0) | Rust (Tokio, Clap, Ratatui, rusqlite) |
| GUI Dashboard | Python 3 (TkInter) |
| LLM Abstraction | Python 3 (abstract base class) |
| State Storage (ECC 2.0) | SQLite (via rusqlite, bundled) |
| Git Integration (ECC 2.0) | libgit2 (via git2 crate) |
| Schema Validation | JSON Schema (Ajv in Node.js) |
| CI/CD | Node.js test runner, ESLint, markdownlint |
| Package Management | yarn 4.9.2, npm |

> [!NOTE]
> ECC 2.0 (the Rust TUI) is a separate binary that requires compilation with `cargo build`. It is not distributed via npm and operates independently of the ECC 1.x configuration pack.

---

## 2. System Requirements

| Component | Requirement | Notes |
|---|---|---|
| Node.js | >= 18 | Required for all ECC 1.x functionality |
| Rust | Stable toolchain | Only for building ECC 2.0 TUI |
| Python 3 | 3.8+ | Only for the GUI dashboard and LLM abstraction |
| Git | Any recent version | Required for worktree features |
| Claude Code | Any version | Primary target; other IDEs partially supported |
| SQLite | Bundled with rusqlite | No external install needed for ECC 2.0 |
| OpenSSL | System or vendored | ECC 2.0 uses `vendored-openssl` feature by default |

---

## 3. Configuration Reference

### Config Files

| File | Format | Location | Purpose |
|---|---|---|---|
| `hooks/hooks.json` | JSON | ECC root | Hook definitions — all PreToolUse, PostToolUse, lifecycle hooks |
| `mcp-configs/mcp-servers.json` | JSON | ECC root | MCP server catalog (copy entries to `~/.claude.json`) |
| `.mcp.json` | JSON | ECC root | Active MCP servers for the ECC repo itself |
| `agent.yaml` | YAML | ECC root | gitagent export surface definition |
| `manifests/install-components.json` | JSON | ECC root | Install component definitions and module mappings |
| `manifests/install-modules.json` | JSON | ECC root | Install module file mappings and targets |
| `schemas/ecc-install-config.schema.json` | JSON Schema | ECC root | Validation schema for install configuration |
| `ecc2/ecc2.toml` | TOML | ECC 2.0 | TUI and session manager configuration |
| `commitlint.config.js` | JS | ECC root | Conventional commit enforcement |
| `.markdownlint.json` | JSON | ECC root | Markdown linting rules |

### Environment Variables

| Variable | Type | Default | Description | Required |
|---|---|---|---|---|
| `ECC_HOOK_PROFILE` | String | `standard` | Hook behavior profile: `minimal`, `standard`, `strict` | No |
| `ECC_DISABLED_HOOKS` | String | (none) | Comma-separated hook IDs to disable | No |
| `ECC_DISABLED_MCPS` | String | (none) | Comma-separated MCP server names to exclude during install | No |
| `CLAUDE_PACKAGE_MANAGER` | String | (auto-detected) | Override package manager: `npm`, `yarn`, `pnpm`, `bun` | No |
| `CLAUDE_PLUGIN_ROOT` | String | (auto-resolved) | Override ECC installation root path | No |
| `ECC_PLUGIN_ROOT` | String | (auto-resolved) | Alias for `CLAUDE_PLUGIN_ROOT` | No |
| `CLAUDE_PROJECT_DIR` | String | (cwd) | Project directory for GateGuard state | No |
| `CLAUDE_DIR` | String | `~/.claude` | Claude Code configuration directory | No |
| `CLAUDE_RULES_DIR` | String | (derived) | Override rules installation directory | No |
| `CLAUDE_SESSION_ID` | String | (auto) | Current Claude Code session ID | No |
| `CLAUDE_TRANSCRIPT_PATH` | String | (auto) | Path to session transcript for continuous learning | No |
| `CLAUDE_MODEL` | String | (auto) | Active model name for cost tracking | No |
| `CLAUDE_HOOK_EVENT_NAME` | String | (auto) | Hook event name injected by Claude Code runtime | No |
| `ECC_SESSION_ID` | String | (auto) | ECC session identifier for cost tracking | No |
| `ECC_GOVERNANCE_CAPTURE` | String | `0` | Enable governance event capture: `0` or `1` | No |
| `ECC_QUALITY_GATE_FIX` | String | (none) | Auto-fix mode for quality gate | No |
| `ECC_QUALITY_GATE_STRICT` | String | (none) | Strict mode for quality gate | No |
| `ECC_MCP_HEALTH_STATE_PATH` | String | (auto) | Path to MCP health state file | No |
| `ECC_MCP_CONFIG_PATH` | String | (auto) | Path to MCP configuration for health checks | No |
| `ECC_MCP_RECONNECT_COMMAND` | String | (none) | Command to run when MCP reconnection is needed | No |
| `ECC_MCP_HEALTH_FAIL_OPEN` | String | (none) | Allow MCP calls even when health check fails | No |
| `ECC_HOOK_INPUT_TRUNCATED` | String | (auto) | Set by hook runtime when input was truncated | No |
| `ECC_HOOK_INPUT_MAX_BYTES` | String | (auto) | Maximum bytes for hook input | No |
| `GATEGUARD_STATE_DIR` | String | (derived) | GateGuard file-based state directory | No |
| `COMPACT_THRESHOLD` | String | `50` | Tool call count before suggesting `/compact` | No |
| `ECC_SESSION_RETENTION_DAYS` | String | (default) | Days to retain session data | No |
| `ECC_UNICODE_SCAN_ROOT` | String | (cwd) | Root directory for Unicode safety scan | No |
| `ECC_WORKFLOWS_DIR` | String | (derived) | Directory for workflow security validation | No |
| `TMUX` | String | (auto) | Set by tmux when running inside a tmux session | No |

> [!IMPORTANT]
> The `CLAUDE_PLUGIN_ROOT` variable is critical for plugin installations. The `plugin-hook-bootstrap.js` wrapper searches multiple candidate paths (direct install, plugin cache, marketplace directories) to resolve the ECC root. If hooks cannot find their helper scripts, set this variable explicitly.

### Install Configuration Schema

Install configuration files (`ecc-install.json`) support the following fields:

| Field | Type | Description |
|---|---|---|
| `version` | Integer (const: `1`) | Schema version |
| `target` | String | IDE target: `claude`, `cursor`, `antigravity`, `codex`, `gemini`, `opencode`, `codebuddy` |
| `profile` | String | Named install profile |
| `modules` | String[] | Specific module IDs to install |
| `include` | String[] | Component IDs to include (e.g., `baseline:rules`, `lang:python`) |
| `exclude` | String[] | Component IDs to exclude |
| `options` | Object | Additional options |

### Hook Configuration Schema

Each hook entry in `hooks/hooks.json` follows this structure:

```json
{
  "matcher": "Bash|Edit|Write|MultiEdit|*",
  "hooks": [
    {
      "type": "command",
      "command": "node path/to/hook.js",
      "async": false,
      "timeout": 30
    }
  ],
  "description": "Human-readable description",
  "id": "pre:bash:dispatcher"
}
```

Hook types supported: `command` (run a shell command), `http` (call a URL), `prompt`/`agent` (invoke an LLM prompt).

> [!NOTE]
> The `matcher` field supports pipe-separated tool names (`Edit|Write|MultiEdit`) or `*` for all tools.

---

## 4. Deployment & Scaling

### npm Distribution

ECC is published as `ecc-universal` on npm. The `package.json` defines two binaries:

| Binary | Script | Purpose |
|---|---|---|
| `ecc` | `scripts/ecc.js` | Primary installer CLI |
| `ecc-install` | `scripts/install-apply.js` | Component-based installer |

The `files` array in `package.json` controls what ships in the npm package. It includes all skills, rules, hooks, commands, agents, manifests, schemas, MCP configs, and install scripts.

### Building ECC 2.0

```bash
cd ecc2
cargo build --release
```

```text
Compiling ecc-tui v0.1.0
    Finished release [optimized] target(s)
```

The release profile enables LTO, single codegen unit, and symbol stripping for a minimal binary.

**Cargo.toml features:**
- `vendored-openssl` (default) — bundles OpenSSL for cross-platform builds
- Git integration via `git2` crate with SSH support

> [!TIP]
> On systems where OpenSSL headers are unavailable, the `vendored-openssl` feature (enabled by default) compiles OpenSSL from source. This adds build time but eliminates system dependency issues.

### Multi-IDE Deployment

The install system supports multiple IDE targets via the `target` field in install configuration. Each target maps to different file locations:

| Target | Rules Location | Config Approach |
|---|---|---|
| `claude` | `~/.claude/rules/` | Native hooks, commands, MCP |
| `cursor` | `.cursor/rules/` | Adapted rules (via `scripts/gemini-adapt-agents.js` pattern) |
| `codex` | `.codex/` | Merged configs (`scripts/codex/merge-codex-config.js`) |
| `gemini` | `.gemini/` | Adapted agent definitions |
| `opencode` | `.opencode/` | OpenCode plugin format (built via `npm run build:opencode`) |

---

## 5. Operations

### Install Lifecycle

The install system (`scripts/lib/install-lifecycle.js`) manages a full lifecycle:

1. **Plan** (`scripts/install-plan.js`): Resolves profiles, components, and modules into a concrete install plan
2. **Apply** (`scripts/install-apply.js`): Executes the plan — copies files, merges configs, renders templates
3. **Repair** (`scripts/repair.js`): Restores missing or corrupted installed files from source
4. **Uninstall** (`scripts/uninstall.js`): Reverses the install, removing only ECC-managed files

Install state is persisted to enable repair and uninstall operations.

> [!NOTE]
> The install system performs non-destructive merges — existing user configuration is preserved. ECC-managed files are tracked in install state so they can be cleanly removed.

### Catalog Synchronization

The catalog system (`scripts/ci/catalog.js`) keeps README tables, AGENTS.md, and translated documentation in sync with the actual directory contents:

```bash
# Check catalog consistency
npm run catalog:check

# Auto-sync catalog tables
npm run catalog:sync
```

### CI Validation Pipeline

The test suite validates structural integrity:

```bash
npm test
```

This runs (in sequence):

1. `check-unicode-safety.js` — detects Unicode homoglyph attacks in source files
2. `validate-agents.js` — validates agent definitions
3. `validate-commands.js` — validates command files
4. `validate-rules.js` — validates rule structure
5. `validate-skills.js` — validates skill directories and SKILL.md files
6. `validate-hooks.js` — validates hooks against schema
7. `validate-install-manifests.js` — validates install manifests
8. `validate-no-personal-paths.js` — ensures no hardcoded personal paths
9. `catalog:check` — verifies catalog tables are in sync
10. `tests/run-all.js` — runs unit test suite

> [!TIP]
> Run `npm run coverage` to generate code coverage reports using c8. The coverage thresholds are 80% for lines, functions, branches, and statements.

### Worktree Orchestration

ECC includes a tmux-based worktree orchestration system (`scripts/lib/tmux-worktree-orchestrator.js`) for running parallel agent sessions:

1. **Plan construction**: Define workers with tasks, agent types, and seed paths
2. **Worktree creation**: Each worker gets an isolated git worktree
3. **tmux session**: Workers run in separate tmux panes within a shared session
4. **Monitoring**: `node scripts/orchestration-status.js` shows worker status
5. **Merge**: Completed worktrees are merged back to the base branch

Key safety validations:
- Seed paths must stay inside the repo root (path traversal rejection)
- Worker slugs must be unique
- Each worker must have a task and launcher command
- Rollback on failure with tracked cleanup

### Session Management (ECC 2.0)

The ECC 2.0 session manager (`ecc2/src/session/manager.rs`) provides:

- **Session lifecycle**: Create, start, stop, resume, delete sessions
- **Worktree attachment**: Each session can have a dedicated git worktree
- **Delegation**: Sessions can delegate work to child sessions
- **Merge queue**: Automated merge of completed worktree branches
- **Heartbeat monitoring**: Detect and recover stalled sessions
- **Budget enforcement**: Track and enforce cost limits per session
- **Conflict detection**: Identify file-level conflicts between concurrent sessions

---

## 6. Performance

### Context Window Management

The strategic compact system (`skills/strategic-compact/`) suggests `/compact` at logical intervals (configurable via `COMPACT_THRESHOLD`, default 50 tool calls). The `pre:edit-write:suggest-compact` hook triggers these suggestions.

### Hook Performance

Hooks that should not block the main flow use `"async": true`:
- Post-bash dispatcher (PR logging, build analysis)
- Quality gate checks
- Continuous learning observation

Synchronous hooks have explicit timeouts (typically 5-10 seconds) to prevent blocking.

> [!NOTE]
> The consolidated dispatcher pattern (one `pre-bash-dispatcher.js` instead of individual hooks) significantly reduces fork count. This addressed the macOS `EAGAIN posix_spawn` issue (GitHub issue #1423).

### MCP Server Limits

The MCP catalog warns to keep under 10 servers enabled simultaneously. Each active MCP server consumes context window space and adds latency to tool discovery.

---

## 7. Security

### Hook Security Model

Hooks execute as shell commands with the same permissions as the Claude Code process. Security-relevant hooks include:

| Hook | Security Function |
|---|---|
| Config protection | Blocks modifications to linter/formatter configs (prevents agents from weakening quality rules) |
| GateGuard fact-force | Forces investigation before file modifications (prevents blind writes) |
| Governance capture | Logs secrets and policy violations (opt-in via `ECC_GOVERNANCE_CAPTURE=1`) |
| Doc file warning | Prevents creation of non-standard documentation files |
| MCP health check | Blocks calls to unhealthy MCP servers |

> [!WARNING]
> The `plugin-hook-bootstrap.js` bootstrap layer executes `require()` against resolved paths. If an attacker can place files at predictable paths in the plugin cache (`~/.claude/plugins/cache/`), they could achieve code execution. The bootstrap validates against a known set of directory patterns but does not perform cryptographic integrity checks.

### Path Traversal Protection

The hook bootstrap (`scripts/hooks/plugin-hook-bootstrap.js`) rejects paths with traversal patterns:

```javascript
// Path traversal rejected: ${relPath}
```

The tmux worktree orchestrator validates that seed paths stay inside the repo root to prevent worktree creation outside the project boundary.

### Input Validation

- Hook inputs are JSON-parsed with explicit error handling
- File paths in hooks are checked for unsafe shell characters (`post-edit-format.js`)
- Script names and binary names in the package manager module are validated against unsafe character patterns
- Install module IDs use pattern validation: `^[a-z0-9-]+$`

### Sensitive Configuration

MCP server configurations in `mcp-configs/mcp-servers.json` contain placeholder API keys (`YOUR_*_HERE`). These should be replaced with actual values in the user's local `~/.claude.json`, not in the repository.

> [!CAUTION]
> Never commit actual API keys to the MCP configuration files. The `validate-no-personal-paths.js` CI check helps catch accidental path leaks, but API key detection is not currently automated.

---

## 8. Developer Internals

### Repository Structure

```text
everything-claude-code/
├── agents/                     # Agent definitions (markdown)
├── commands/                   # Slash command definitions (80+ markdown files)
├── contexts/                   # Context documents for Claude Code
├── docs/                       # Multi-language documentation
│   ├── business/               # Business documents
│   ├── examples/               # Usage examples
│   ├── releases/               # Release notes
│   ├── ja-JP/                  # Japanese translation
│   ├── ko-KR/                  # Korean translation
│   ├── pt-BR/                  # Portuguese (Brazil) translation
│   ├── tr/                     # Turkish translation
│   ├── zh-CN/                  # Simplified Chinese translation
│   └── zh-TW/                  # Traditional Chinese translation
├── ecc2/                       # ECC 2.0 Rust TUI
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs             # CLI entry point (9000+ lines, Clap-based)
│       ├── config/mod.rs       # TOML configuration (ecc2.toml)
│       ├── session/            # Session management
│       │   ├── mod.rs          # Types, enums, state machine
│       │   ├── manager.rs      # Session lifecycle, delegation, merge queue
│       │   ├── store.rs        # SQLite persistence
│       │   ├── runtime.rs      # Process spawning, I/O piping
│       │   ├── daemon.rs       # Background daemon
│       │   └── output.rs       # Output streaming
│       ├── worktree/mod.rs     # Git worktree operations (1500+ lines)
│       ├── tui/app.rs          # Ratatui TUI application
│       ├── observability/mod.rs # Tool call logging
│       ├── comms/mod.rs        # Inter-session messaging
│       └── notifications.rs    # Desktop and webhook notifications
├── examples/                   # Example configurations
├── hooks/                      # Hook configuration
│   └── hooks.json              # Master hook definitions
├── manifests/                  # Install manifests
│   ├── install-components.json # Component definitions
│   └── install-modules.json    # Module file mappings
├── mcp-configs/                # MCP server catalog
│   └── mcp-servers.json        # 20+ server configs
├── plugins/                    # Plugin system
├── research/                   # Research documents
├── rules/                      # Coding rules
│   ├── common/                 # Language-independent
│   ├── typescript/             # TypeScript/JS
│   ├── python/                 # Python
│   ├── golang/                 # Go
│   ├── swift/                  # Swift
│   ├── kotlin/                 # Kotlin
│   ├── java/                   # Java
│   ├── rust/                   # Rust
│   ├── cpp/                    # C/C++
│   ├── php/                    # PHP
│   ├── csharp/                 # C#
│   ├── perl/                   # Perl
│   ├── dart/                   # Dart
│   └── web/                    # Web-specific
├── schemas/                    # JSON Schema files
├── scripts/                    # Tooling scripts
│   ├── ecc.js                  # Primary CLI entry point
│   ├── install-apply.js        # Install executor
│   ├── install-plan.js         # Install planner
│   ├── doctor.js               # Diagnostic tool
│   ├── repair.js               # Install repair
│   ├── uninstall.js            # Uninstaller
│   ├── catalog.js              # Catalog sync
│   ├── claw.js                 # Interactive session launcher
│   ├── status.js               # Status reporter
│   ├── hooks/                  # Hook implementations (40 files)
│   ├── lib/                    # Shared libraries
│   │   ├── install*.js         # Install lifecycle modules
│   │   ├── state-store/        # SQLite-based state (Node.js)
│   │   ├── skill-evolution/    # Skill tracking and versioning
│   │   ├── tmux-worktree-orchestrator.js  # Parallel agent orchestration
│   │   ├── package-manager.js  # Package manager abstraction
│   │   ├── mcp-config.js       # MCP configuration utilities
│   │   ├── hook-flags.js       # Hook profile/disable logic
│   │   └── utils.js            # Common utilities
│   ├── ci/                     # CI validation scripts
│   └── codex/                  # Codex integration scripts
├── skills/                     # 130+ skill directories
│   ├── <skill-name>/
│   │   └── SKILL.md            # Skill definition
│   └── ...
├── src/                        # Python source
│   └── llm/                    # LLM provider abstraction
│       ├── __init__.py
│       ├── __main__.py         # CLI entry: python -m llm
│       ├── cli/selector.py     # Interactive model selector
│       └── core/
│           ├── interface.py    # Abstract LLMProvider base class
│           └── types.py        # Data types (Message, ToolCall, etc.)
├── tests/                      # Test suites
│   ├── lib/                    # Unit tests for scripts/lib
│   ├── hooks/                  # Hook tests
│   ├── ci/                     # CI validation tests
│   └── run-all.js              # Test runner
├── agent.yaml                  # gitagent manifest
├── commitlint.config.js        # Commit message rules
├── ecc_dashboard.py            # Python GUI dashboard
├── install.sh                  # Unix install script
├── install.ps1                 # Windows install script
├── package.json                # npm package definition
└── the-security-guide.md       # Security reference
```

### Module Reference

#### ECC 2.0 Session Manager (`ecc2/src/session/manager.rs`)

The session manager is the orchestration core of ECC 2.0. Key capabilities:

**Session lifecycle:**
- `list_sessions()` — enumerate all sessions from SQLite
- `get_status()` — full status including worktree state, metrics, costs
- `stop_session()` — gracefully stop a running session (SIGTERM, then SIGKILL)
- `resume_session()` — resume a paused or crashed session
- `delete_session()` — remove session and clean up worktree

**Delegation model:**
- Sessions form a tree: a lead session can delegate tasks to child sessions
- `get_team_status()` — traverse the delegation tree to a configurable depth
- Assignment policy (`assign`) routes work to existing idle delegates or spawns new ones
- `drain_inbox()` — process unread task handoffs from a lead's inbox
- `auto_dispatch()` — sweep across lead sessions and route handoffs

**Merge queue:**
- `build_merge_queue()` — identify mergeable worktrees and blockers
- `process_merge_queue()` — merge all ready worktrees (inactive sessions only)
- Blockers include: uncommitted changes, staged changes, active sessions, merge conflicts

**Coordination:**
- `coordinate_backlog()` — dispatch + rebalance in one pass
- `maintain_coordination()` — conditional coordination when pressure is detected
- `get_coordination_status()` — global health assessment (healthy, saturated, needs attention)

#### ECC 2.0 Worktree Module (`ecc2/src/worktree/mod.rs`)

Git worktree operations via shell commands (not libgit2 for worktree operations):

- `create_for_session()` — creates a worktree with a session-specific branch
- `sync_shared_dependency_dirs()` — symlinks `node_modules`, `.venv`, etc. into the worktree
- `merge_into_base()` / `rebase_onto_base()` — integrate worktree changes
- `merge_readiness()` — pre-merge conflict check using `git merge-tree`
- `health()` — categorize worktree state (clean, dirty, diverged, conflicted)
- `diff_file_preview()` / `diff_patch_preview()` — bounded diff output for TUI display
- `create_draft_pr()` — push branch and create a GitHub draft PR via `gh`
- Hunk-level staging: `stage_hunk()`, `unstage_hunk()` for fine-grained git operations

#### ECC 2.0 State Store (`ecc2/src/session/store.rs`)

SQLite database with WAL mode for concurrent read access:

- Sessions, scheduled tasks, remote dispatch requests, messages
- Context graph: entities, relations, observations (knowledge graph per session)
- Daemon activity tracking (recovery, rebalance passes)
- Cost and tool activity metrics sync from external files
- Conflict incident tracking for worktree merge conflicts

#### ECC 2.0 Configuration (`ecc2/src/config/mod.rs`)

TOML-based configuration at `~/.config/ecc2/ecc2.toml`:

- Agent profiles with inheritance (child profiles inherit from parent)
- Orchestration templates with variable substitution
- Harness runner configuration (which binary to spawn for each agent type)
- Memory connectors: JSONL file/directory, Markdown file/directory, dotenv file
- Notification config: desktop notifications, webhooks (Slack, Discord, custom), quiet hours
- Budget alert thresholds
- Conflict resolution strategies (manual, auto-merge, auto-rebase)
- TUI pane layout and keyboard shortcuts

#### Hook System (`hooks/hooks.json` + `scripts/hooks/`)

All hooks are wrapped by `plugin-hook-bootstrap.js`, which:
1. Resolves the ECC installation root from multiple candidate paths
2. Sets `CLAUDE_PLUGIN_ROOT` for downstream scripts
3. Delegates to the actual hook script

The `run-with-flags.js` wrapper adds profile-based filtering:
- Checks `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS`
- Skips execution if the hook is disabled for the current profile
- Passes through to the actual hook script if enabled

#### Install System (`scripts/lib/install*.js` + `manifests/`)

The install system uses a three-layer architecture:

1. **Manifests** (`manifests/install-components.json`, `manifests/install-modules.json`): Define what can be installed
2. **Request** (`scripts/lib/install/request.js`): Parse CLI arguments into a normalized install request
3. **Runtime** (`scripts/lib/install/runtime.js`): Resolve request to file operations
4. **Apply** (`scripts/lib/install/apply.js`): Execute file operations (copy, merge, render)
5. **State** (`scripts/lib/install-state.js`): Track what was installed for repair/uninstall

Install modules support multiple targets — each module specifies which IDE targets it supports, and the installer filters accordingly.

#### Skill Evolution System (`scripts/lib/skill-evolution/`)

Tracks skill usage, effectiveness, and versioning:

- `tracker.js` — Records skill execution outcomes (success, failure, partial) and user feedback
- `versioning.js` — Manages skill version history with rollback capability
- `provenance.js` — Validates provenance metadata for learned/imported skills
- `health.js` — Monitors skill health metrics and warns on degradation
- `dashboard.js` — Panel-based dashboard for skill evolution status

#### LLM Abstraction Layer (`src/llm/`)

A Python-based provider abstraction:

- `LLMProvider` (ABC): `generate()`, `list_models()`, `validate_config()`, `supports_tools()`, `supports_vision()`
- Type system: `Message`, `ToolDefinition`, `ToolCall`, `ToolResult`, `LLMInput`, `LLMOutput`, `ModelInfo`
- Provider types: `anthropic`, `openai`, `google`, `local`
- CLI selector: `python -m llm` launches an interactive provider/model chooser

> [!NOTE]
> The LLM abstraction layer currently defines interfaces and types but does not include concrete provider implementations in the repository. It serves as a framework for building provider-specific integrations.

### Code Patterns and Conventions

**Commit format:** Conventional commits enforced by `commitlint.config.js` — types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`.

**Error handling (Rust):** Uses `anyhow::Result` for application errors and `thiserror` for typed domain errors. All fallible operations return `Result<T>`.

**Error handling (Node.js):** Custom `Error` classes with descriptive messages. Hook scripts use structured error messages with context (file path, field name, etc.).

**State management (ECC 2.0):** SQLite with WAL mode. All database writes go through the `StateStore` struct. Session state transitions are validated (`can_transition_to()`).

**Hook pattern:** Every hook follows the pattern: read stdin → parse JSON → check conditions → write stderr (warnings) → write stdout (passthrough) → exit with appropriate code.

**Cross-platform:** Hook logic is implemented in Node.js for cross-platform behavior. Shell wrappers exist only for continuous learning observers. Windows-specific issues are documented in GitHub issues and handled with conditional logic.

### Testing Strategy

**Test framework:** Custom Node.js test runner (`tests/run-all.js`) with assertion helpers.

**Test organization:**
- `tests/lib/` — Unit tests for `scripts/lib/` modules (package-manager, session-manager, tmux-worktree-orchestrator, skill-evolution, install-manifests, etc.)
- `tests/hooks/` — Hook behavior tests (gateguard, MCP health check, etc.)
- `tests/ci/` — CI validation tests

**Coverage:** c8 with 80% thresholds for lines, functions, branches, and statements.

**CI checks:**
- Unicode safety (homoglyph detection)
- Agent, command, rule, skill, hook schema validation
- Install manifest consistency
- Personal path detection
- Catalog sync verification

### Contributing

1. Fork the repository and create a feature branch
2. Follow the conventional commit format
3. Add or update skills in `skills/<name>/SKILL.md`
4. Add commands in `commands/<name>.md`
5. Run `npm run catalog:sync` to update catalog tables
6. Run `npm test` to validate all schemas and structures
7. Submit a PR

**Adding a new language:**

1. Create `rules/<language>/` with `coding-style.md`, `testing.md`, `patterns.md`, `hooks.md`, `security.md`
2. Each file references its `../common/` counterpart
3. Add install component in `manifests/install-components.json`
4. Update `install.sh` and `install.ps1`
5. Add translations in `docs/` language directories

---

## 9. Integration Points

### Claude Code Plugin System

ECC can be installed as a Claude Code plugin via the marketplace:

```bash
/plugins
claude plugin install ecc@claude-plugins-official
```

The plugin ships `hooks.json` and associated scripts. The bootstrap layer (`plugin-hook-bootstrap.js`) resolves plugin paths from multiple installation locations:

1. `CLAUDE_PLUGIN_ROOT` environment variable
2. Direct `~/.claude/` installation
3. Plugin marketplace paths (`~/.claude/plugins/ecc/`, etc.)
4. Plugin cache paths (`~/.claude/plugins/cache/ecc/`)

> [!WARNING]
> The `"agents"` field in `plugin.json` currently fails manifest validation (GitHub issue #1459), preventing plugin installation in some Claude Code versions. Use the npm or manual install methods as alternatives.

### Codex Integration

For OpenAI Codex environments:

```bash
npx ecc --target codex typescript
```

Codex-specific scripts:
- `scripts/codex/merge-codex-config.js` — merges ECC configuration into Codex format
- `scripts/codex/merge-mcp-config.js` — adapts MCP server configs for Codex
- `scripts/codex-git-hooks/` — Git hook adapters for Codex workflows
- `scripts/orchestrate-codex-worker.sh` — Codex-specific worker orchestration

### Gemini Integration

```bash
npx ecc --target gemini typescript
```

Uses `scripts/gemini-adapt-agents.js` to transform agent definitions into Gemini-compatible format.

### gitagent Specification

The `agent.yaml` file exports ECC's surface in the gitagent specification format:

```yaml
spec_version: "0.1.0"
name: everything-claude-code
version: 1.10.0
model:
  preferred: claude-opus-4-6
  fallback:
    - claude-sonnet-4-6
skills: [130+ skill IDs]
commands: [80+ command names]
tags: [agent-harness, developer-tools, code-review, testing, security, cross-platform, gitagent]
```

### Internationalization

ECC documentation is translated into 6 languages:

| Language | Directory | Coverage |
|---|---|---|
| Japanese | `docs/ja-JP/` | Full (rules, skills, examples, commands) |
| Korean | `docs/ko-KR/` | Full |
| Portuguese (Brazil) | `docs/pt-BR/` | Full |
| Turkish | `docs/tr/` | Full |
| Simplified Chinese | `docs/zh-CN/` | Full |
| Traditional Chinese | `docs/zh-TW/` | Partial |

Translated documentation mirrors the English structure with localized content for rules, skills, hooks, plugins, and examples.

---

_Generated May 2026 from affaan-m/everything-claude-code at 1a50145. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._