Codex Semantic Review

PyPI package: codex-commit-review-mcp · Release: v0.3.0

This is a local MCP server with zero third-party runtime dependencies. After a successful commit of code or runtime configuration, Codex will receive a mandatory $commit-review reminder; once explicitly called, it generates a plan-linked, readable, and traceable code review site. A single invocation of history can switch among multiple commit tabs on the same page.

It gathers the review context that a plain git diff cannot provide into a single window:

• On the left, a truly recursive and collapsible GitLab-style changed-file tree showing file state, importance, and counts of added/deleted lines.

• In the middle, support for unified and strictly aligned before/after split views of a diff, preserving old and new line numbers, hunks, and source positions of functions.

• On the right, for important functional changes it presents explanations at the file, function, hunk, and line granularity; clicking an explanation jumps to the corresponding code.

• At the top, stable step IDs from the build plan are mapped into files and functions and covered/unmapped status is shown.

• review.json, comments.json and manifest.json provide SHA-256 audit evidence.

The generated site only binds to 127.0.0.1 and will not upload code. Automatic location hints are always flagged as heuristic; they can help Codex locate the spot, but they do not, in themselves, a CC of the final semantic review.

Interactive

The repository contains an interactive bilingual page that follows the MCP light theme. Using disguised but realistic data, it simulates the full Codex-for-mac workflow: enter a task, generate a plan, verify execution, execute the items one by one, hand off after Build, and invoke MCP to open the local Review. When finished, plan/sub-feature/commit stay in a one-to-one mapping; selecting any planned item opens its commit and brings up the changed-file tree, the before/after diff, file/function/line proximity, the semantic gate, and the receipt. The demo never reads the current repository or uploads data.

python3 -m http.server 4173 --directory site

Then open http://127.0.0.1:4173/.

The public product page is: GitHub Pages

Related MCP server: code-timeline

One-Click Install

Install the PyPI package and register it as a stdio MCP server under Codex:

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

Install the matching workflow skill from within Codex using the built-in $skill-installer:

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

The new skill will appear next turn. Then use codex mcp list to confirm the MCP and explicitly run $commit-review to perform one commit review.

Codex Integration

The official Codex integration has three layers:

1. .codex/config.toml declares the stdio MCP server and sets required = true so that it is available for on-demand invocations.

2. AGENT.md instructs Codex to print the notice when a behavior-changing commit has been made, but does not start the MCP by itself.

3. .codex/hook.json catches success in PostToolUse of git commit and echoes the reminder at Stop; non-code-only document or image commits neither queued as pending nor stopping the turn.

Thelogg already has a project-level ready-to-run for the entry. Codex will load project-level MCP only after the project is marked as trusted, and after a first-time or after the hook file is changed, review and approve the exact hooks at the two hooks page from Step 7, using the /hooks command inside Codex.

Official references:

• Codex MCP config

• Codex lifecycle hooks

• AGENTS.md project instructions

A TOML template to reuse for other repositories or user-recipes is in examples/config.toml. A reusable skill is inside skills/commit-review.

Running

Python 3.9+ is enough:

PYTHONPATH=src python3 -m commit_review_mcp

You can also install a command-line entry:

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

A repository-checkout-style TOML is below; Codex resolves the MCP’s relative cwd as the current project root, therefore . makes PYTHONPATH = "src" target the source tree within the repository:

[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

Two-Phase Review

A single commit: use prepare_commit_review / create_commit_review. When the same task has multiple pending commits, prefer prepare_commit_history_review / create_commit_history_review; when the output is a page of tabs that traverses oldest-to-newest, but every SHA still has a result, digest and a receipt.

In the first step you invoke prepare_commit_review or prepare_commit_history_review. When a finished plan is present each item must have a stable id; when there is no plan the MCP creates an explicit auto-generated / unplanned entry:

{
  "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"]
  }
}

The tool hands back:

• important_files — driven by function/control-flow, how big the changed set, and plan file importance;

• annotation_contract.targets — exactly which file/function/block/line targets must be annotated;

• review_template — a ready skeleton for the final payload composed of line numbers, hunk indices, hunk names, and plan_item_ids in it.

In the second stage, after all the targets are filled in, invoke 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
}

The create_commit_review will reject a payload that lacks the explanation of any important_files, any of the required target annotations, a link to the plan, or a concrete summary. In a successful response the semantics, semantic_review.passed = true, url, review_dir, review_sha256, important_files, plan_coverage, comment_counts and _review`.

Reminder and audit closure

On success, the server will write codex-commit-review/receipts/<commit>.json under Git metadata and not touch the working tree at all. The history page produces a receipt per commit, pointing to same localhost artifact while each stores its own commit, digest and semantic coverage. The reminder is mandatory, but this project’s demand-driven policy isn't going to block a turn should the user not call MCP; when server invoked, though, it strictly refuses a heuristic-only or incomplete payload.

The hook is a reminder for a local workflow, not an amplification of authr: it neither pushes, merges, uploads, deletes code, nor kills a process. When you run git commit --amend/--rebase, the new SHA (摘要) will be reconsidered; a SH that has become unreachable after replaced supersed is not required separately. Working-tree’s uncommitted changes appear separately from what's in the commit.

Audit Files

Inside it is, by default, written under ~/.codex/commit-reviews/<repo>/<commit12>/. If directory is not writable, fallback to the system temp directory and say so in the result. The directory holds:

• review.json — the commit, diff base, plan mapping, changed files, d iff model and semantic coverage;

• comments.json — the Codex, heuristic comments and in-browser local review comments;

• manifest.json — SHA-256 digests of the static assets, review and comments;

• index.html, appJa, app.js, styles.css — the fully local site with no external CDN.

For larger diffs is max_diff_bytes; a binary is graded with the old to file-level review. Function detection is a light, language-independent heuristic signature detector, not a claim to full AST-level analysis.

Verification

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

Research, visual discussion and tradeoffs are documented in docs/research.md.