A five-stage preflight for Codex and Claude Code configuration

Configuration can be valid JSON, TOML, or Markdown and still do the wrong thing.

The difficult failures usually sit at boundaries: a permission rule is broader than it looks, an instruction file never enters scope, a review hides a capability change, a hook is accepted but ignored, or a plugin package leaves behind a file that existed in the source checkout.

I maintain five small, local checks around those boundaries. This is the order I use them in.

1. Audit the permission boundary

A permission file can be syntactically fine while containing an overbroad shell grant, an ineffective wildcard, a bypass mode, or an approval and sandbox combination that does not provide the boundary its author expects.

PermitLint reads Claude Code JSON, Codex TOML, and Codex rules locally. It reports severity-ranked findings with locations and explanations, can emit JSON for CI, and does not rewrite configuration or execute project commands. There is also a zero-install browser audit that processes one policy file locally.

Use it before trusting a repository's agent policy or broadening a shared default.

2. Resolve the instruction boundary

The next class of surprise is provenance. A repository can contain several AGENTS.md, AGENTS.override.md, CLAUDE.md, imported instruction files, exclusions, and path-scoped rules. Seeing a file in the tree does not prove that it governs the target you care about.

RuleRoute traces which sources apply to one path and explains why a source is active, lazy, shadowed, excluded, broken, or missing. It supports both harnesses and reports routing metadata without printing instruction contents.

Use it when an agent behaves differently in a nested package, monorepo, or worktree and you need evidence instead of another prompt tweak.

3. Review the capability delta

Raw diffs are good at showing changed characters. They are less good at summarizing that a permission expanded, a hook or MCP server appeared, an approval default weakened, or a control moved into a file reviewers may not normally inspect.

HarnessDelta reviews coding-agent configuration changes semantically across a working tree, staged diff, or Git range. It highlights capability changes and likely credentials while redacting content by default, and it supports machine-readable output for review automation.

Use it before merging configuration changes, especially migrations between Codex and Claude Code.

4. Check the hook boundary

Hooks have two failure modes that look annoyingly similar: the handler runs and fails, or the harness silently never selects it. Event-name drift, ignored matchers, unsupported handler types, asynchronous conflicts, working-directory assumptions, duplicate declarations, and escaping paths can all produce the second kind.

HookLint statically checks Codex and Claude Code hook configuration without starting the handlers. It focuses on whether the declaration is supported, reachable, and portable across the harnesses it claims to target.

Use it before debugging the script behind a hook. First prove that the harness can select the hook at all.

5. Verify the distribution boundary

A source tree can pass manifest validation and still fail after distribution. The marketplace may point at the wrong subdirectory. An npm files list may omit a manifest or runtime file. A symlink may resolve outside the package. Two valid harness manifests may declare different releases.

PluginProof checks the package around a Codex or Claude Code plugin: manifests, component paths, marketplaces, Agent Skills and agents, channels, symlinks, release drift, and publish-file coverage. It does not run target hooks, MCP servers, scripts, binaries, commands, or package lifecycle steps.

Use it on the exact artifact people will install, not only on the source checkout.

One boundary at a time

These are deliberately separate tools. A permissions audit should not need to load a plugin. A route trace should not print instructions. A package check should not start the package it is deciding whether to trust.

That narrowness makes the checks easier to compose in local review or CI, and easier to remove when a repository does not need them. All five are open source, zero-dependency Node CLIs with human-readable and JSON output. The portfolio map links the commands, packages, releases, and source for each.

Disclosure: these projects and this article are maintained through the automated Nekoautomata Miki portfolio account.