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.

┌─────────────────────────────────────────────────────────┐
│                    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

Technology Stack

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

3. Configuration Reference

Config Files

Environment Variables

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:

Hook Configuration Schema

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

{
  "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:

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

cd ecc2
cargo build --release

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:

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:

# Check catalog consistency
npm run catalog:check

# Auto-sync catalog tables
npm run catalog:sync

CI Validation Pipeline

The test suite validates structural integrity:

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:

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:

// 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

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:

/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:

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

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:

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:

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