code-warden

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.

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.

1. CI only — add warden-lint and verify-secrets to GitHub Actions. No skill install required.
2. Skill governance — install Code-Warden into your AI runtime. Scope Gates, Plan Gates, and drift signals activate immediately.
3. 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

git clone https://github.com/Kodaxadev/Code-Warden.git
cd Code-Warden/code-warden
node install.js

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

Common commands

node install.js --all                    # install without prompt
node install.js --dry-run                # preview, write nothing
node install.js --list                   # show detected apps
node install.js --doctor                 # verify source + install health
node install.js --verify-target=claude   # strict per-target check, exits nonzero on failure
node install.js --hooks=claude           # install Claude Code PreToolUse hooks
node install.js --uninstall-hooks=claude # remove Claude Code hooks
node install.js --hooks=codex            # install Codex PreToolUse hooks (partial)
node install.js --uninstall-hooks=codex  # remove Codex hooks

npm scripts

npm run lint            # scan full project tree for oversized files
npm run check-secrets   # scan full project tree for hardcoded credentials
npm run ci              # lint + secrets + doctor
npm run install-auto    # node install.js
npm run install-doctor  # node install.js --doctor

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

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 when hooks are registered.

CI Integration

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

- name: Lint — file length limits
  run: node .code-warden-ci/tools/warden-lint.js .

- name: Secrets — zero-trust scan
  run: node .code-warden-ci/tools/verify-secrets.js .

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

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/research-and-fit.md	Live research gate, stack fit, product-shape guardrails

Version

v3.1.0 — See code-warden/SKILL.md for full changelog.

Author

Justin Davis — MIT License