code-warden

Quickstart

npx code-warden init
npx code-warden doctor
npx code-warden verify codex  # or your target runtime
npx code-warden report

Optional hard hooks where supported:

npx code-warden hooks claude
npx code-warden hooks codex

Use doctor after install or hook setup. It verifies installed skill manifests, hook script paths, and runtime-specific hook config when hooks are registered. When it finds partial hook setup, it prints the repair command to rerun.

Who This Is For

Code-Warden is for when AI coding stops being autocomplete and starts being delegated work.

If you run short, supervised one-file AI edits, Code-Warden may be overkill.

If you run long Claude Code, Codex, or Cursor sessions — multi-file refactors, parallel projects, CI-gated work, or client and product code — Code-Warden gives your agent declared scope, verifiable checks, and enforceable safety rails.

At its core, Code-Warden is a governance contract:

The agent states architecture context before acting.
The agent declares scope and patch order before edits.
The repo verifies file size, secrets, tests, install health, risk policy, runtime hooks, and receipt artifacts.
The workflow keeps receipts, JSON, Markdown, SARIF, and release evidence outside chat memory.

Built for developers who:

Run long, high-autonomy AI coding sessions
Let agents touch multiple files or whole modules
Work across several projects at once
Need CI-friendly verification without relying on chat memory
Need an audit trail for what the agent was allowed to change
Want hard blocking where the runtime supports it

Probably overkill if:

You only use AI for short snippets
You manually review every one-file edit before it lands
You do not need CI checks
You are comfortable relying entirely on prompt instructions

Prevents / Allows

Prevents

Code before scope is declared
Multi-file edits without a patch plan
Files touched outside approved scope
Oversized monolithic files
Hardcoded API keys and credentials
Completion claims without verification evidence
Stale or broken agent installs
Claude Code writes that violate hook policy

Allows

Normal development work
Fast solo-founder iteration
Existing agent workflows
CI enforcement without chat memory
Optional hard blocking only where supported

Four Layers

Compatibility

Runtime	Install	Skill Rules	Local Tools	CI	Hard Hooks
Claude Code	✅	✅	✅	✅	✅ PreToolUse
OpenAI Codex	✅	✅	✅	✅	⚡ Partial
Cursor	✅	✅	✅	✅	—
Warp	✅	✅	✅	✅	—
Windsurf	✅ flat rules	✅ adapted	✅	✅	—
Generic Agents	✅	✅	✅	✅	—
GitHub Actions	—	—	✅	✅	—

Claude Code gets full hard enforcement (blocks Write/Edit before the file system is touched). Codex gets partial enforcement: apply_patch and Bash calls are intercepted for secrets and estimated file size — the tool surfaces Codex exposes at PreToolUse. CI enforcement closes the remaining gap for both runtimes.

Why Not Just Prompt Better?

You should prompt well. Code-Warden does not replace that.

Prompts are policy. Code-Warden adds verification and enforcement.

Rule	Prompt-only	Code-Warden
Keep files modular	Agent remembers	`warden-lint` checks files and directories
No hardcoded secrets	Agent remembers	`verify-secrets` scans locally and in CI
Stay inside scope	Agent declares scope	Scope Gate creates an explicit file contract
Verify before done	Agent claims it checked	`npm run ci` produces a deterministic result
Block unsafe writes	Not possible everywhere	Claude `PreToolUse` hooks deny `Write`/`Edit` before execution

Code-Warden is portable at the governance, installer, local-tooling, and CI layers. Hard pre-write blocking is currently Claude Code-specific because Claude exposes PreToolUse hooks. Other runtimes get all other layers.

What Code-Warden Is / Is Not

Code-Warden is:

A governance layer for AI coding agents
A local verification toolkit
A cross-runtime installer and health checker
A CI-friendly policy gate
An optional hard-enforcement layer for Claude Code (full) and Codex (partial)

Code-Warden is not:

A replacement for your coding agent
A full development methodology like Superpowers
A sandbox or security boundary against malicious users
A guarantee that unsupported runtimes can block tool calls before execution

Code-Warden governs the agent inside the workflow you already use.

Adoption Path

You do not need to install everything at once. Each layer adds value independently.

CI only — add warden-lint and verify-secrets to GitHub Actions. No skill install required.
Skill governance — install Code-Warden into your AI runtime. Scope Gates, Plan Gates, and drift signals activate immediately.
Hard enforcement — enable hooks for pre-tool-use blocking. Claude Code: full (Write/Edit). Codex: partial (apply_patch/Bash). Requires step 2 first.

Start where you have the most immediate pain.

Install

npx code-warden init

Or install globally:

npm install -g code-warden
code-warden init

The installer scans for AI runtimes and deploys to all of them in one step. Supports Claude Code, Cursor, Warp, OpenAI Codex, Windsurf, and generic agent runtimes.

CLI commands

code-warden init              # install to detected AI runtimes
code-warden report            # generate governance report
code-warden report --format=md # Markdown output (pipe to PR summary)
code-warden report --format=sarif # SARIF output for Code Scanning
code-warden report --format=sarif --out=code-warden.sarif
code-warden receipt --template --out=code-warden-receipt.json
code-warden receipt --validate=code-warden-receipt.json
code-warden references README.md code-warden/tools/
code-warden smoke-npx --package=code-warden@latest
code-warden doctor            # verify source + install health
code-warden verify codex      # strict health check for one runtime
code-warden list              # show detected runtimes
code-warden hooks claude      # install Claude Code PreToolUse hooks
code-warden hooks codex       # install Codex PreToolUse hooks (partial)
code-warden uninstall-hooks claude
code-warden uninstall-hooks codex

Invoke

/code-warden

Or: "load code-warden", "new session", "begin coding", "governance check".

Session Start Sequence

Optional Hard Enforcement (Hooks)

Claude Code — Full enforcement

node install.js --hooks=claude           # install (requires Claude target installed first)
node install.js --uninstall-hooks=claude # remove

Blocks Write and Edit before the file system is touched — if the resulting file would exceed the line limit or contain a hardcoded credential.

OpenAI Codex — Partial enforcement

node install.js --hooks=codex            # install (requires Codex target installed first)
node install.js --uninstall-hooks=codex  # remove

The Codex hook installer writes ~/.codex/hooks.json and enables the current Codex feature flag in ~/.codex/config.toml:

[features]
hooks = true

If an older config contains [features].codex_hooks, the installer removes that deprecated key while enabling hooks. Current Codex docs list hooks as the stable lifecycle-hook feature flag.

Hook	Trigger	Policy
`warden-apply-patch-hook.js`	`apply_patch`	Blocks if added lines contain a credential or estimated result exceeds line limit
`warden-bash-hook.js`	`Bash`	Blocks if command contains a hardcoded credential

Codex exposes apply_patch and Bash at PreToolUse — not Write/Edit. These are the available surfaces. CI enforcement closes the remaining gap.

Doctor and --verify-target=<id> validate hook script paths and Codex hook feature enablement when hooks are registered, with repair guidance for partial hook setup.

Governance Evidence

Code-Warden produces a machine-readable governance report — verifiable evidence that checks ran and passed:

node tools/governance-report.js .              # writes .code-warden-report.json
node tools/governance-report.js . --format=md  # Markdown table for PR summaries
node tools/governance-report.js . --format=sarif # SARIF for source-located findings
node tools/governance-report.js . --format=sarif --out=code-warden.sarif

The report covers file length, hardcoded credentials, behavioral tests, source integrity, and runtime hook status in a single pass. In CI, it pipes directly into $GITHUB_STEP_SUMMARY so every PR shows what was checked.

SARIF output is intentionally narrower than the JSON report: it includes only findings with source locations (CW001/max-file-length and CW002/hardcoded-credential). Behavioral tests, install health, runtime hook state, and session governance remain in JSON/Markdown because they are workflow evidence, not source-code findings.

Governance receipts cover the part reports cannot know by themselves: the confirmed Scope Gate and Plan Gate. Generate a draft receipt before or during a session, fill in the gate and final command evidence, then validate it:

code-warden receipt --template --out=code-warden-receipt.json
code-warden receipt --validate=code-warden-receipt.json

Receipts deliberately start as drafts with canProveCompliance: false; they become valid only when the required evidence is filled in.

Reports also include risk policy evidence from codewarden.json. The default policy marks read-only work as low, file edits as medium, dependency/network/release operations as high, and destructive or secret-bearing actions as blocked.

External evidence providers are recorded with scope and trust limits. Code Scanning SARIF, secret scanning, dependency scans, artifact attestations, npm provenance, and CI run links can support a governance claim, but they do not replace Scope Gate, Plan Gate, or receipts.

MCP servers are governed as tool-bearing integrations, not harmless context sources. Before enabling one, Code-Warden expects an approval record covering server source, version, transport, toolsets, credential scope, data egress, and rollback. See code-warden/references/mcp-governance.md.

Use code-warden references <paths...> to recommend the focused governance references for touched paths. This is advisory loading, not hidden enforcement.

CI Integration

Use Code-Warden as a GitHub Action:

- name: Code-Warden Governance Gate
  uses: Kodaxadev/Code-Warden@v3
  with:
    path: .

The action writes .code-warden-report.json, appends a Markdown summary to the workflow run, and uploads the report as an artifact by default.

Enable GitHub Code Scanning annotations with SARIF:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v6
  - name: Code-Warden Governance Gate
    uses: Kodaxadev/Code-Warden@v3
    with:
      path: .
      sarif: 'true'

The action uploads SARIF through github/codeql-action/upload-sarif@v4 and still fails the job when the governance report fails.

Or download a pinned release directly:

- name: Install Code-Warden
  run: |
    curl -fsSL -o cw.zip \
      https://github.com/Kodaxadev/Code-Warden/releases/download/v3.4.0/code-warden-v3.4.0.zip
    unzip -q cw.zip -d .code-warden-ci

- name: Governance report
  run: node .code-warden-ci/tools/governance-report.js .

- name: Publish governance summary
  if: always()
  run: node .code-warden-ci/tools/governance-report.js . --format=md >> $GITHUB_STEP_SUMMARY

- name: Upload governance artifact
  if: always()
  uses: actions/upload-artifact@v7
  with:
    name: code-warden-report
    path: .code-warden-report.json
    retention-days: 90

The pinned v3.4.0 release-download path includes SARIF and --out support.

Full template: code-warden/templates/ci/github-actions.yml

Release Trust

Code-Warden releases are tag-driven. The release workflow verifies the package version matches the pushed tag, runs the governance gate, performs an npm publish dry run, publishes to npm through trusted publishing, creates a GitHub release, and uploads the versioned zip asset.

Trusted publishing uses GitHub Actions OIDC instead of a long-lived npm token and lets npm attach provenance to public package publishes from public repositories.

File Structure

File	Purpose
`SKILL.md`	Session gates, quick rules, drift signals, reference index
`CONFIGURE.md`	Tunable thresholds and team-size profiles
`DECISIONS.md`	Architecture decision log
`references/planning-gates.md`	Scope Gate and Plan Gate contracts
`references/architecture.md`	Blueprint Rule, Re-injection, State Update
`references/safety.md`	Blast Radius, Patch-First, Zero-Trust, Dependency Freeze
`references/cognition.md`	Think Before Coding, Don't Guess Syntax, Human Checkpoint
`references/cleanup.md`	Tech Debt format, Test Contract, Decision Log
`references/anti-drift.md`	Anchor Check, Session Scoping, Drift Trigger
`references/operations.md`	Verification evidence, git hygiene, dependency control
`references/evidence-providers.md`	External scanners, provenance, attestations, CI evidence, trust limits
`references/research-and-fit.md`	Live research gate, stack fit, product-shape guardrails
`references/mcp-governance.md`	MCP approval, toolset scope, credentials, consent, audit evidence
`tools/lib/reference-selector.js`	Path-based governance reference recommendations
`tools/lib/risk-policy.js`	Risk tier defaults, config merge, and validation
`tools/receipt.js`	Governance receipt template and validation CLI

Version

v3.4.0 — See CHANGELOG.md for full changelog.

Author

Justin Davis — MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github/workflows		.github/workflows
code-warden		code-warden
logo		logo
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_v2.3.0.md		RELEASE_NOTES_v2.3.0.md
RELEASE_NOTES_v2.3.1.md		RELEASE_NOTES_v2.3.1.md
RELEASE_NOTES_v2.4.0.md		RELEASE_NOTES_v2.4.0.md
RELEASE_NOTES_v2.5.0.md		RELEASE_NOTES_v2.5.0.md
RELEASE_NOTES_v2.6.0.md		RELEASE_NOTES_v2.6.0.md
RELEASE_NOTES_v2.7.0.md		RELEASE_NOTES_v2.7.0.md
RELEASE_NOTES_v2.7.1.md		RELEASE_NOTES_v2.7.1.md
SECURITY.md		SECURITY.md
action.yml		action.yml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

code-warden

Quickstart

Who This Is For

Prevents / Allows

Four Layers

Compatibility

Why Not Just Prompt Better?

What Code-Warden Is / Is Not

Adoption Path

Install

CLI commands

Invoke

Session Start Sequence

Optional Hard Enforcement (Hooks)

Claude Code — Full enforcement

OpenAI Codex — Partial enforcement

Governance Evidence

CI Integration

Release Trust

File Structure

Version

Author

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

code-warden

Quickstart

Who This Is For

Prevents / Allows

Four Layers

Compatibility

Why Not Just Prompt Better?

What Code-Warden Is / Is Not

Adoption Path

Install

CLI commands

Invoke

Session Start Sequence

Optional Hard Enforcement (Hooks)

Claude Code — Full enforcement

OpenAI Codex — Partial enforcement

Governance Evidence

CI Integration

Release Trust

File Structure

Version

Author

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages