EPX (ExplainX Package Exchange)

EPX is an open-source package manager for reusable AI assets. In Phase 1, GitHub repositories are the registry: no account or backend is required.

Usage

Every EPX command starts with the ExplainX ASCII banner. The banner is written to stderr so structured stdout, including epx audit --json, remains pipe-safe.

epx add whyashthakker/react-review
epx add whyashthakker/react-review --codex
epx add whyashthakker/react-review --target codex claude-code
epx add anthropics/skills --skill frontend-design --codex
epx add anthropics/skills --skill frontend-design --all-agents
epx add owner/ai-rules --rule typescript
epx add owner/ai-rules --rule typescript --codex --claude-code --cursor
epx add owner/ai-rules --rule typescript --all-agents
epx prompt add microsoft/vscode find-duplicates
epx cmd add iannuttall/claude-sessions session-help --codex --claude-code --cursor
epx list
epx update
epx remove react-review
epx validate
epx audit
epx audit react-review
epx mcp add https://mcp.upstox.com/mcp
epx agent add github/awesome-copilot
epx instruction add owner/repo
epx template add owner/repo
epx context add owner/repo
epx mcp add https://mcp.upstox.com/mcp --codex --claude-code --cursor

Running epx add <owner/repo> in a terminal opens an interactive agent and scope picker. Universal agents always share .agents/skills. Type to search additional agents, use the arrow keys to move, Space to select, Ctrl+A to select all, Enter to confirm, and Escape to cancel cleanly. Pass --codex, --claude-code, --cursor, --target <agent...>, or --all-agents to skip the agent picker. Add --global for a user-wide installation; otherwise assets are installed in the current project.

Universal agents—including Codex and Cursor—use .agents/skills/<name>. Additional agents use their native directories, such as .claude/skills/<name> for Claude Code. The agent registry follows the destinations supported by the Vercel Labs Skills CLI.

Repositories without epx.yaml are also supported when they use the conventional SKILL.md layout, either at the repository root or under skills/<name>/SKILL.md. If several skills are present and none matches the repository name, select one with --skill <name>.

Universal rules

Install one rule from a GitHub repository and use it across multiple AI coding agents:

epx add owner/repo --rule typescript

The interactive picker currently supports native rule installation for Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Cline, Roo Code, and Windsurf. Use arrows to move, Space to select, Ctrl+A to select every compatible agent, and Enter to install. Skip the picker with agent flags or --all-agents:

At least one target agent must be selected. Confirming with no selected agents cancels the target installation while retaining the audited canonical package in ~/.epx/packages.

epx add owner/repo --rule typescript --codex --cursor
epx add owner/repo --rule typescript --all-agents

EPX discovers conventional rules from rules/, .cursor/rules/, .claude/rules/, .github/instructions/, .windsurf/rules/, .roo/rules/, and .clinerules/, as well as .cursorrules, AGENTS.md, CLAUDE.md, and GEMINI.md. If a repository contains exactly one rule, epx add owner/repo detects it automatically. When several rules exist, EPX opens a searchable rule picker. Use arrows to move, Space to select multiple rules, Ctrl+A to select all, Enter to confirm, or Escape to cancel. Pass --rule <name> to install one known rule without opening the rule picker.

EPX keeps the downloaded canonical rule under ~/.epx/packages/<name>/rules and generates the native target format. For example, Cursor receives .cursor/rules/<name>.mdc, Claude Code receives .claude/rules/<name>.md, Copilot receives .github/instructions/<name>.instructions.md, and Codex receives an idempotent EPX-managed section in AGENTS.md. Existing content outside an EPX-managed section is preserved.

Installed packages and the local registry live in ~/.epx. Set EPX_HOME to use another location.

Commands and prompts

Install reusable commands or prompts from GitHub:

epx cmd add owner/repo create-pr
epx prompt add owner/repo code-review

Use the separate epx cmd add and epx prompt add namespaces so repositories containing several kinds of AI assets are never misclassified. When a repository contains multiple commands or prompts and no name is supplied, EPX opens the searchable multi-select picker. Selected assets can be installed for Codex, Claude Code, Cursor, GitHub Copilot, and Gemini CLI. EPX detects commands/, prompts/, .claude/commands/, .cursor/commands/, .gemini/commands/, .github/prompts/, and .codex/prompts/. It writes Markdown for Codex, Claude Code, and Cursor, .prompt.md for Copilot, and valid command TOML for Gemini CLI.

Custom agents and subagents

Discover and install custom agents from GitHub:

epx agent add github/awesome-copilot
epx agent add github/awesome-copilot prompt-builder --copilot
epx agent add owner/repo security-reviewer --all-agents

EPX detects agents recursively under agents/, .github/agents/, .claude/agents/, and .gemini/agents/. Omitting the name opens the searchable multi-select picker. The first release targets Claude Code, GitHub Copilot, and Gemini CLI. EPX preserves the agent instructions and description but deliberately removes source-specific tool and model declarations during conversion so installing an agent cannot silently broaden permissions on another client.

Instructions, templates, and context packs

Install persistent instructions without colliding with skill or prompt detection:

epx instruction add owner/repo
epx instruction add owner/repo security --all-agents

Instruction discovery supports instructions/, rules/, .github/instructions/, .cursor/rules/, .claude/rules/, root AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md. It uses the same native conversion and managed-file behavior as universal rules.

Template repositories use templates/<name>/. EPX copies the selected template into the current directory and refuses the entire installation if any destination file already exists:

epx template add owner/repo
epx template add owner/repo nextjs

Context repositories use contexts/<name>/, context/<name>/, or knowledge/<name>/. EPX stores packs under .agents/context/<name>/ and adds idempotent managed references to the selected AGENTS.md, CLAUDE.md, or GEMINI.md files:

epx context add owner/repo
epx context add owner/repo architecture

MCP servers

Install a remote Streamable HTTP or SSE MCP URL and select the clients that should receive it:

epx mcp add https://mcp.upstox.com/mcp

Use the searchable picker or skip it with flags:

epx mcp add https://mcp.upstox.com/mcp --codex --claude-code --cursor
epx mcp add https://mcp.upstox.com/mcp --all-agents
epx mcp add https://example.com/mcp --name example

EPX installs MCP servers globally and merges them without deleting existing settings. User-level installations target ~/.codex/config.toml, ~/.claude.json, ~/.cursor/mcp.json, ~/.gemini/settings.json, and VS Code's platform-specific user mcp.json for Codex, Claude Code, Cursor, Gemini CLI, and GitHub Copilot respectively. Restart the selected client after installation so it reloads its MCP configuration. Remote OAuth is completed by the selected client when it first connects; EPX does not collect or store OAuth tokens.

Package format

An EPX repository has an epx.yaml file at its root and one or more supported asset directories:

react-review/
├── epx.yaml
├── skills/
│   └── review.md
├── rules/
│   └── react-rules.md
└── commands/
    └── review.md

name: react-review
version: 1.0.0
description: React code review assistant
type: skill
targets:
  - claude
  - cursor
  - codex

name, version, and type are required. type must be skill, rule, or command, and its matching plural directory must be present and non-empty. Extra supported directories may be included in the same package.

Updates use the repository's latest GitHub release, falling back to its newest tag. The release/tag must contain an epx.yaml whose version is newer than the installed version.

Private team vaults

EPX vaults distribute reviewed assets through private Git repositories, synchronized Google Drive, iCloud Drive, Dropbox or OneDrive folders, generic local/network folders, and compatible MCP servers. Existing standalone installs remain independent.

# Detect Dropbox, confirm its folder, then create and connect the vault
epx init vault team --dropbox

# Or choose Dropbox, Google Drive, OneDrive, iCloud, or a local folder interactively
epx init vault team
epx vault connect team

# Explicit paths remain supported
epx vault init "/path/to/Google Drive/Team EPX Vault" --name team
epx vault connect team "/path/to/Google Drive/Team EPX Vault" --provider folder

# Or connect Git and MCP providers
epx vault connect company [email protected]:company/ai-vault.git --provider git
epx vault connect remote https://vault.company.com/mcp --provider mcp


# Publish, review, and explicitly synchronize
epx vault publish ./postgres-review --vault team
epx vault add JuliusBrussee/caveman --vault team
epx vault approve postgres-review --vault team
epx vault status team
epx vault sync team --dry-run
epx vault sync team

Run epx init vault <name> or epx vault connect <name> to choose a synchronized storage provider with the arrow keys. EPX detects installed account folders and asks for confirmation before creating or connecting the exact path. If a selected client is missing, EPX can open its official installation page after confirmation; the user installs it and signs in before retrying. Cloud credentials remain with desktop clients. Git uses the system Git/SSH credential stack. The MCP adapter implements vault_get_snapshot and vault_put_snapshot tools. For a private MCP vault named remote, provide EPX_VAULT_TOKEN_REMOTE in the environment; tokens are never written to the shared vault or EPX configuration.

Every publication is validated, audited, hashed, and stored with its heuristic risk result. Use --block-risk when strict ingestion is desired. Edit epx-vault.yaml to register named reviewers and their SSH public keys. Approvals are signed, apply to one exact digest, and cannot be issued by the publisher when self-approval protection is enabled. High and critical assets remain blocked from installation by default vault policy. Sync installs only approved assets and refuses to overwrite native agent destinations changed since the previous vault sync.

The first vault creation asks once for a name and email, saves the local profile at ~/.epx/profile.json with user-only permissions, and writes its SHA-256 identity plus name/email into the new vault member list. Later publications reuse the identity automatically. Inspect or change it with epx profile show and epx profile set --name "Name" --email [email protected].

Security audit

Audit every Markdown file under skills/, rules/, and commands/ using the same heuristic risk categories as the explainx.ai skill scanner:

epx audit
epx audit react-review
epx audit ./my-package --json
epx audit --fail-on critical

The audit checks for command and dynamic code execution, downloads, secret access, privilege escalation, exfiltration, obfuscation, destructive actions, persistence, sensitive paths, supply-chain risks, prompt injection, network access, and broad filesystem access. It is static heuristic analysis, so findings require human review. By default the command exits with status 1 when the highest risk is high or critical, making it suitable for CI.

Development

npm install
npm run build
npm test

The Jest suite uses mocked GitHub responses and isolated temporary EPX homes, so it does not modify ~/.epx or require live repositories. Run coverage with npm run test:coverage and watch mode with npm run test:watch.

Publish a verified public release with npm's passkey-compatible client:

npm run release

The release script runs type checking, tests, the production build, and a package dry run before publishing. Authentication remains in npm's user-level configuration and is never stored in this repository.

License

MIT