npm package: @portcullis-ai/codex-cli
Description: Portcullis AI Code Guardian integration for OpenAI Codex CLI
Author: Portcullis AI
Latest version: 0.1.4

# @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

### 1. Install Python Dependencies

Portcullis requires Python 3.10+ and several dependencies:

```bash
portcullis install
```

### 2. Configure Codex CLI

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. Verify Installation

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:

### 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

```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](https://github.com/indygreg/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