The code quality guardrail for AI-assisted development

Cursor, Copilot, Claude Code — they write code 10x faster.
archguardian makes sure that code doesn't wreck your codebase.

---

npx archguardian init    # adds config + git hook — one command, done
npx archguardian scan    # full project scan
npx archguardian fix     # auto-fix findings
git commit               # hook blocks bad code automatically

The problem

You're shipping faster than ever with AI coding tools. But speed without guardrails is how you end up with:

• Hardcoded API keys that Copilot autocompleted from training data
• Unused imports that Cursor added and never cleaned up
• as any everywhere because the AI couldn't figure out the types
• Copy-paste blocks generated 5 times with slightly different variable names
• Architecture violations where the AI imported the database layer directly from UI components
• Inconsistent naming across files — camelCase here, snake_case there, PascalCase somewhere else
• Overly complex functions with deeply nested conditionals that no one can review
• Insecure Dockerfiles running as root with :latest tags and exposed secrets

Code review catches some of it. But at 3 PRs a day with 500+ lines of AI-generated code each, reviewers are overwhelmed.

archguardian catches all of it, automatically, before the commit even happens.

How it works

1. You commit code (written by you, Copilot, Cursor, Claude, or any AI tool)
2. archguardian's pre-commit hook kicks in — analyzes only changed lines
3. Real AST parsing via ast-grep (native tree-sitter bindings) — not regex hacks
4. 34 built-in rules across 13 analyzers run in parallel in under 1 second
5. Bad code gets blocked with clear, actionable messages. Clean code passes instantly.

What it catches

Security Hardcoded secrets (AWS, GitHub, Slack, Stripe, Google, JWTs, DB URLs — 11 patterns) SQL injection via template literals XSS: innerHTML, dangerouslySetInnerHTML, document.write eval() / Function() usage ReDoS-prone regex Taint analysis with cross-file tracking Custom patterns via config	AI code smells Excessive comment-to-code ratio Unused imports (AST-verified, not regex) Catch blocks larger than try blocks Duplicate code blocks in the same diff as any type assertions Excessive ! non-null operators	Conventions Functions: camelCase Classes / interfaces: PascalCase Constants: UPPER_SNAKE Files: kebab-case All configurable per project Per-language overrides
Duplicates AST structural hashing (ignores variable names and literals) Jaccard token similarity (configurable threshold) Catches the "AI generated 5 similar functions" pattern	Architecture Define layers (UI, Service, Repository, Domain) Enforce allowed/denied import directions Catches boundary violations at commit time	Complexity Cyclomatic complexity (branch count) Cognitive complexity (nesting-weighted) Configurable thresholds per project Multi-language support
IaC Security Dockerfile: root user, :latest tags, curl|bash, exposed secrets, ADD vs COPY, missing HEALTHCHECK Kubernetes: privileged containers, missing resource limits, :latest image tags GitHub Actions: script injection, mutable action references	Dead Code & Coverage Unused export detection via dependency graph Test coverage integration (lcov, Istanbul) Flags uncovered new/changed code Configurable coverage thresholds	Supply Chain Dependency vulnerability scanning (OSV database) License compliance checking (allowed/denied lists) SBOM generation (CycloneDX 1.5 / SPDX 2.3) Structural YAML rules (ast-grep patterns)

Works with your stack

TypeScript, JavaScript, TSX, JSX, Python, Go, Rust, Java — powered by ast-grep native tree-sitter bindings. Real AST parsing, not regex pattern matching.

Quick start

# Install and initialize in your project
npx archguardian init

That's it. archguardian creates .archguard.yml and installs a git pre-commit hook. Every commit is now guarded.

Configuration

version: 1
languages: [typescript, javascript, python, go, rust, java]
include: ["src/**"]
exclude: ["**/*.test.ts", "**/node_modules/**"]

severity:
  failOn: error       # error | warning | info
  maxWarnings: 20

analyzers:
  security:
    enabled: true
    severity: error
  aiSmells:
    enabled: true
    severity: warning
    commentRatio: 0.4
  conventions:
    enabled: true
    naming:
      functions: camelCase
      classes: PascalCase
      constants: UPPER_SNAKE
      files: kebab-case
  duplicates:
    enabled: true
    similarity: 0.85
  architecture:
    layers:
      - name: ui
        patterns: ["src/components/**", "src/pages/**"]
      - name: service
        patterns: ["src/services/**"]
      - name: repository
        patterns: ["src/repositories/**"]
    rules:
      - from: ui
        deny: [repository]
  complexity:
    enabled: true
    severity: warning
    maxCyclomatic: 15
    maxCognitive: 20
  iac:
    enabled: true
    dockerfile: true
    kubernetes: true
    actions: true
  deadCode:
    enabled: true
    entryPoints: ["src/index.ts"]
  coverage:
    enabled: true
    reportPath: "coverage/lcov.info"
    minCoverage: 80
    minNewCodeCoverage: 90
  licenses:
    enabled: true
    allowed: ["MIT", "Apache-2.0", "ISC", "BSD-*"]
    denied: ["GPL-*", "AGPL-*"]
  taint:
    enabled: true
    crossFile: true

# Monorepo workspace overrides
workspaces:
  "packages/api/**":
    analyzers:
      security: { enabled: true, severity: error }
      complexity: { maxCyclomatic: 10 }
  "packages/ui/**":
    analyzers:
      conventions: { severity: warning }

# Structural YAML rules (ast-grep patterns)
rules:
  astgrep: "rules/"   # directory of .yml rule files

Adopting on an existing codebase

Don't want 500 warnings on day one? Use baseline mode:

archguardian scan --update-baseline      # snapshot current state
archguardian scan                         # only shows NEW findings from now on

Findings are matched by ruleId + file + message (not line number), so baseline entries survive code edits.

Inline suppression

Silence false positives without disabling rules globally:

// archguard-ignore security/xss
el.innerHTML = sanitized;                   // suppress specific rule

doSomething(); // archguard-ignore-line     // suppress all rules on this line

Works with //, #, and /* */ comment styles.

CLI reference

archguardian init                                 Create config + install git hook
archguardian check [--format] [--post-to-pr]      Analyze staged changes (pre-commit)
archguardian scan  [--format] [--post-to-pr]      Analyze full project
archguardian fix   [--dry-run] [--ai]             Auto-fix findings
archguardian learn [--apply]                      Infer conventions from your codebase
archguardian rules [--json]                       List all 34 built-in rules
archguardian metrics [--json]                     Findings trend over time
archguardian dashboard [--port]                   Web dashboard on localhost
archguardian dismiss <ruleId> [--pattern]         Dismiss finding patterns from future scans
archguardian summarize [--format] [--post-to-pr]  Visual change summary with impact diagram
archguardian diagram [--format] [--scope]         Architecture dependency diagram
archguardian sbom [--format cyclonedx|spdx]       Generate Software Bill of Materials

Output formats: terminal (default), json, sarif

Exit codes: 0 pass, 1 errors found, 2 warnings exceeded threshold, 3 config error, 4 quality gate failure

GitHub PR integration

Post findings directly as inline review comments on pull requests:

archguardian scan --post-to-pr    # posts findings as PR review comments
archguardian summarize --post-to-pr  # posts summary as PR comment

Requires GITHUB_TOKEN, GITHUB_REPOSITORY, and GITHUB_PR_NUMBER environment variables (auto-set in GitHub Actions).

SBOM generation

Generate a Software Bill of Materials for compliance and supply chain security:

archguardian sbom --format cyclonedx > sbom.json   # CycloneDX 1.5
archguardian sbom --format spdx > sbom.json         # SPDX 2.3

Collects dependencies from package.json, go.mod, Cargo.toml, and pom.xml. Outputs include PURLs for each component.

Use with AI coding tools

archguardian ships with ready-made slash commands for all major AI coding assistants. After npx archguardian init, just type /scan, /fix, or /check in your AI tool.

Command	What it does
/scan	Full project scan, findings grouped by severity
/check	Analyze staged changes before committing
/fix	Auto-fix unused imports and naming violations
/baseline	Snapshot current findings for incremental adoption
/suppress	Add inline suppression comments for false positives
/setup	Initialize archguardian in a new project
/complexity	Analyze cyclomatic and cognitive complexity
/dead-code	Detect unused exports and dead code
/sbom	Generate Software Bill of Materials
/iac	Scan Dockerfiles, Kubernetes, GitHub Actions
/licenses	Check dependency license compliance
/coverage	Integrate test coverage reports

Claude Code

archguardian includes skills (.claude/skills/) that register as slash commands automatically.

.claude/skills/
├── scan/SKILL.md        →  /scan
├── check/SKILL.md       →  /check
├── fix/SKILL.md         →  /fix
├── baseline/SKILL.md    →  /baseline
├── suppress/SKILL.md    →  /suppress
├── setup/SKILL.md       →  /setup
├── complexity/SKILL.md  →  /complexity
├── dead-code/SKILL.md   →  /dead-code
├── sbom/SKILL.md        →  /sbom
├── iac/SKILL.md         →  /iac
├── licenses/SKILL.md    →  /licenses
└── coverage/SKILL.md    →  /coverage

How it works: Clone or install archguardian, and the skills are available immediately. Type /scan in Claude Code and it runs npx archguardian scan --format json, parses findings, explains each one, and offers to fix or suppress.

Skills use SKILL.md frontmatter with allowed-tools, $ARGUMENTS substitution, and description fields so Claude can also invoke them automatically when relevant.

Cursor

archguardian includes both rules (.cursor/rules/) for background context and slash commands (.cursor/commands/) for invocable actions.

.cursor/
├── rules/
│   ├── archguardian.mdc    # Always-on project context
│   └── ...                  # Agent-requested contexts
└── commands/
    ├── scan.md              →  /scan
    ├── check.md             →  /check
    ├── fix.md               →  /fix
    ├── complexity.md        →  /complexity
    ├── dead-code.md         →  /dead-code
    ├── sbom.md              →  /sbom
    ├── iac.md               →  /iac
    ├── licenses.md          →  /licenses
    └── coverage.md          →  /coverage

Type /scan in Cursor Agent chat to run a full project scan.

GitHub Copilot

archguardian includes prompt files (.github/prompts/) that register as slash commands in VS Code.

.github/
├── copilot-instructions.md      # Always-on project context
└── prompts/
    ├── scan.prompt.md            →  /scan
    ├── check.prompt.md           →  /check
    ├── fix.prompt.md             →  /fix
    ├── complexity.prompt.md      →  /complexity
    ├── iac.prompt.md             →  /iac
    └── ...

Type /scan in Copilot Chat to run a full project scan.

Windsurf

archguardian includes workflows (.windsurf/workflows/) and rules (.windsurf/rules/).

.windsurf/
├── rules/
│   └── rules.md                 # Always-on project context
└── workflows/
    ├── scan.md                   →  /scan
    ├── check.md                  →  /check
    ├── fix.md                    →  /fix
    ├── complexity.md             →  /complexity
    ├── iac.md                    →  /iac
    └── ...

Type /scan in Windsurf Cascade to run a full project scan.

Cline

archguardian includes rules (.clinerules/) for project context. Cline also auto-detects the .cursor/rules/ files.

Aider

archguardian works with Aider via the .aider.conf.yml config which loads CLAUDE.md as read-only context:

read:
  - CLAUDE.md

Tip: All commands use --format json under the hood. JSON output is structured and easier for AI tools to parse, explain, and act on.

CI/CD

GitHub Action

- uses: ysfAskri/archguardian@v1
  with:
    format: sarif           # uploads to GitHub Security tab
    quality-gate: true      # enforce quality thresholds
    post-to-pr: true        # post findings as inline PR comments

Any CI

npx archguardian scan --format sarif > results.sarif
npx archguardian scan --post-to-pr    # inline PR review comments
npx archguardian sbom --format cyclonedx > sbom.json

VS Code Extension

The vscode-extension/ directory contains a VS Code extension with:

• Inline diagnostics for all archguardian findings
• Code actions: quick-fix with AI and inline suppression
• Auto-scan on file save
• Status bar showing finding count

LLM-powered suggestions

Get AI-powered fix suggestions for findings. Supports OpenAI, Anthropic, and Gemini:

llm:
  enabled: true
  provider: anthropic   # openai | anthropic | gemini

Set your API key via OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY. Responses are cached locally to avoid repeated API calls.

Plugins

Extend with custom analyzers:

plugins:
  - archguardian-plugin-my-rules

Each plugin exports an analyzer class. See plugin docs for details.

Structural YAML rules

Define custom rules using ast-grep patterns in YAML files:

# rules/no-console-log.yml
id: no-console-log
language: typescript
rule: "console.log($$$ARGS)"
message: "Avoid console.log in production code"
severity: warning

# .archguard.yml
rules:
  astgrep: "rules/"

How it compares

archguardian is not a replacement for ESLint or SonarQube. It solves a different problem: catching the patterns AI coding tools introduce, with zero setup friction.

	archguardian	ESLint	SonarQube	CodeRabbit	Semgrep
AI-specific code smells	Built-in	Partial	No	No	No
Architecture enforcement	Built-in	Via plugin	Paid only	No	No
Complexity metrics	Built-in	Via plugin	Built-in	No	No
IaC security scanning	Built-in	No	No	No	Via rules
Dead code detection	Built-in	Via plugin	Built-in	No	No
SBOM generation	Built-in	No	No	No	No
License compliance	Built-in	No	Paid only	No	No
Coverage integration	Built-in	No	Built-in	No	No
Cross-file taint analysis	Built-in	No	Paid only	No	Built-in
PR inline review bot	Built-in	No	Via plugin	Built-in	Via app
Monorepo workspaces	Built-in	Via config	Built-in	Built-in	Via config
Pre-commit hook	One command	Manual	No	No	Built-in
Speed on typical diffs	< 1 second	1-5s	Minutes	N/A	1-5s
Languages	8	JS/TS core	20+	Many	30+
AI tool integrations	6 tools	None	SonarLint	GitHub	None
Pricing	Free (MIT)	Free (MIT)	Freemium	Freemium	Freemium

Use archguardian when you want a fast, zero-config guardrail purpose-built for AI-assisted development. Use ESLint when you need deep JavaScript/TypeScript linting with hundreds of configurable rules. Use SonarQube when you need enterprise-grade code quality across a large org with dashboards, quality gates, and compliance reporting. They work well together — archguardian catches what the others miss in the pre-commit stage.

Contributing

git clone https://github.com/ysfAskri/archguardian.git
cd archguardian && npm install
npm test           # 273 tests
npm run build      # builds to dist/

Project structure

src/
├── cli/          Commander.js entry + 12 commands + output formatters (terminal, JSON, SARIF)
├── core/         Pipeline, config loader, diff parser, suppression, baseline, workspace resolver, dependency collector, types
├── parsers/      ast-grep NAPI parser (TS/JS/Python/Go/Rust/Java) + AST utilities
├── analyzers/    Security, AI smells, conventions, duplicates, layer violations, complexity, IaC, dead code, coverage, licenses, taint (cross-file), structural rules
├── plugins/      Dynamic plugin loader for external analyzers
├── llm/          LLM client (OpenAI, Anthropic, Gemini), prompt builder, file-based cache
├── fixes/        Auto-fix engine (remove unused imports, rename conventions, AI-powered)
├── metrics/      Run history tracker (.archguard/metrics.json)
├── hooks/        Git hook installer (direct + Husky)
├── ci/           GitHub annotator + PR review bot + PR summary commenter
└── utils/        Git operations, logging, perf timing

License

MIT

---

_{Built by Youssef ASKRI}