Requires Node.js 20 or later. Node.js 24 LTS is recommended.
npm install -g @egchq/egc
egc installThat's it. The installer detects which AI tools you have installed and configures all of them automatically.
Note: 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. See TROUBLESHOOTING.md for details.
Permissions: if
npm install -gfails withEACCES(typical when Node comes from your distro's package manager or a system-wide installer and the global npm prefix is root-owned, as on a stock Ubuntu withaptNode or a Homebrew Node on macOS), the clean fix is a user-writable prefix: a Node version manager (mise, nvm, asdf, fnm) or a custom npm global prefix under your home directory, as described in TROUBLESHOOTING.md. If you would rather keep the system Node,sudo npm install -g @egchq/egcworks as a one-off; runegc installand everything after it without sudo, so the files EGC writes under your home stay owned by you.
The bare install prepares the runtime only. To have your AI tools restore project memory on their very first prompt, continue with stage 2 below: cd into a project and run egc init once.
If VS Code is your primary editor, install the GitHub Copilot Chat extension first. Inline autocomplete alone is not enough: Copilot needs the chat extension to discover and use EGC skills.
Then install the Copilot target:
npm install -g @egchq/egc
egc install --target copilotThe Copilot target installs EGC skills under ~/.copilot/skills/, one of the directories VS Code Copilot reads personal skills from, so it discovers them automatically. An install made before this change left them under ~/.github/skills/, which VS Code does not read; the next egc install --target copilot (or egc auto-update) moves the copies EGC wrote and leaves your own files there alone.
Memory is shared across EGC 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.
npm install -g @egchq/egc
egc install --target zedThis installs EGC's skills into ~/.config/zed/. It does not register the MCP servers: --target <tool> only ever installs skills and rules.
To get egc-guardian and egc-memory into Zed's context_servers, run the installer or egc init instead. Both detect Zed and write to ~/.config/zed/settings.json with paths resolved at install time:
egc initThese three were retired on 2026-08-16 and no longer receive an install. The ids are still recognized, so egc install,
egc doctor, egc repair and egc auto-update explain the retirement instead of failing on an id that used to be valid.
Nothing is written to ~/.continue/, to ~/.gemini/ for the standalone Gemini CLI, or to the Roo Code settings any more.
Antigravity, the replacement for Gemini CLI, lives under the same ~/.gemini/ home: egc init registers the EGC servers
in ~/.gemini/config/mcp_config.json, the file the Antigravity CLI, the Antigravity IDE and Antigravity 2.0 all read.
EGC setup has three distinct stages. You can stop after the stage that matches what you need.
egc installThis prepares the core runtime, initializes the shared state store, and registers the MCP servers in detected tools. A bare install does not create managed target install-state files, so egc doctor may report that none exist. That is expected, not an error.
The prompt library (agents, skills, commands and rules) is optional and off by default: at an interactive terminal the bare install asks whether to add it, and an empty answer means no. egc install --prompt-library adds it to every detected tool without asking (a full profile per tool, which does create the managed install-state files that egc doctor and egc repair track), egc install --no-prompt-library skips the question (CI, provisioning), and a headless run skips it with a note that names the flag. The two flags cannot be combined.
The dashboard starts right after this stage when you are at an interactive terminal. A headless run (CI, or output redirected to a file) skips it and prints Dashboard not started (headless environment). Run 'egc dashboard' to start it. instead.
Run this from the root of a project you want EGC to manage:
egc initThis bootstraps the cognitive protocol, registers MCP servers, configures project-local memory protections, verifies the setup, and starts the dashboard.
Each of those steps is one check line: cognitive protocol says how many tools carry the current protocol and names the ones it installed or upgraded, MCP registration says how many tools already had the servers and names the ones it wrote, memory reports the state store with its migration count, and commit-privacy filter lists what it changed in the repository the first time and reports the filter as configured afterwards. A detail line appears only when something changed, was skipped or failed.
After those steps egc init prints a short install check, then the dashboard line, then the closing line: Installation complete., or the same line with the number of warnings, or Installation finished with N errors. when something is still broken. When everything is healthy the check is one line (12 targets healthy); when something needs attention, only those targets are listed, each with the command to run. The full report is always one command away with egc doctor. Two status lines above the check tell you whether the state store is ready and whether the Token Crusher shim is on your PATH (the shim is installed by egc install, and a new terminal picks it up).
Install the complete managed content set for a specific target when you want rules, skills, agents, commands, and platform configuration tracked by egc doctor and egc repair:
egc install --target <target> --profile fullegc install --prompt-library does the same for every detected tool at once, without the question: every home target whose config directory or command is present, and Trae and CodeBuddy under the home directory (their project adapters run with the home as the project, the way their former scripts did with ~). Claude Code receives the agents in ~/.claude/agents, the commands in ~/.claude/commands and the rules in ~/.claude/rules, all in the format Claude Code reads.
Use egc catalog to inspect available targets, profiles, and components before installing.
egc uninstall --target <target> removes every managed file that target's install-state recorded (rules, skills, hooks, platform configuration); egc uninstall with no target does that for every install-state in the current context, and --dry-run lists the paths first. Codex, Goose and OpenHands install into the same ~/.agents folder, so uninstalling one of them leaves the files the others still use and says how many it kept; the last of them to be uninstalled removes them. Two things stay on purpose: the shared state store in ~/.egc (memory, savings ledger, sessions), and the cognitive protocol block the bare install writes into ~/.gemini/GEMINI.md, which no install-state tracks. Delete those by hand for a clean slate, then remove the package itself:
npm uninstall -g @egchq/egcOptional dependency:
uvis required only for the Jira and omega-memory MCP servers. Core EGC installation and all other targets are unaffected whenuvis not installed.
Not sure if you have Node.js 20? Run node --version. If it shows 20 or higher, you're ready.
git clone https://github.com/Fmarzochi/EGC.git
cd EGC
sh scripts/install.sh- Compiles the MCP servers (
egc-guardian,egc-memory) - Initializes the local SQLite database
- Runs the cognitive bootstrap: writes the memory protocol into
~/.claude/CLAUDE.md,~/.gemini/GEMINI.md, and equivalent files for each detected tool
Note: the standalone Gemini CLI stopped serving on June 18, 2026 and was retired from EGC on August 16, 2026. The
~/.gemini/tree EGC still writes belongs to Antigravity, not to that CLI. For free-tier users, Antigravity CLI is the recommended alternative: EGC supports it viaegc install --target antigravity.
- Registers both MCP servers in every detected tool's config file
- Asks whether to install the prompt library (61 agents, 232 skills, 77 commands), default no;
--prompt-libraryanswers yes without asking,--no-prompt-libraryskips the question, and a headless run (CI) skips it with a note - Installs the Token Crusher binary shim (
~/.egc/bin): a best-effort, non-fatal step, see Token Crusher below
EGC install
node v22.0.0
npm 10.0.0
Optional dependency not found: uv
Required only for Jira and omega-memory MCP servers.
Core EGC installation is unaffected. Install: https://docs.astral.sh/uv/
installing root dependencies...
building egc-guardian...
building egc-memory...
initializing database...
bootstrapping cognitive protocol...
[cognitive] Claude Code: memory protocol installed (~/.claude/CLAUDE.md)
[cognitive] Antigravity (Gemini home): memory protocol installed (~/.gemini/GEMINI.md)
registering MCP servers...
✓ registered egc-guardian in Claude Code (user scope)
✓ registered egc-memory in Claude Code (user scope)
✓ registered in Cursor (~/.cursor/mcp.json)
Install prompt library? (61 agents, 232 skills, 77 commands) [y/N]:
Installing Token Crusher binary shim...
Shim directory: ~/.egc/bin
Installed: git, npm, gh, ...
Installation complete.
EGC Dashboard starting at http://localhost:7890
Re-check anytime with 'egc doctor'.
Only the tools you actually have are touched, so your own output will be
shorter or longer than this one. Claude Code is registered through its own
CLI (claude mcp add -s user), which is why those two lines name the
servers individually. In a headless environment (CI, or output piped to a
file) the dashboard line is replaced by Dashboard not started (headless environment). Run 'egc dashboard' to start it.
git clone https://github.com/Fmarzochi/EGC.git
cd EGC
.\scripts\install.ps1- Node.js: install from nodejs.org. Confirmed working with Node.js v24 + PowerShell 5.1 and WSL2.
- Antigravity CLI on Windows: if the
irm | iexinstall script hangs silently, use the direct binary download instead:Invoke-WebRequest -Uri https://antigravity.dev/install/agy.exe -OutFile agy.exe
- Antigravity free tier: the starter quota is limited. Expect to exhaust it within a few exchanges. Upgrade or use Claude Code / Cursor for longer sessions.
- Gemini CLI: stopped serving June 18, 2026 and retired from EGC on August 16, 2026. Antigravity is the replacement.
- Upgrading with
npm install -g @egchq/egc@latest: close the AI tools and terminals that run EGC first. npm renames the package folder during the update, and Windows refuses the rename while any process holds a file inside it (an AI tool running the EGC MCP servers, a terminal with a hook mid-run). The failure readsEBUSY: resource busy or lockedon a path undernode_modules\@egchq\egc. A reboot clears the lock too. See Troubleshooting.
egc doctorThis compares every managed file EGC installed against the source it came from, reporting drift, missing files, and version mismatch per target. It also checks the state store: where it lives, whether the memory store exists yet, and whether older versions left stray copies behind.
EGC can send anonymous usage data to help improve the project. This is opt-in: you will be asked once on the first run of egc install, egc init, or egc doctor.
What is sent: EGC version + OS platform only. No project data, no file contents, no identifiers.
How to disable at any time:
egc telemetry offor delete ~/.egc/telemetry.json.
How to check your current setting:
egc telemetry statusThe dashboard starts automatically after egc install and egc init, whenever you are at an interactive terminal. Headless environments (CI, or output redirected to a file) skip it and say so.
You can control it manually:
egc dashboard # start the dashboard server
egc dashboard stop # stop it
egc dashboard status # check if it is runningThe local server is available at http://localhost:7890. It streams everything your AI does in real time: tool calls, file edits, shell commands, token usage, cost per session, and agent status, across every IDE you have running.
What you see:
| Widget | What it shows |
|---|---|
| Active agents | Which IDEs are online right now |
| Tool calls | Every tool invocation as it happens |
| Token usage | Input / output / cache per session |
| Cost | Real-time spend estimate (Claude only) |
| Memory state | Decisions, lessons, and patterns saved this session |
Cost tracking requires the Claude provider. Other IDEs show token usage where available.
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 even inside compound commands. Every prompt is also routed against the component catalog so the right skills and agents are injected into context. If the validator is ever missing, hooks fail open so you are never locked out of your own tool.
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: say you are done for the night and your state is saved before the AI even answers; greet it the next morning and your next steps are already in context. At session end a memory miner distills the session's decisions and lessons into your project state. Without a key these LLM features honestly do nothing, and the lifecycle hooks still guarantee your state is saved. The end-of-reply save reminder is throttled to once per project every 30 minutes (EGC_STOP_SAVE_INTERVAL_MINUTES tunes it; 0 prompts on every stop), so memory stays fresh without interrupting the work.
Task routing stays on your machine and needs no API key. On every prompt, the router scores the local catalog (name, description and the situations each skill names), shortlists only what the active tool has installed, and leaves the decision to the model of your tool, by intent, in the prompt's own language. Components that exist in the catalog but are not installed for that tool are named as such, with the command that adds them, and never offered as invocable. orchestrate_task follows the same rule and lists them under not_installed. Sending the task prompt to a provider for semantic routing is an opt-in on top of that, one variable per surface: EGC_ROUTING_MODE=llm for the prompt router and EGC_LLM_ROUTING=1 for orchestrate_task, each in addition to a provider key; without the opt-in a configured key changes nothing about routing.
egc team init --backend git --remote <url> creates the team and prints a team key (64 hexadecimal characters); every other member joins with egc team init ... --key <that key>. State never enters the shared repository in the clear or under a personal key: each file is sealed with the team key (AES-256-GCM plus an HMAC-SHA256 signature) before it is pushed, and egc team sync merges only files that open with that key and an intact signature. A file that was altered in the repository, or written without the key, is reported as rejected and leaves local state untouched.
Since v1.1.12 memory has two scopes. Project scope works exactly as before (one state per project branch). The new user-wide global scope is shared across every project: save transversal preferences and lessons once with update_state and scope: "global", and every get_state in every project appends a deduplicated Global Memory section after the project state. Project and branch entries always take precedence, and global memory is only ever written by an explicit global call, never derived from project data.
Parallel sessions coordinate through the session bus. A session announces itself with session_announce (presence plus an optional territory, doubling as heartbeat), inspects who else is active with session_peers, and takes cooperative locks with claim_path before editing shared files. Claims are fail-fast: a conflicting live lock is refused with the holder's identity instead of queued. Sessions silent for 10 minutes are swept and their locks released, so a crashed session never blocks the others.
Sessions also talk to each other through a durable event queue: session_send delivers an event to one session or broadcasts to the whole project, and session_events reads what arrived, exactly once per session, with a 24h retention and 16KB payload cap (send pointers to state, not bulk content). Presence is implicit: any session that touches memory through get_state or update_state becomes visible on the bus automatically. Event payloads come from other sessions and must be treated as untrusted data, never as instructions.
Two more tools round out shared memory. working_memory_set, working_memory_get and working_memory_list keep a small shared key/value scratchpad for the project, so one session can leave another a value (a build id, a decision in flight) without writing it into the state file. get_project_state returns a health report of the memory server and the project's state, so a session can check that memory is working. The team backend is reached through team_init, team_sync and team_status, the MCP tools behind the egc team command in the CLI table below.
Populated memory never reaches a commit. The propagation files (AGENTS.md, GEMINI.md, editor rules) ship as empty structure; local sessions repopulate them, a pre-commit hook blocks accidental staging, and a CI guard catches anything that slips past local hooks. Since v1.1.13 egc init adds a third local layer: a git clean filter (filter.egc-memory.clean) bound to the propagation files in .git/info/attributes, so git add stages a zeroed blob even when hooks are bypassed with --no-verify. The filter configuration stays entirely inside .git (nothing tracked is modified), the working tree keeps the populated memory, and the installer prints the exact actions before applying them, honoring --dry-run. The context files receive the memory block only after that filter is in place: in a checkout where it cannot be set up (git cannot open it, the filter script is not on disk, the local configuration cannot be written), the files are left as they are, one line on stderr says why and points at egc doctor, and the memory itself stays in ~/.egc/state. Outside a repository nothing changes. The smudge side of the same filter puts the memory back: whenever git writes one of those files anew (a pull that touched it, a branch switch, a stash pop), the block is rebuilt from ~/.egc/state, so the working tree never loses it and the file reads as unmodified afterwards; where the state cannot be read, or the script is gone, the file comes out as committed and the checkout goes on. The clean side zeroes the llms.txt form of the block as well.
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%, while errors, warnings and failures always survive. It ships with the package, announces itself once at the end of egc init, and stays silent afterwards.
egc run git log # any command, crushed output
egc run --raw git log # escape hatch: full output
egc saved # accumulated savings report, computed locally at zero token cost
egc gain # full savings panel: totals, efficiency meter, breakdown by command kind
egc gain --history # the run-by-run savings log
egc discover # scan recent session transcripts for crushable output that skipped the crusherOn hook-capable harnesses the bash dispatcher routes eligible simple commands through egc run automatically. The rewrite is strictly fail-open: pipelines, chaining, redirection, already-wrapped commands, or a missing egc CLI all pass through untouched. Opt out anytime with EGC_DISABLED_HOOKS=pre:bash:crusher-rewrite.
Known limitation: on Claude Code, that hook rewrite does not fire for commands the AI assistant itself runs through the Bash tool. It fires only for a human typing directly into the terminal. This is a confirmed, permanent gap in how Claude Code's PreToolUse hook applies to assistant-issued commands, not an EGC bug.
To cover that gap, egc install and egc auto-update also install a PATH-level binary shim under ~/.egc/bin, covering git, npm, pnpm, yarn, bun, pip, pip3, poetry, pipenv, uv, composer, bundle, and gh: small launcher files that sit ahead of the real binaries on PATH and route through the same compression engine. Because it works via normal shell PATH resolution, it compresses output for any caller (a human, this AI, or another tool entirely), regardless of hook support. It requires a new shell session after install to pick up the PATH change. Manage it directly with:
egc crusher-shim install # add the shim to ~/.egc/bin and your shell's PATH
egc crusher-shim status # check whether it's installed and active in this shell
egc crusher-shim uninstall # remove itThe Scrubber removes AI provenance marks from content you own, automatically. On hook-capable harnesses it registers a PreToolUse hook at egc init (the same way the Token Crusher and Guardian do), so files are cleaned as they are written: invisible Unicode carriers (zero-width family, BOM, tag characters, variation selectors, and more) and long dashes are stripped, while the invisibles that carry meaning (emoji joiners, complex-script joiners, flag tags, RTL marks) are preserved. A commit hook removes AI co-authorship from commit messages while keeping human co-authors.
An opt-in content-scrubber skill and CLI cover on-demand and batch use, including metadata: they strip AI-provenance metadata from Markdown frontmatter, HTML head and SVG, from PNG and JPEG images, and from PDF Document Info dictionaries. Metadata cleaning is honest about partial coverage: compressed-stream and encrypted cases are reported, never altered.
Everything is pure Node, deterministic, and fail-open: a parse error, an engine error, or binary input passes the original content through untouched, so the Scrubber can never block or corrupt a write. Opt out of the automatic write hook anytime with EGC_DISABLED_HOOKS=pre:scrubber.
You never need to type any of these. Talk to your AI naturally, in any language, and the auto-intuition protocol maps your intent to the right action: saying "how much did I save?" runs the savings report, saying "we are done for today" saves the session. The commands below exist for people who prefer explicit control, and every one of them is valid on its own:
Auto-intuition and provider keys. The protocol lives in each tool's context file, so the AI follows it with no API key. The
UserPromptSubmithook that also acts on your intent by code, before the AI answers (saving the session, injecting next steps or past decisions, recording what you asked it to remember), classifies the prompt with an LLM provider: it detects nothing unlessANTHROPIC_API_KEY,GEMINI_API_KEY(orGOOGLE_API_KEY),OPENAI_API_KEYorOPENROUTER_API_KEYis set, and the lifecycle hooks still save the state at session end. SetEGC_INTUITION_LLM=0to turn the classifier off.
| Command | What it does |
|---|---|
egc init |
First-run bootstrap (cognitive protocol + MCP registration + doctor) |
egc install |
Install EGC content into a supported target; on a bare install, --prompt-library and --no-prompt-library decide the optional library without the question |
egc plan |
Inspect selective-install manifests and resolved plans |
egc catalog |
Discover install profiles and component IDs |
egc consult |
Recommend EGC components and profiles from a natural language query |
egc consolidate |
Compact oversized project state files into layered summaries |
egc list-installed |
Inspect install-state files for the current context |
egc doctor |
Diagnose missing or drifted EGC-managed files |
egc repair |
Restore drifted or missing EGC-managed files |
egc auto-update |
Pull latest EGC changes and reinstall the current managed targets |
egc status |
Query the EGC SQLite state store status summary |
egc overview |
Aggregated read-only view of every per-project memory state |
egc export |
Print the decrypted memory document for a project or the global scope, as text or --json (read-only) |
egc verify |
Run the project verification command and record a receipt for the commit gate |
egc sessions |
List or inspect EGC sessions from the SQLite state store |
egc replay |
List or replay recorded sessions with timeline scrubbing |
egc prompt |
Execute an LLM prompt via the Gemini backend (EGC Bridge) |
egc session-inspect |
Emit canonical EGC session snapshots from dmux or Gemini history targets |
egc loop-status |
Inspect transcripts for stale loop wakeups and pending tool results |
egc uninstall |
Remove EGC-managed files recorded in install-state |
egc watch |
Watch one project's tool config files and sync state changes bidirectionally: the current directory, or the path given as an argument or with --project |
egc telemetry |
Manage anonymous usage telemetry (status, on, off) |
egc dashboard |
Start the EGC Dashboard (stop and status as sub-args) |
egc team |
Team memory sync: init, sync, or status |
egc budget |
Budget guardian: set, status, reset token and cost limits per session |
egc plugin |
Plugin registry: install, list, remove, update EGC plugins |
egc run |
Run a command through the Token Crusher (--raw skips compression) |
egc saved |
Accumulated Token Crusher savings, short summary |
egc gain |
Full savings panel (--history for the run-by-run log) |
egc discover |
Scan recent session transcripts for crushable output that skipped the crusher |
egc crusher-shim |
Install, uninstall or check the PATH-level Token Crusher binary shim for tools without hook support |
egc claw |
NanoClaw REPL: persistent session-aware agent loop with Markdown history |
egc harness-audit |
Score the harness setup across tool coverage, quality gates, memory, and security |
egc doctor, egc repair, and egc auto-update all accept --repo-root <path>, pointing them at a local development checkout instead of wherever the running egc binary was installed from. Without it, they compare your managed files against the published npm package, which reports every unreleased change as missing or drifted. Pass a --repo-root pointing at your local checkout when running any of these three commands so all agree on the source of truth.
egc auto-update only runs a real git pull when the install directory has a .git folder (i.e. you installed via git clone, not npm install -g). On a git-based install, auto-update pulls straight from origin/main, so a fix that has merged but not yet been published as an npm release still reaches you. On an npm-only install, there is no repository to pull from: auto-update prints a reminder to run npm install -g @egchq/egc@latest, which only helps once a new version has actually been published. On Windows, close the AI tools and terminals that run EGC before that command, or npm fails with EBUSY on a file it cannot rename (see the Windows notes above). If you need a fix that is on main but not yet released, git clone + sh scripts/install.sh (or .\scripts\install.ps1) is the reliable path, not npm install -g.
See TROUBLESHOOTING.md for common issues including permission errors, Node.js version mismatches, and manual MCP registration steps.