@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

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

Setup

1. Install Python Dependencies

Portcullis requires Python 3.10+ and several dependencies:

portcullis install

2. Configure Codex CLI

Add Portcullis as an MCP server in your Codex configuration:

portcullis setup

This adds the following to ~/.codex/config.toml and installs the Portcullis agent definition at ~/.codex/AGENTS.md:

[mcp_servers.portcullis-ai-guardrails]
command = "npx"
args = ["-y", "@portcullis-ai/codex-cli", "serve"]
startup_timeout_sec = 60
tool_timeout_sec = 120

3. Verify Installation

Run diagnostics to ensure everything is configured correctly:

portcullis doctor

Usage

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

Agentic Tools (High-Level)

• 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

Sentinel Tools (Safety)

• 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

Temporal Tools (Evolution)

• get_symbol_evolution - Symbol timeline tracking
• predict_change_impact - Blast radius analysis
• get_breaking_changes_since - Breaking change detection

CLI Commands

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:

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:

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