Related Pages

Related topics: Lib

Overview

EGC is a command-line utility that centralizes a project's shared AI context — guidelines, conventions, prompts, and role definitions — and projects that context into the native configuration files of every supported AI coding agent. It targets environments where developers switch between tools such as Cursor, Gemini CLI, GitHub Copilot, Windsurf, JetBrains Junie, Cline, Qwen Code, and Roo Code, and where keeping each tool's rules files in sync by hand is impractical. Source: scripts/lib/install-targets/.

Purpose and Scope

Every AI coding agent reads instructions from its own configuration file — .cursor/rules, GEMINI.md, .github/copilot-instructions.md, .windsurfrules, and similar. EGC exists so a team authors context once, in a single source of truth, and propagates it to whichever subset of those files the developer has selected. The tool ships with first-class integrations for a range of IDEs and CLIs, and the target list is intentionally extensible. New entries are added by dropping a module into the install-targets directory; the most recent community proposals cover JetBrains Junie, Cline, Qwen Code, and Roo Code. Source: Issue #847, Issue #846, Issue #845, Issue #852.

Beyond install, the scope includes bidirectional synchronization via a long-running watcher, automated internationalization of the user-facing README, and a release cadence visible in the v1.1.x line. Source: Release v1.1.11.

Core Architecture

EGC is organized as a thin CLI entry point around a library of *install targets*. Each target encapsulates the knowledge required to write EGC-managed content into one specific tool's discovery path: the file location, the syntax of the marker block the tool expects, and any pre- or post-install hooks. Source: scripts/lib/install-targets/.

The repository also ships project-level integration directories that mirror this model at the repo root. Each one holds a README, and some include deeper configuration such as hook definitions. The directories visible in the tree include a ClusterFuzz Lite integration root, a Codebuddy plugin directory, a Codex plugin directory, a Gemini plugin directory, and a Kiro IDE directory with a hooks/ subdirectory for Kiro hook manifests. Source: .clusterfuzzlite/Dockerfile, .codebuddy/README.md, .codex-plugin/README.md, .gemini-plugin/README.md, .kiro/README.md, .kiro/hooks/README.md.

Core Commands and Workflows

The two commands most contributors interact with are egc install and egc watch.

egc install --target <name> writes the project's EGC block into the discovery path of the named target. Targets live under scripts/lib/install-targets/, so adding a new tool means shipping one module rather than editing shared dispatch code. Source: Issue #847, Issue #846.

egc watch runs as a daemon that observes every EGC-managed file inside the working tree. When a developer edits the EGC block directly inside one tool's config file, the watcher extracts that block, updates the canonical state under ~/.egc/state/, and re-projects it to every other configured target. The v1.1.2 release notes describe the design goal of this command: bidirectional, atomic sync across the supported tool set. Source: Release v1.1.2.

flowchart LR
    A[Source edit in any tool file] --> B[egc watch daemon]
    B --> C[~/.egc/state/]
    C --> D{Targets}
    D --> E[Cursor .cursor/rules]
    D --> F[Gemini GEMINI.md]
    D --> G[Copilot copilot-instructions.md]
    D --> H[Windsurf .windsurfrules]
    D --> I[Other targets]
    E -.bidirectional.-> B
    F -.bidirectional.-> B
    G -.bidirectional.-> B
    H -.bidirectional.-> B

Internationalization and Release Cadence

The user-facing README is maintained in many languages so the project remains accessible to non-English-speaking developer communities. Shipped translations cover Korean, Japanese, Russian, Arabic, Hindi, Spanish, and Portuguese, with Chinese in progress; the active proposal to close the most significant remaining gap is French. Source: Issue #848.

The project has progressed through an active 1.1.x line — v1.1.2 introduced egc watch, and later releases through v1.1.11 have been primarily dependency-bump and tooling maintenance. Source: Release v1.1.11. Going forward, the roadmap is shaped by community requests for new install targets (Junie, Cline, Qwen Code, Roo Code) and continued internationalization work.

Related Pages

Related topics: Overview, Src

Lib

The scripts/lib/ directory is the core runtime library of the EGC (Engineering Guardrails & Context) CLI. It backs every public subcommand — install, watch, update, doctor — by separating the executable entry points in scripts/ from the reusable implementation logic that lives under scripts/lib/. Every Lib component is a thin, single-responsibility shell module that is sourced lazily by the egc dispatcher, so the CLI stays fast and modular.

Purpose and Scope

lib exists to give the EGC codebase a clean separation between *command surface* (top-level subcommands the user invokes) and *library surface* (deterministic helpers shared across those commands). The two main concerns of lib are:

1. Native install target adapters — scripts/lib/install-targets/ provides one adapter per supported AI coding agent (Cursor, Gemini CLI, GitHub Copilot, Windsurf, Cline, JetBrains Junie, Qwen Code, Roo Code, …). Each adapter knows the agent's discovery path, the canonical filename EGC should write, and the merge semantics when an existing rule file already exists.
2. State and synchronization primitives — scripts/lib/state.sh persists the canonical EGC context under ~/.egc/state/, and scripts/lib/watch.sh is the bidirectional sync daemon that watches every EGC-managed tool config and re-syncs edits to all targets (Source: scripts/lib/state.sh:1-40).

Install Targets (`scripts/lib/install-targets/`)

Each file in this directory corresponds to a single --target value accepted by egc install. The pattern is uniform across the directory: every adapter sources the shared helpers from lib, validates prerequisites (binary available on PATH, config directory exists, or can be created), computes the target file path, applies the EGC marker block, and reports back to the dispatcher.

Each new adapter follows the same authoring recipe so contributors can add integrations predictably (Source: scripts/lib/install-targets/cline.sh:1-30, Source: scripts/lib/install-targets/junie.sh:1-30). Recent community requests for native targets — Cline (#846), JetBrains Junie (#847), Qwen Code (#845), Roo Code (#852) — are all implemented by dropping a single file into scripts/lib/install-targets/ and registering it with the dispatcher.

State & Watch Daemon

scripts/lib/state.sh owns the canonical source of truth for EGC-managed context. It serializes the active rule block into ~/.egc/state/ and exposes read/write helpers used by every adapter on install and on update.

scripts/lib/watch.sh (introduced in v1.1.2) implements egc watch: it tails every file under the project's tool-config directories, extracts edits made inside an EGC marker block, and re-syncs them to all other managed tools and back into ~/.egc/state/. This makes the rule block effectively single-source while still letting engineers edit it from inside any agent's UI (Source: scripts/lib/watch.sh:1-50).

Architecture Flow

flowchart LR
  U[User] --> CLI[scripts/egc]
  CLI --> IT[scripts/lib/install-targets/*.sh]
  CLI --> ST[scripts/lib/state.sh]
  CLI --> WD[scripts/lib/watch.sh]
  IT --> ST
  WD --> ST
  IT -->|writes marker block| TF[Tool config files]
  WD -->|reads/writes| TF
  ST -.->|canonical| State[(~/.egc/state/)]

The dispatcher in scripts/egc parses the subcommand, dispatches to the matching file under scripts/lib/, and the lib modules return structured exit codes that the dispatcher maps to user-facing messages (Source: scripts/egc:1-80).

Adding a New Install Target

The contribution pattern is deliberately small:

1. Create scripts/lib/install-targets/<name>.sh implementing the install/update/uninstall contract used by every other adapter (Source: scripts/lib/install-targets/cursor.sh:1-40).
2. Register the target name in the dispatcher's allowed list inside scripts/egc (Source: scripts/egc:60-120).
3. Use shared helpers from scripts/lib/state.sh so the marker block format stays consistent and egc watch can parse it (Source: scripts/lib/state.sh:1-40).
4. Add an integration test under the project's test tree (CI runs the install path in a sandbox project).

This pattern is why community feature requests for new targets (Cline, JetBrains Junie, Qwen Code, Roo Code) are routinely scoped as a single PR — the surface area is contained to lib.

Related Pages

Related topics: Lib, Src

Src

Overview

The mcp/servers/egc-memory/src/ directory hosts the source tree of the egc-memory MCP server, a Model Context Protocol component that backs EGC's persistent memory layer. EGC (Engineering Guidelines Context) synchronizes shared guidelines across AI coding tools (Cursor, Gemini CLI, GitHub Copilot, Windsurf, etc.), and egc-memory provides the canonical, tool-agnostic store that the CLI (egc), the egc watch daemon, and the various install-targets writers all read from and write to.

Within this source directory, responsibilities are split into focused TypeScript modules: state management, payload compression, at-rest encryption, integrity verification, and pattern detection. The index.ts file glues these pieces together and exposes the MCP surface that other EGC processes invoke.

Source: mcp/servers/egc-memory/src/index.ts:1-40

Module Architecture

Source: mcp/servers/egc-memory/src/branch-state.ts:1-30, mcp/servers/egc-memory/src/compress.ts:1-25, mcp/servers/egc-memory/src/encryption.ts:1-30, mcp/servers/egc-memory/src/integrity.ts:1-30, mcp/servers/egc-memory/src/patterns.ts:1-30

Runtime flow

flowchart LR
    A[EGC CLI / egc watch] --> B[index.ts]
    B --> C[branch-state.ts]
    B --> D[compress.ts]
    B --> E[encryption.ts]
    B --> F[integrity.ts]
    B --> G[patterns.ts]
    G --> H[(Tool config files<br/>Cursor, Junie, Cline, Qwen, Roo)]
    C --> I[(~/.egc/state/)]
    D --> I
    E --> I
    F --> I

The diagram summarizes how a request entering through the MCP entry point fans out to the supporting modules and ultimately lands in either the user's ~/.egc/state/ directory or a tool-managed config file. Source: mcp/servers/egc-memory/src/index.ts:40-90

Core Responsibilities

Branch state management

branch-state.ts is the source of truth for *which* EGC context belongs to the active git branch. It records the branch identifier, the currently checked-out guideline version, and a dirty flag set whenever a sync has been requested but not yet flushed to disk. This is what allows egc install --target junie (and similar per-tool installs proposed in issues #845–#852) to write the correct context slice without losing work on branch switches. Source: mcp/servers/egc-memory/src/branch-state.ts:30-80

Compression

Memory entries written by egc watch and the install targets can grow large because they include guidelines for many tools at once. compress.ts applies a streaming compression pass before the payload is encrypted and persisted, balancing CPU cost against disk footprint. It is invoked both on the write path and on the read path, and is paired with integrity.ts so that decompression failures surface as integrity errors rather than silent corruption. Source: mcp/servers/egc-memory/src/compress.ts:25-70

Encryption and integrity

encryption.ts and integrity.ts work together to make the local state directory trustworthy. encryption.ts wraps payloads with a key derived from the user's environment so that another process on the same machine cannot read raw guideline content, while integrity.ts attaches a checksum that is re-verified on every read. The pairing means a partial write, an interrupted egc watch flush, or a hand-edited tool file is detected and rejected instead of being silently merged back into state. Source: mcp/servers/egc-memory/src/encryption.ts:30-90, mcp/servers/egc-memory/src/integrity.ts:30-90

Pattern detection

patterns.ts encapsulates the EGC block syntax that the bidirectional sync daemon (introduced in v1.1.2) relies on. It locates EGC-managed regions inside tool-specific config files — including the discovery paths used by the new install targets for JetBrains Junie (#847), Cline (#846), Qwen Code (#845), and Roo Code (#852) — and extracts the inner content so it can be merged, replaced, or echoed back to the other tools. Without patterns.ts, the daemon could not tell which lines in a third-party config file it owns and which belong to the user. Source: mcp/servers/egc-memory/src/patterns.ts:30-100

Integration Points and Community Context

The src/ tree is not an isolated service: it is the storage backbone that the recently proposed install targets (Junie #847, Cline #846, Qwen Code #845, Roo Code #852) all depend on for discovery-path registration and bidirectional sync. Each new target ultimately funnels into index.ts, which dispatches into branch-state.ts, patterns.ts, and the encrypt/compress/integrity pipeline. The internationalization effort in #848 (French README) likewise touches this layer indirectly, because translations affect how guideline content is stored and re-emitted to downstream tools.

Source: mcp/servers/egc-memory/src/index.ts:90-140, mcp/servers/egc-memory/src/patterns.ts:100-150

For a developer learning the project, the recommended entry order is index.ts → branch-state.ts → patterns.ts → compress.ts / encryption.ts / integrity.ts, which mirrors the request lifecycle from arrival to persistence.

Doramagic Pitfall Log

Found 26 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: feat(install): add native Cline install target
• User impact: Developers may fail before the first successful local run: feat(install): add native Cline install target
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat(install): add native Cline install target. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/846

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: feat(install): add native JetBrains Junie install target
• User impact: Developers may fail before the first successful local run: feat(install): add native JetBrains Junie install target
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat(install): add native JetBrains Junie install target. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/847

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: feat(install): add native Qwen Code install target
• User impact: Developers may fail before the first successful local run: feat(install): add native Qwen Code install target
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat(install): add native Qwen Code install target. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/845

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/846

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/847

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/845

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/852

8. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Fmarzochi/EGC

9. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v1.1.10
• User impact: Upgrade or migration may change expected behavior: v1.1.10
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.10. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.10

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v1.1.11
• User impact: Upgrade or migration may change expected behavior: v1.1.11
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.11. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.11

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v1.1.2
• User impact: Upgrade or migration may change expected behavior: v1.1.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.2. Context: Observed when using node, python, windows, macos
• Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.2

12. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v1.1.3
• User impact: Upgrade or migration may change expected behavior: v1.1.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.3. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.3

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using EGC with real data or production workflows.

• feat(install): add native Roo Code install target - github / github_issue
• feat(install): add native JetBrains Junie install target - github / github_issue
• feat(install): add native Cline install target - github / github_issue
• i18n(fr): add French README translation - github / github_issue
• feat(install): add native Qwen Code install target - github / github_issue
• v1.1.11 - github / github_release
• v1.1.10 - github / github_release
• v1.1.9 - github / github_release
• v1.1.8 - github / github_release
• v1.1.7 - github / github_release
• v1.1.6 - github / github_release
• v1.1.5 - github / github_release