oxn (Oxygen)

# Why it exists

Coding agents write code faster than anyone can review its structure. They respect a style guide well enough, but they have no sense of a project’s architecture: which layer may import which, where coupling is already too high, which module is quietly turning into a cycle.

The tools that measure architecture well (Sonargraph, Structure101, NDepend and the like) are commercial. The free ones tend to cover a single language or a single metric. I wanted one engine that computes the metrics itself, from one normalized code graph, uniformly across languages, and then uses them to hold an agent to the invariants a project declares.

# How it works

The idea fits in one line: semantic context goes in over MCP; deterministic enforcement comes out over hooks.

• Enforcement. A Claude Code PostToolUse hook runs on every Edit, Write and MultiEdit. When a change violates a declared rule it exits with code 2 and line-level detail, and the agent has to fix it before moving on. The retry loop is bounded by a retry_budget, because LLM refactoring does not reliably converge.
• Context. Four read-only MCP tools let the agent ask about the architecture before it edits: what depends on this, which layer this belongs to, where the hotspots are.
• Analysis. Parsing is tree-sitter, name resolution is SCIP, and everything above that is implemented in the project itself, from complexity and coupling to an exact minimum feedback arc set (oxn arch) that says which edges to cut to break a dependency cycle.

# Design decisions

• Two free dependencies, the rest self-built. Free tools are still used, but as differential-test oracles in CI rather than as runtime dependencies.
• Hooks enforce, MCP informs. Keeping the two roles apart means the model can never argue its way past a gate.
• Hand-written MCP. The protocol is implemented directly against the 2025-06-18 revision instead of pulling in the SDK and its dependency tree.
• Numbers the model can’t invent. oxn review lets an LLM phrase a pull request summary, but any number it states that OXN did not measure is refused.
• Calibration in the open. oxn calibration lists every tunable threshold together with the evidence behind it. oxn health reports, but never gates.
• No cloud, no daemon. Everything runs locally.

# Status

Alpha, and published on PyPI. The analysis engine is built and gating: OXN has gated its own development since 30 August 2026, across all six launch languages.