Skip to content

Installation

Jump to bottom
Felipe Marzochi edited this page Oct 10, 2026 · 8 revisions

Installation

Via npm (recommended)

Requires Node.js 20 or later.

npm install -g @egchq/egc
egc install

The installer detects which AI tools you have installed and configures all of them automatically.

If you use a Node.js version manager (mise, nvm, asdf, fnm), install EGC under your default Node version, the one active outside any project directory. Installing it under multiple Node versions causes version conflicts.

If npm install -g fails with EACCES (a root-owned global npm prefix, typical with a distro-packaged Node), the clean fix is a user-writable prefix: a Node version manager or a custom npm global prefix under your home directory. Since v1.1.21, egc install also survives a root-owned prefix after sudo npm install -g: a read-only server directory is confirmed and skipped with a note instead of ending in a bare exit code.

On hosts whose glibc is too old for the prebuilt native sqlite3 binary (Debian 12, Ubuntu 22.04 and similar), both MCP servers fall back to the portable sql.js engine behind the same API, persisted to the same file, with a one-line notice. EGC_SQLITE_ENGINE=native|wasm pins either engine.

Project setup

Run this once from the root of each project you want EGC to manage:

egc init

This bootstraps the cognitive protocol, registers the MCP servers, configures project-local memory protections, verifies the setup, and starts the dashboard when you are at an interactive terminal.

Up to 1.1.21 egc init ended with the full doctor report. Since 1.1.22 (#1384) the run ends with a compact install check instead: a healthy install is one line (12 targets healthy), only targets that need attention are listed, each with the exact command to run, and Installation complete. is the last line. The full report stays one command away with egc doctor.

VS Code + GitHub Copilot

Install the GitHub Copilot Chat extension first, then:

npm install -g @egchq/egc
egc install --target copilot

This installs EGC skills under ~/.github/skills/, which VS Code Copilot discovers automatically. Memory is shared across targets: context saved while using Copilot is the same state used by Claude Code, Cursor, Antigravity, Devin Desktop, and the rest of the supported tools.

Zed

npm install -g @egchq/egc
egc install --target zed

The target installs skills under the shared ~/.agents/skills/ (the only global directory Zed reads) and the bootstrap into ~/.config/zed/AGENTS.md. The MCP servers reach Zed's context_servers in ~/.config/zed/settings.json through egc init or the shell installers, which detect Zed on their own.

Linux / macOS (from source)

git clone https://github.com/Fmarzochi/EGC.git
cd EGC
sh scripts/install.sh

The script re-executes itself under bash when sh is dash and stops with a plain message when bash is missing.

What the installer does

  1. Compiles the MCP servers (egc-guardian, egc-memory)
  2. Initializes the local SQLite database
  3. Runs the cognitive bootstrap: writes the memory protocol into ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md (Antigravity's home), and equivalent files for each detected tool
  4. Registers both MCP servers in every detected tool's config file
  5. Asks whether to install the prompt library (agents, skills, commands) at an interactive terminal, default no; --prompt-library answers yes, --no-prompt-library skips the question, and CI never sees the prompt (v1.1.22)

Gemini CLI, Continue.dev, and Roo Code were retired from the install package in v1.1.19 after their vendors discontinued them. Antigravity succeeds Gemini CLI on the same ~/.gemini home: egc install --target antigravity.

Windows

git clone https://github.com/Fmarzochi/EGC.git
cd EGC
.\scripts\install.ps1

Notes:

  • Install Node.js from nodejs.org. Confirmed working with Node.js v24 plus PowerShell 5.1 and WSL2.
  • If the Antigravity CLI install script hangs silently, use the direct binary download: Invoke-WebRequest -Uri https://antigravity.dev/install/agy.exe -OutFile agy.exe
  • Antigravity's free tier has a limited starter quota; expect it to run out within a few exchanges. Use Claude Code or Cursor for longer sessions.

Verify the install

egc doctor

This checks that both MCP servers are built, registered, and reachable in every detected tool, and that every managed file is present and unchanged. egc repair restores drifted or missing files.

Telemetry

EGC can send anonymous usage data to help improve the project. This is opt-in: you are asked once on the first run of egc install, egc init, or egc doctor.

What is sent: EGC version and OS platform only. No project data, no file contents, no identifiers.

egc telemetry off      # disable at any time
egc telemetry status   # check current setting

Or delete ~/.egc/telemetry.json.

Dashboard

EGC can start a local dashboard server at http://localhost:7890 (or EGC_PORT) that streams tool calls, file edits, shell commands, token usage, cost per session, session bus activity, and agent status across every IDE you have running. It starts automatically after egc install and egc init whenever you are at an interactive terminal; headless runs (CI, or output redirected to a file) skip it and say so.

egc dashboard          # start the dashboard server
egc dashboard stop     # stop it
egc dashboard status   # check if it is running

Cost tracking requires the Claude provider; other tools show token usage where available.

Enforcement

Validation does not depend on the AI choosing to cooperate. EGC installs harness hooks that run on every tool call: each shell command and file write is validated before it executes, and destructive commands, credential paths, and force pushes are blocked, including inside compound commands. Every prompt is also routed against the component catalog so the right skills and agents reach the context.

With a provider API key (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY), EGC also understands session intent semantically, in any language, with no predefined phrases. Without a key, these LLM-dependent features do nothing, and the lifecycle hooks still guarantee your state is saved. Task routing stays local (keyword scoring) unless you also opt in with EGC_LLM_ROUTING=1.

Token Crusher

The Token Crusher compresses noisy shell output before it reaches the model: long git log and git diff output, test-runner noise, package-manager installs, and large gh --json payloads shrink by up to 90 percent, while errors, warnings and failures always survive.

egc run git log        # any command, crushed output
egc run --raw git log  # escape hatch: full output
egc saved              # accumulated savings, computed locally
egc gain               # full savings panel (--history for the run log)
egc discover           # find crushable output that skipped the crusher

On hook-capable harnesses the bash dispatcher routes eligible simple commands through egc run automatically (fail-open; opt out with EGC_DISABLED_HOOKS=pre:bash:crusher-rewrite). For tools without hook rewrite support, egc crusher-shim install adds a PATH-level shim covering git, npm, pnpm, yarn, bun, pip, poetry, uv, composer, bundle, gh and friends; it needs a new shell session to take effect.

EGC Scrubber

Since v1.1.21 the Scrubber removes AI provenance marks from content you own, automatically. On hook-capable harnesses a Write/Edit hook registered at egc init strips invisible Unicode carriers and long dashes as files are written, while meaningful invisibles (emoji joiners, complex-script joiners, RTL marks) are preserved; a commit hook removes AI co-authorship trailers while keeping human co-authors. The opt-in content-scrubber skill and CLI cover on-demand and batch use, including metadata in Markdown, HTML, SVG, PNG, JPEG, and PDF files, honest about partial coverage. Everything is pure Node, deterministic, and fail-open. Opt out of the write hook with EGC_DISABLED_HOOKS=pre:scrubber.

Troubleshooting

See docs/TROUBLESHOOTING.md in the repository for common issues including permission errors, Node.js version mismatches, and manual MCP registration steps.

Clone this wiki locally