@portcullis-ai/codex-cli

Portcullis AI Code Guardian integration for OpenAI Codex CLI.

Overview

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.

Installation

``bash
npm install -g @portcullis-ai/codex-cli
`

Setup

$3

Portcullis requires Python 3.10+ and several dependencies:

`bash
portcullis install
`

$3

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
`

$3

Run diagnostics to ensure everything is configured correctly:

`bash
portcullis doctor
`

Usage

Once configured, Portcullis launches automatically when you start Codex CLI. The following MCP tools become available:

$3


- historepo_quick_safety_check - 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 detection

CLI 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 available

The 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/`.

Requirements

- Node.js 18+
- Python 3.10+ (auto-downloaded if not available)
- Git (for repository analysis)

License

MIT