convez.ai
SkillDevOps & InfraestruturaIntermediário
Kodaxadev

Code-Warden

Kodaxadev/Code-Warden

Governança e auditoria para agentes de IA que tocam código em produção

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada 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-Warden

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
v4.0.0
Issues abertas
0
Contribuidores
1

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

RuntimeInstallSkill RulesLocal ToolsCIHard 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.

RulePrompt-onlyCode-Warden
Keep files modularAgent rememberswarden-lint checks files and directories
No hardcoded secretsAgent remembersverify-secrets scans locally and in CI
Stay inside scopeAgent declares scopeScope Gate creates an explicit file contract
Verify before doneAgent claims it checkednpm run ci produces a deterministic result
Block unsafe writesNot possible everywhereClaude 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

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.

HookTriggerPolicy
warden-apply-patch-hook.jsapply_patchBlocks if added lines contain a credential or estimated result exceeds line limit
warden-bash-hook.jsBashBlocks 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

FilePurpose
SKILL.mdSession gates, quick rules, drift signals, reference index
CONFIGURE.mdTunable thresholds and team-size profiles
DECISIONS.mdArchitecture decision log
references/planning-gates.mdScope Gate and Plan Gate contracts
references/architecture.mdBlueprint Rule, Re-injection, State Update
references/safety.mdBlast Radius, Patch-First, Zero-Trust, Dependency Freeze
references/cognition.mdThink Before Coding, Don't Guess Syntax, Human Checkpoint
references/cleanup.mdTech Debt format, Test Contract, Decision Log
references/anti-drift.mdAnchor Check, Session Scoping, Drift Trigger
references/operations.mdVerification evidence, git hygiene, dependency control
references/evidence-providers.mdExternal scanners, provenance, attestations, CI evidence, trust limits
references/research-and-fit.mdLive research gate, stack fit, product-shape guardrails
references/mcp-governance.mdMCP approval, toolset scope, credentials, consent, audit evidence
tools/lib/reference-selector.jsPath-based governance reference recommendations
tools/lib/risk-policy.jsRisk tier defaults, config merge, and validation
tools/receipt.jsGovernance receipt template and validation CLI

Version

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

Author

Justin Davis — MIT License

Ver o original no GitHub

Bom para

Relacionados