EDC — Context-Aware Code Review for Pi and AI Agents

EDC builds a local repository architecture map so coding agents stop reviewing blind.

Use it when you want a Pi/Claude/Cursor/Codex agent to understand module ownership, path routing, trust boundaries, invariants, and review scope before it comments on code.

What you get:

• repo map / agent context — generated edc-context/ docs with module boundaries and routing metadata
• context-aware code review — security, delivery/architecture, and quality lenses routed to the right module docs
• local-first workflow — runs from your repo through Pi's /edc menu or the terminal CLI; no remote PR bot required

Works with Pi, Claude Code, Cursor, and Codex.

30-second start

pi install npm:@sgtbeatdown/edc
cd your-repo
pi
# run /edc, choose build context, then choose scope + review lens

First run may write edc-context/, AGENTS.md or EDC_AGENTS.md, local runtime cache .edc/, pi job state under .git/edc/, and review-*.md reports. Generated context is disposable; source remains authoritative. See Generated Files and Local State for details and .gitignore guidance.

Why EDC?

Tool style	Strength	Gap	EDC angle
Cursor rules / Claude memory / AGENTS.md	Simple local guidance	Manual and drifts	Generated, updated, validated context tree
Claude/Cursor/Codex agents	Good at code changes	Start each repo/session mostly blind	Shared repo map before work starts
PR bots	Convenient diff review	Remote, black-box, PR-only	Local inspectable context-aware review
Semantic search / code search	Finds relevant code	Does not encode authority or invariants	Authored module docs with routing and guardrails

What EDC Does

EDC separates deterministic orchestration from LLM analysis:

• Shell scripts own routing, freshness checks, manifest updates, subprocess spawning, and validation.
• Subagents write per-module architecture context and review reports.
• Agent integrations expose the same workflows through native commands, skills, hooks, or pi's interactive menu.

The generated context lives in the target repository under edc-context/: an overview, module docs, routing manifest, build metadata, and audit/review reports. Build it once per repo, then update it from diffs as code moves. Security reviews are routed through the generated manifest so each changed path gets the relevant module context instead of a giant undifferentiated context dump.

Commands

Command	When to run it
build	Once per repo, and after big refactors. Discovers modules and writes edc-context/{index.md, manifest.json, modules/*.md, reports/*, build/build.json} plus a short agent orientation (AGENTS.md, or EDC_AGENTS.md when preserving an existing AGENTS.md).
update	Before review if HEAD has moved. Incremental refresh from a branch diff so you do not rebuild from scratch on every PR.
review full|diff [base]	Runs all lenses: security, delivery/architecture, and quality review.
security full|diff [base]	Runs context-aware security/adversarial review and writes a consolidated review-*.md report.
delivery full|diff [base]	Checks goal/spec delivery and architecture fit, writing delivery-review-*.md.
quality full|diff [base]	Code-quality and maintainability review. Full audits all modules; diff audits modules owning changed files.
doctor	When something feels off. Validates the edc-context/ tree and routing contract.
mode	Shows or toggles runtime context loading mode (advisory or inject).

Terminal CLI

The unified installer (bash install.sh --agent <agent>) places a shared terminal wrapper at ~/.edc/scripts/edc alongside the orchestrator scripts and adds ~/.edc/scripts to your shell PATH when it can detect a zsh/bash rc file. Restart your shell after install, or run export PATH="$HOME/.edc/scripts:$PATH" for the current shell. Pass --no-path to skip rc-file edits.

From any terminal, in the target repo:

# build or update context in the current repo
edc build  --agent claude
edc build  --agent cursor --force
edc build  --agent codex --focus orchestrator
edc build  --agent codex --ignore 'vendor/**' --ignore 'dist/**'
edc update --agent claude              # incremental refresh after HEAD moves

# run all review lenses in the current repo: security, delivery, then quality
edc review full --agent claude
edc review diff --agent pi          # diff vs detected default branch
edc review diff main --agent pi     # diff vs explicit base

# run the security-only review pipeline in the current repo
edc security full --agent claude
edc security diff main --agent cursor
edc security diff origin/main --agent codex --ignore 'generated/**'

# goal/spec delivery + architecture-fit review
edc delivery full --agent claude
edc delivery diff main --agent pi

# code quality / maintainability review
edc quality full --agent claude
edc quality diff main --agent pi

# runtime-mode toggle (used by Claude Code and pi inject/advisory hooks)
edc mode                # show current mode
edc mode advisory       # docs only, hooks no-op
edc mode inject         # auto-load context through supported hooks

# validate the edc-context/ layout
edc doctor

--agent selects which CLI (claude / cursor / codex / pi) drives subprocess fanout, and is mandatory for build, update, review, security, delivery, and quality (not for mode or doctor). Review commands auto-build or auto-update edc-context/ first if it is missing or stale. Use full for the current tracked repo and diff [base] for HEAD versus a base branch; omitted diff base uses the detected default branch. Security review routes files through edc-context/manifest.json: module-mapped files get module context, unexpected unmapped files are reviewed with repo-level context only, and paths matching unmapped.allowedGlobs are intentionally skipped but listed in the final review. Quality diff audits only modules owning changed files; quality full audits all modules. Structured result files include scope/base/target plus dirty/untracked inclusion. success-with-warning means durable outputs validated even though the agent transport reported an odd/nonzero finish. --ignore may be repeated; passing any --ignore flag overrides .edcignore for that run, otherwise .edcignore is read from the repo root.

Install

Claude Code

Recommended — install via the plugin marketplace:

claude plugin marketplace add almogdepaz/edc
claude plugin install edc@edc

Alternative — install the runtime directly from a clone:

bash install.sh --agent claude

Both paths install the plugin surface (slash commands + hooks + skills) and the terminal CLI (~/.edc/scripts/edc). The direct installer also adds a zsh/bash PATH entry when possible; use --no-path to skip shell rc edits.

Cursor

# remote one-liner
curl -fsSL https://raw.githubusercontent.com/almogdepaz/edc/main/install.sh | bash -s cursor

# or from a local checkout
bash install.sh --agent cursor

Codex

# remote one-liner
curl -fsSL https://raw.githubusercontent.com/almogdepaz/edc/main/install.sh | bash -s codex

# or from a local checkout
bash install.sh --agent codex

pi

# npm package
pi install npm:@sgtbeatdown/edc

# project-local install for a team repo
pi install npm:@sgtbeatdown/edc -l

# or from a local checkout
bash install.sh --agent pi

For pi commands, menu behavior, background jobs, modes, requirements, and troubleshooting, see pi/README.md.

Codex auth with the orchestrator

The orchestrator spawns codex exec using your normal Codex configuration by default, so ChatGPT OAuth/API-key login state under ~/.codex is inherited. If you need an isolated Codex home for tests or benchmarks, set:

export EDC_CODEX_HOME=/path/to/isolated/codex-home

When EDC_CODEX_HOME is set, the orchestrator uses it verbatim and does not clean it up.

Agent Commands and Menus

Claude, Cursor, and Codex expose thin wrappers for the same deterministic orchestrators. Pi exposes the workflows through one interactive /edc menu instead of separate slash commands.

Agent	User-facing actions
Claude Code	/edc:edc-build, /edc:edc-update, /edc:edc-run-review, /edc:edc-doctor; methodology skills edc-review, edc-audit, edc-delivery-review
Cursor	/edc-build, /edc-update, /edc-run-review, /edc-doctor; public methodology skills
Codex	$edc-build, $edc-update, $edc-run-review, $edc-doctor; public methodology skills
pi	/edc interactive menu: choose scope first (full repo, changes vs default branch, changes vs custom base), then lens (combined/security/delivery/quality); methodology skills edc-review, edc-audit, edc-delivery-review

Review invocation examples

# terminal CLI
edc review full --agent pi
edc review diff main --agent pi
edc security full --agent claude
edc security diff HEAD~5 --agent claude
# advanced legacy security forms still support PRs, single commits, and patch files:
edc security-review --agent claude --pr 42
edc security-review --agent claude path/to/changes.patch

# Claude slash command equivalent for combined review
/edc:edc-run-review --full
/edc:edc-run-review HEAD --base main

Without --base, a git ref target uses its parent (<target>^) as the base, which reviews only that commit. To review a branch against main, pass --base main. For PR numbers, PR URLs, or patch files, use the explicit security-only command (edc security-review --agent <agent> ...) because delivery and quality phases require a git diff scope. Use --ignore-context for a pure direct security review with no context build/update and no reads from existing edc-context/; use --no-context-refresh to skip creation/update while still allowing existing context if present.

Runtime Modes

EDC stores runtime mode in edc-context/manifest.json as policy.defaultMode.

• advisory (default) — pure docs. Hooks no-op. Agents read edc-context/index.md and relevant edc-context/modules/<name>.md when prompted by a command/menu or by the user. Zero token overhead per tool call.
• inject — auto-loaded context for supported integrations. Session start surfaces edc-context/index.md; before Edit/Write/Bash/tool-call paths, EDC resolves the file through manifest.json and injects the matching module doc once per session.

Toggle from a target repo after context exists:

edc mode
edc mode advisory
edc mode inject

Cursor and Codex are docs-only regardless of the mode flag. Claude Code and pi support injection.

Generated Files and Local State

EDC writes generated context and local runtime state in a few places:

• edc-context/ — generated per-module deep context written by build/update; review task IPC lives under edc-context/review-tasks/. This directory is disposable: recovery may wipe and rebuild it.
• AGENTS.md / EDC_AGENTS.md — short generated orientation pointing agents at edc-context/. If a repo already has a non-EDC AGENTS.md, non-pi builds preserve it, write EDC_AGENTS.md, and explain how to replace, append, or reference it. Set EDC_AGENTS_MODE=overwrite to replace AGENTS.md.
• review-*.md — consolidated review output.
• .edc/ — project-local runtime copy used by hooks/extensions when they need deterministic access to orchestrator scripts and private prompt bundles. Global installs also live under ~/.edc/.
• .git/edc/status and .git/edc/<kind>.log — pi's current background job status/logs. These are git metadata files, not worktree files, and need no .gitignore entry.

For repos where you do not want generated EDC artifacts tracked, add:

AGENTS.md
EDC_AGENTS.md
edc-context/
review-*.md
.edc/

If generated context or review outputs get committed, edc review filters them out of diffs automatically so the tool does not review its own output, but you will still usually want them ignored to keep history clean.

Repo Structure

edc/
  install.sh                           # one-line installer for all agents
  AGENTS.md / EDC_AGENTS.md            # generated agent entrypoint/orientation
  .claude-plugin/marketplace.json      # Claude plugin marketplace manifest
  plugins/edc/                         # plugin, skills, hooks, and shared orchestrators
    commands/                          # user-facing Claude slash commands
    skills/                            # user-facing methodology skills
    prompt-bundles/                    # hidden prompt bundles for orchestrator subprocesses
    scripts/                           # everything that ships to ~/.edc/scripts/
    hooks/                             # Claude hook surface + shared JS runtime helpers
  pi/                                  # pi package surface, docs, extension, and installer
  tests/hardening/                     # shell/Node regression tests
  benchmark/                           # CVE recall and review benchmark harnesses

Cursor and Codex have no in-repo runtime source beyond installer templates. Their wrappers are emitted by install.sh into ~/.cursor/commands/ and ~/.codex/skills/, and delegate to the orchestrators under ~/.edc/scripts/.

For implementation details, see plugins/edc/README.md. For generated architecture context, see edc-context/index.md after running edc build.