Portcullis AI Code Guardian integration for OpenAI Codex CLI
npm install @portcullis-ai/codex-cliPortcullis AI Code Guardian integration for OpenAI Codex CLI.
This package provides an MCP (Model Context Protocol) server that integrates Portcullis's code intelligence and safety analysis tools with the Codex CLI. It enables Codex to perform safety checks, risk assessments, and historical code analysis before making changes.
``bash`
npm install -g @portcullis-ai/codex-cli
Portcullis requires Python 3.10+ and several dependencies:
`bash`
portcullis install
Add Portcullis as an MCP server in your Codex configuration:
`bash`
portcullis setup
This adds the following to ~/.codex/config.toml and installs the Portcullis agent definition at ~/.codex/AGENTS.md:
`toml`
[mcp_servers.portcullis-ai-guardrails]
command = "npx"
args = ["-y", "@portcullis-ai/codex-cli", "serve"]
startup_timeout_sec = 60
tool_timeout_sec = 120
Run diagnostics to ensure everything is configured correctly:
`bash`
portcullis doctor
Once configured, Portcullis launches automatically when you start Codex CLI. The following MCP tools become available:
- Pre-flight safety assessment
- historepo_why_does_this_exist - Chesterton's Fence analysis
- historepo_architecture_audit - Architectural review
- historepo_file_deep_dive - Complete file history
- historepo_get_edit_context - Pre-task context injection$3
- analyze_patch_risk - Diff risk assessment
- get_symbol_risk_profile - Historical risk analysis
- check_zombie_pattern - Reintroduced code detection
- get_revert_history - Past revert tracking
- get_chestertons_fences - Load-bearing code detection$3
- get_symbol_evolution - Symbol timeline tracking
- predict_change_impact - Blast radius analysis
- get_breaking_changes_since - Breaking change detectionCLI Commands
`bash
portcullis serve # Start MCP server (used by Codex)
portcullis install # Install Python dependencies
portcullis setup # Configure ~/.codex/config.toml
portcullis doctor # Diagnose installation
portcullis version # Show version
`Python Runtime
Portcullis requires Python 3.10+ to run the MCP server backend. The CLI resolves Python in this order:
1. System Python - Checks
python3, python, and well-known paths for Python 3.10+
2. Bundled Python - Uses pre-bundled runtime from python/runtime/ (included in full bundles)
3. Auto-download - Downloads Python 3.10.13 from python-build-standalone if no local Python is availableThe
portcullis doctor command shows which Python source is in use.Building & Bundling
For development:
`bash
npm run build # Compile TypeScript
npm run bundle:server # Bundle historepo_ai server code only
npm run bundle:full # Bundle server code + Python runtime
`For publishing:
`bash
npm run prepublishOnly # clean + build + bundle:server (runs automatically on npm publish)
`The
bundle:server script copies the historepo_ai Python backend into python/historepo_ai/, filtering out tests, __pycache__, and dev-only files. The bundle:full variant also downloads a platform-specific Python runtime into python/runtime/`.- Node.js 18+
- Python 3.10+ (auto-downloaded if not available)
- Git (for repository analysis)
MIT