Code-Warden
Kodaxadev/Code-Warden
Governança e auditoria para agentes de IA que tocam código em produção
Ver no GitHubCamada portável de governança e execução para agentes de codificação com IA. Implementa Scope Gates e Plan Gates, verifica código localmente, integra com CI/CD, valida saúde de instalações e oferece hooks opcionais para Claude Code. Ideal para sessões de codificação autônoma de longa duração com múltiplos arquivos.
Instalação
npx convez-ai Kodaxadev/Code-Warden1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Agentes codificadores em sessões longas com múltiplos arquivos
- Verificação de escopo e plano antes de edições automáticas
- Integração CI/CD com gates de qualidade e segurança
- Auditoria e rastreabilidade de mudanças feitas por IA
- Prevenção de código não declarado, credenciais expostas e overscopying
Veredito

Code-Warden é uma solução madura (v3.4.0) e bem fundamentada para times que delegam trabalho real a agentes IA. Resolve um problema legítimo (falta de governança em codificação autônoma), mas é claramente feita para contextos de alta autonomia — não é para quem faz edições curtas e supervisionadas. Implementação sólida com suporte a hooks Claude e CLI bem pensada.
README
A tradução para o português deste README ainda está na fila.
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-lintandverify-secretsto 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