hpatch is a Codex Responses router and CLI that replaces verbose apply_patch tool calls with compact selectors and replacement text, reducing model output tokens while preserving sandbox checks and diff UI.

Stars

6

7-day growth

No data

Forks

1

Open issues

0

License

MIT

Last updated

2026-07-30

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It provides reproducible token savings by moving patch reconstruction out of model output, uses constrained grammar to eliminate invalid tool calls, and integrates seamlessly with Codex CLI and its sandbox.

Who it is for

  • Developers using OpenAI Codex CLI for AI-assisted code editing
  • LLM agent engineers seeking to reduce token costs and latency
  • Researchers analyzing token efficiency in AI code generation

Use cases

  • Lower token consumption when applying multiple file edits via Codex
  • Standalone file patching with a compact DSL without running a full model
  • Measuring output token savings between hpatch and traditional apply_patch

Strengths

  • Measurable token savings (GPT-5 estimates) by avoiding old context repetition and JavaScript carriers
  • Lark grammar enforces valid syntax, preventing generate-reject-retry cycles for malformed tool calls
  • Atomic script validation with rejection that leaves files unchanged
  • Compatible with Codex diff UI and sandbox permissions

Considerations

  • Requires Go 1.26+, systemd user service for router, and Codex CLI with ChatGPT auth
  • Router only works with single usable workspace root; zero or multiple roots fail closed
  • Token savings are reproducible payload estimates, not actual provider billing totals

README quick start

hpatch

A Codex Responses router that lets agents edit with compact selectors and replacement text instead of emitting full patches.

hpatch-router sits between Codex and the Responses API. It replaces the Code Mode apply_patch surface with constrained functions.hpatch, resolves successful scripts against the declared workspace, and hands Codex a real apply_patch carrier so sandbox checks and the normal diff UI remain intact. The repository also includes the standalone hpatch CLI and reusable Go engine used by the router.

TL;DR:

GoalStart here
Route Codex edits through hpatchInstall and configure the Codex router
Make Codex prefer hpatchOverride the base instructions
Inspect measured token savingsMetrics, then run hpatch gain
Use the engine without CodexStandalone CLI
Read the full editing contracthpatch --help, hpatch --tool-help, doc/spec/interface.md

Why hpatch?

A direct Code Mode edit makes the model repeat patch framing, old context, replacement text, and the JavaScript carrier. The router moves patch reconstruction out of model output:

flowchart LR
    subgraph output["Alternative model-output payloads"]
        H["hpatch pathfunctions.hpatch + selectors + replacement"]
        A["apply_patch baselinefunctions.exec + JavaScript carrier+ old context + replacement + patch framing"]
    end

    subgraph router["Router and Codex after model output"]
        B["Router reads the immutableworkspace baseline"]
        C["Router generates theapply_patch envelope"]
        D["Codex applies the patchsandbox checks + normal diff"]
    end

    H --> B --> C --> D
    A --> D

The patch is not eliminated: the router generates it after inference. Savings are the difference between the two model-output payload estimates shown above. State reports, rejection diagnostics, and the net cost of installing the hpatch tool definition while removing the Code Mode apply_patch section are tracked separately as input overhead. These are reproducible GPT-5 token estimates, not provider billing totals.

For an 11-line function replacement, hpatch asks the model for this:

functions.hpatch
in parser.go
rsel 50:60
type

Description

Compact, editor-like file edits for agents: select text, type the change, skip rewriting full patches.

Related repositories

Similar projects matched by category, topics, and programming language.

mereyabdenbekuly-ctrl
Featured
mereyabdenbekuly-ctrl GitHub avatar

clodex-ide

Clodex is an open-source, local-first agentic IDE that combines persistent AI tasks, code, terminal, browser, Git, models, memory, and governed execution in one Electron workspace, currently in technical preview.

AI & Machine LearningAI Agents
859
MoonshotAI
Featured
MoonshotAI GitHub avatar

Kimi-K3

Kimi K3 is an open-weight, 2.8T-parameter native multimodal agentic model with a 1M-token context window, designed for frontier coding, knowledge work, and reasoning tasks.

AI & Machine LearningAI Agents
3,348
lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390