Codex Semantic Review

Paquete PyPI: codex-commit-review-mcp · Versión: v0.3.0

Es un servidor MCP local con cero dependencias de terceros en tiempo de ejecución. Cuando se confirma un commit o una configuración de ejecución de forma correcta, Codex recibe el recordatorio obligatorio $commit-review; si se invoca de forma explícita, genera un sitio de revisión de código ligado al plan, legible y trazable. Una sola llamada a history permite alternar entre varias pestañas de commits dentro de la misma página.

Reúne en una sola interfaz el contexto de revisión que le falta a un git diff normal:

• A la izquierda, un árbol real recursivo y plegable de archivos modificados (changed-file tree) con estilo GitLab, que muestra el estado, la importancia y las líneas añadidas/eliminadas.

• En el centro, soporta unified y split diff before/after alineado estrictamente, conservando los números de línea antiguos y nuevos, así como el hunk y la ubicación de la función.

• A la derecha, muestra las cambias funcionales más importas, junto con explicaciones por archivo, por función, por diseño y por línea; al hacer clic en una explicación permite ur al código correspondiente.

• La parte superios asigna a los IDs estables de pasos del build plan a archos y funcions, y muestra covered/unmapped.

• review.json, comments.json y manifest.json ofrecen la evidencia de auditoría de SHA-256.

El sitio se vincula únicamente a 127.0.0.1; no sub código. Las pistas de localación automática siempre están marcadas como heuristics; ayudan a Codex a ubicar, pero no cumplen el pos móvil final de revisión semántica.

Demo interadjunta

El repositorio contiene una página demo bilingüe que hereda el light theme de MCP. Simula con pseudo-datos anonimizados flujo de trabajo completo dentro de Codex en Mac: ingresar la tarea, generar el Planas, confirmation de ejecución, construir itemum por item, entregar y llamar al MCP para abrir la revisión local. Las páginas completas, del plano >featuref → pal.

Una vez concluido, plan/sub-feature/commit mantienen una correspondencia base uno a uno; al hacer clic en cual sobre el item del plan abre el commit correspondiente y ofrece changed-file tree, un diff before/after, localización de file/versión/function/line, semantic gate y recepuad. La demo no read el repositorio actual no sube datos.

python3 -m http.server 4173 --directory site

Huego abra http://127.0.0.1:4173/.

Página pública del product: GitHub Pages

Related MCP server: Git Code Review MCP

Instalación en un solo paso

Instala el paquete PyPI y regoca del MCP stdio de Codex:

python3 -m pip install --user codex-commit-review-mcp==0.3.0 && codex mcp add codex_commit_review -- python3 -m commit_review_mcp

En Codex, concedo al instalador integrado $skill-installer para instalar el workflow skill correspondiente:

$skill-installer https://github.com/chi-qhsun/Codex-Semantic-Review/tree/v0.3.0/skills/commit-review

El nuevo skill estará disponible en la siguiente ronda. Usa codex mcp list para verificar el MCP y, luego, invoca de forma explícita $commit-review para completar una revisión de commits.

Integración con Codex

La integración real con Codex se divide en tres capas:

1. .codex/config.toml registra el MCP estándar stdio, y usa required = true para garantar la disponibilidad bajo pedido.

2. AGENTS.md surgió un recordatorio tras un commit de camb io de comportamiento, per no se autoproa el MCP.

3. .codex/hooks.json captura los git commit correctos en PostToolUse, y lo pone Stop como recordatorio; los commits de solo documentación o imagen entLos/agree pending y no bloque el turno actual.

Este repositorio ya app include a través de proyect (project-level) ejecutable. Codex solo lee le la MCP y los hooks de la spe a nivel del project una vez que el project se ha confilado/; en el primer uso o when el contenido de los hooks cambie, in Codex use /hooks para verificar y confiar en las definiciones de los hooks específicos.

Fuentes oficiales:

• Configuración MCP de Codex

• Codex lifecycle hooks

• Instrucciones de projeto en AGENTS.md

La plantilla de TOML para otos repositorios o configuraciones de nivel de usuario se presenta en examples/config.toml. El skill restable está en ubiado en skills/commit-review.

Run

Basta con Python 3.9+:

PYTHONPATH=src python3 -m commit_review_mcp

También se puede instalar un comando de entrada:

python3 -m pip install .
codex-commit-review-mcp

Una configuración TOML de un checkout del project títé as follows; Codex registra el cwd relativo del MCP contra la raíz del project actual, por lo que . hace que PYTHONPATH = "src" apunte al directorro de fuentes de repositorio:

[mcp_servers.codex_commit_review]
command = "python3"
args = ["-m", "commit_review_mcp"]
cwd = "."
env = { PYTHONPATH = "src" }
enabled = true
required = true
enabled_tools = ["prepare_commit_review", "create_commit_review", "prepare_commit_history_review", "create_commit_history_review", "read_commit_review"]
default_tools_approval_mode = "auto"
startup_timeout_sec = 10
tool_timeout_sec = 120

Revisión en dos fases

Para simple commits, use prepare_commit_review / create_commit_review. Cuando hay varios commits other applicant order en la misma task, se prió usar prepare_commit_history_review / create_commit_history_review; el resultado es una página de pestañas que puede conmutca... but cada SHA pose still un entail result semántico, digest y receipt.

En la primera fase de prepare_commit_review de, or with prepare_commit_history_review. Con es/te un plan construído, cada item debe tener un id estable; sin plan, el MCP generará un item explítico auto-generated / unplanned:

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {
    "title": "Bound retry behavior",
    "items": [
      {"id": "retry", "title": "Bound transient retries", "description": "Retry transient failures at most three times"},
      {"id": "tests", "title": "Prove failure behavior", "acceptance": "Focused success and permanent-failure tests pass"}
    ],
    "decisions": ["Keep the public API compatible"],
    "risks": ["Retries must not hide permanent errors"]
  }
}

La herramienta devuelve:

• important_files: determina el de la función/imflujo de control, la magnel cambio del y la correspondencia con el plan;

• annotation_contract.targets: objetivos compet áctos (file/function/block/line) para acubrir que deben cubrírs;

• review_template: el skeleton del payload final sepreparado para rellenar, with línea física, la hunk, function name and plan_item_ids.

Si ya se han cubiendo todos los targets, se llama a create_commit_review:

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {"title": "Bound retry behavior", "items": [{"id": "retry", "title": "Bound transient retries"}]},
  "review": {
    "summary": "This commit bounds transient retries while preserving permanent error propagation and the public call contract.",
    "important_changes": [
      {
        "path": "src/retry.py",
        "title": "Bounded retry state machine",
        "body": "Before, every failure escaped immediately; after, only transient failures enter a three-attempt loop and permanent failures still propagate.",
        "plan_item_ids": ["retry"]
      }
    ],
    "comments": [
      {"level": "file", "path": "src/retry.py", "body": "This file now owns retry classification, the bounded loop, and unchanged outward error propagation.", "plan_item_ids": ["retry"]},
      {"level": "function", "path": "src/retry.py", "function": "run", "line": 18, "body": "The function keeps its return contract but adds bounded state around transient calls; permanent exceptions are not caught.", "plan_item_ids": ["retry"]},
      {"level": "block", "path": "src/retry.py", "hunk_index": 0, "line": 19, "body": "This hunk introduces the three-attempt loop and separates retryable failures from the terminal path.", "plan_item_ids": ["retry"]},
      {"level": "line", "path": "src/retry.py", "hunk_index": 0, "line": 22, "body": "The explicit attempt bound prevents an unbounded retry loop while leaving the final exception visible.", "plan_item_ids": ["retry"]}
    ]
  },
  "open_browser": true
}

create_commit_review rechazará los payload que no incluyan explicación de los archivos important, annotations of target, enlaces del plan, o un resumen explícito. Un resultado correctas debe incluir semantics_review.passed = true, url, review_dir``, review_sha256``, important_files, plan_coverage, comment_counts y receipt.

Recordatorios y cierre de auditoría

Le revisión exitosa lea to metadata de Git codex-commit-reviews/receipts/<commit>.json, sin tocar el árbol (working tree). La página history escrib each receipt por commit, todos pointing al mismo artifact de localhost, manteniendo por cada una su commit respective, digest y cobertura semántica. La recordación es obligatoria, pero la estrategia de este prroyecto no bloka el plus turn si el usuario no ha llamado al MCP; una vez invocado, MCP rechaza, aún así, cla payload solo–heuristics o complete no.

Los hooks son de recordación de la presa de trabajo local, not una ampliación de permisos: no hacen push, no merge, no under upload, no delete código, no detten otros processes. Tras amend/rebase, la nueva SHA entra de nuevo en el sequence`; las SHA supersedadas que se han vuelto inaccesibles no requieren revisión. Los cambios sin confirm en el árbol working se muestran separados del diff confirmad.

Archivos de auditoría

El artifact por defecto se referencia ~/.codex/commit-reviews/<repo>/<commit>/. Si no es escribable, se explalla en el resultado and a fallback al director tem de del sistema. La carpeta incluye:

• review.json: la descripa commit, base, plan mapping, funcional changes, diff model y cobertura semántica;

• replies.json/comments.json: Codex, heuristicids and revision local comments;

• manifest.json: resources estátiques y SHA-256 de /review y comments；

• index.html, app.js y styles.css: unt pe sitio local sin CDN.

Los diffs grandes están limitados por max_diff_bytes; los binarios se provider al uma revisión de file. La detection de funcionsy es una identificacióne de light de signatures, no completo analisis de AST.

Verificación

python3 -m unittest discover -s tests -v
PYTHONPYCACHEPREFIX=/tmp/codex-commit-review-pyc python3 -m py_compile src/commit_review_mcp/*.py .codex/hooks/*.py
node --check src/commit_review_mcp/web/app.js
python3 -m build --wheel --no-isolation

La investigación visual y sus trade-offs en docs/research.md.