Architecture

Architecture

Two MCP servers, local-only

EGC's runtime is two Model Context Protocol servers running as local stdio processes: egc-memory (state persistence) and egc-guardian (validation and catalog routing). Both are TypeScript projects compiled with tsc, source in mcp/servers/egc-memory/ and mcp/servers/egc-guardian/. See MCP-Servers for the full tool list.

egc-memory stores state in a SQLite database with WAL mode and a message-queue write-arbitration layer to prevent concurrent-write conflicts; native sqlite3 when its binary loads, the portable sql.js engine behind the same API otherwise. State content is encrypted at rest with AES-256-GCM before touching disk. Memory has two scopes since v1.1.12: one state per project branch, plus a user-wide global scope for transversal preferences and lessons.

egc-guardian intercepts every shell command and file write through PreToolUse hooks installed in each supported tool, and routes free-text prompts against the component catalog (agents, skills, rules) via orchestrate_task, using local keyword scoring by default and semantic LLM routing only when EGC_LLM_ROUTING=1 and a provider key are both set. It also offers validate_content, an advisory prompt-injection scan for untrusted content.

Cross-harness design

Source: docs/architecture/cross-harness.md.

EGC is the reusable workflow layer; each supported tool ("harness") is an execution surface. The durable parts of agentic work, skills, rules and instructions, hooks where the harness supports them, MCP configuration, install manifests, live once in this repository. Each harness adapts those assets at the edge instead of requiring a new workflow model per tool.

Surface	Shared source	Adapted per harness
Skills	skills/*/SKILL.md	Packaged per harness (plugin format, flat directory copy, and so on)
Rules and instructions	rules/, AGENTS.md	Injected differently per harness (native rules, AGENTS.md, cursor rules)
Hooks	hooks/hooks.json, scripts/hooks/	Hook-backed where the harness supports hooks, instruction-backed otherwise
MCPs	.mcp.json, mcp-configs/	Native MCP config import per harness where MCP is supported
Commands	commands/, CLI scripts	Command semantics vary per harness

The rule for new work: put the durable behavior in skills/, rules/, hooks/, or scripts/ first. Harness-specific files should only load the shared asset, adapt event shapes, map command names, or handle platform limits. If a change requires editing three harness-specific copies of the same workflow, the shared source is in the wrong place.

Repository layout (active surfaces)

Source: docs/governance/SUBSYSTEM-MAP.md. This file classifies subsystems as ACTIVE, GENERATED, ARCHIVAL, DORMANT, LEGACY, or DEPRECATED so contributors know what is live.

Path	Notes
agents/	Agent definitions, source of truth
commands/	Slash commands
skills/	Skills, one directory per skill
rules/	Cross-language coding rules
hooks/hooks.json	Hook manifest; implementations in scripts/hooks/
scripts/lib/install-targets/	Per-target install adapters (one file per harness)
scripts/ci/	Structure validators invoked by CI
scripts/egc.js	The egc CLI entrypoint (bin: egc)
scripts/install-apply.js	The egc-install entrypoint
manifests/install-{modules,profiles,components}.json	Install adapter driver, defines profiles and modules
mcp/servers/egc-guardian/, mcp/servers/egc-memory/	The two MCP servers
tests/	Test suite (tests/run-all.js runs everything matching **/*.test.js)
scripts/install.sh, scripts/install.ps1	Cross-platform install entrypoints (the shell script re-executes itself under bash)

Some paths are explicitly marked DORMANT in the source-of-truth map (present in the repository but not currently wired into any execution path): scripts/runtime/ (router, mount-all, unmount-all, activator beyond discovery.js), scripts/orchestration/router.py, and a handful of Python test files excluded from the JS test runner's glob. The map instructs contributors not to revive dormant paths opportunistically without updating the documentation to say so.

Install pipeline

egc install resolves a profile and target through scripts/lib/install-manifests.js against the adapters in scripts/lib/install-targets/registry.js, then scripts/install-apply.js materializes the files. The pipeline supports dry-run and records provenance metadata for every file it writes. See Configuration for profiles and Supported-Tools for the tier model each harness falls into.

Adding a new harness

Per docs/spec/integration-tiers.md: choose a tier based on what the target tool actually consumes. MCP and instruction files only: Tier 3, add the tool to the shared MCP registration list in scripts/lib/mcp-register.js (used by egc init and, through mcp-register-cli.js, by both shell installers) and a target name to scripts/bootstrap-cognitive.js. Filesystem skills, agents or rules, whatever the layout: Tier 1, add an adapter to scripts/lib/install-targets/ and register it, plus manifest entries. Tier 2 (a .{tool}/install.sh of its own) is retired: Kiro, Trae and CodeBuddy moved their custom assets into Tier 1 adapters and those scripts no longer exist. Tier 1 is the answer for every tool with filesystem assets; Tier 3 for thin clients.

Beyond the two servers

Three more runtime pieces ship in the same package and are wired by egc init on hook-capable harnesses:

• Token Crusher: compresses noisy shell output (git log, git diff, test runners, package managers, large gh --json payloads) before it reaches the model, through egc run, an automatic bash-hook rewrite, and a PATH-level binary shim (egc crusher-shim) for tools without hook rewrite support. Savings are kept in a local ledger read by egc saved and egc gain.
• EGC Scrubber (v1.1.21): a deterministic, fail-open Write/Edit hook that strips invisible Unicode carriers and long dashes from content you own, plus a commit hook that removes AI co-authorship trailers; the content-scrubber skill and CLI cover batch use and file metadata.
• Session mesh (v1.1.19): a durable event bus in the state store with wake-on-write delivery (session_wait), cooperative path locks, presence and territories, taught to every install by the cognitive protocol (v6 since v1.1.22) and reinforced by a native turn-boundary notice on the harnesses whose hooks can inject context. See Supported-Tools for the per-harness map.