Camouf

> Camouf catches the mistakes AI coding assistants make — broken contracts, phantom imports, signature drift, and architectural violations that traditional linters miss entirely.

---

The Problem: AI Agents Forget Context

Claude, Copilot, and Cursor are brilliant at generating code — but they work with limited context windows. When an AI generates frontend code without seeing your backend contracts, or modifies a file without remembering related files, things break in ways that compile but fail at runtime:

``typescript
// Backend contract (shared/api.ts)
export function getUserById(id: string): Promise { ... }
export interface User { email: string; createdAt: Date; }

// AI generates frontend code (components/Profile.tsx) — looks correct, compiles fine
const user = await getUser(userId); // ❌ Wrong function name
console.log(user.userEmail); // ❌ Wrong field name
console.log(user.created_at); // ❌ Wrong casing
`

ESLint doesn't catch this. TypeScript passes. Your tests might even pass. Then production breaks.

---

How Camouf Solves It

Camouf scans your codebase for the specific patterns of errors that AI assistants create:

$3

| Error Type | Example | Traditional Tools |
|------------|---------|-------------------|
| Function Name Drift | getUser() instead of getUserById() | ❌ ESLint ignores it |
| Phantom Imports | import { validate } from './helpers' (file doesn't exist) | ❌ TypeScript ignores at lint time |
| Field Name Mismatch | user.userEmail instead of user.email | ❌ Compiles with any |
| Context Drift | Same concept named User/Customer/Account in different files | ❌ No tool detects this |
| Orphaned Functions | AI generates helpers that are never called | ❌ Tree-shaking hides it |
| Casing Inconsistency | getUserById / get_user_by_id in same project | ❌ Style issue, not error |

$3

`
Defined in shared/api.ts:15 Used in frontend/user.ts:42
getUserById(id) ◄────────── getUser(userId)
└── 75% similar — likely AI context loss
`

$3

`bash
npx camouf fix-signatures --all # Fix all mismatches automatically
npx camouf fix --id sig-001 # Fix a specific mismatch
`

---

Traditional Linters vs Camouf

| Aspect | ESLint / Prettier | Camouf |
|--------|-------------------|--------|
| Focus | Code style, syntax errors | Cross-file contract integrity |
| Scope | Single file at a time | Entire codebase relationships |
| AI Errors | Doesn't detect | Purpose-built for AI mistakes |
| Runtime Safety | No guarantee | Catches compile-but-fail bugs |
| Architecture | No awareness | Layer boundaries, DDD, dependencies |

Camouf is not a replacement for ESLint — it catches what ESLint can't see.

---

Why Camouf?

- AI-Native: Built specifically for Claude, Copilot, and Cursor error patterns
- Cross-File Analysis: Detects mismatches across your entire codebase
- Plugin Architecture: Extend with custom rules for React, Next.js, NestJS, or any framework
- Multi-language Support: TypeScript, JavaScript, Python, Java, Go, Rust
- CI/CD Ready: SARIF, JSON, JSOND outputs for GitHub Actions and AI agents
- VS Code Integration: Real-time Problems panel with clickable fixes

---

Features

- 13+ Built-in Rules: AI-specific and architecture validation rules
- Function/Field Matching: Fuzzy matching to detect AI naming drift
- Circular Dependency Detection: Find and break dependency cycles
- Real-time Watch Mode: Continuous architecture monitoring
- Security Scanning: Detects hardcoded secrets, API keys, credentials
- Multiple Report Formats: HTML, JSON, JSOND, Markdown, SARIF
- VS Code Integration: Problems panel with clickable quick-fixes
- Plugin System: Extend for any framework (React, Next.js, NestJS...)

---

Quick Start

$3

`bash
npm install -g camouf

or

npm install --save-dev camouf
`

$3

`bash
camouf init
`

$3

`bash
camouf validate
`

$3

`bash
camouf watch
`

---

Plugin System

Extend Camouf for any framework. Plugins can add rules, analyzers, parsers, quick-fixes, and output formatters.

`bash
npm install --save-dev camouf-plugin-react
`

`json
{
"plugins": ["camouf-plugin-react"],
"rules": {
"plugin": {
"missing-dependency-array": "error"
}
}
}
`

See Creating Plugins for building your own.

---

Official Plugins

| Plugin | Description | Status |
|--------|-------------|--------|
| camouf-plugin-react | React hooks dependency arrays, component naming, prop drilling, stale closures | ✅ Available |
| camouf-plugin-nextjs | Next.js page structure, API routes, middleware | 🔜 Coming Soon |
| camouf-plugin-nestjs | NestJS module boundaries, DI patterns | 🔜 Coming Soon |

$3

Catches AI-generated React mistakes:

`bash
npm install --save-dev camouf-plugin-react
`

Rules included:

| Rule | Description |
|------|-------------|
| missing-dependency-array | Detects useEffect/useCallback with missing dependencies |
| inconsistent-component-naming | Enforces PascalCase for React components |
| prop-drilling-detection | Finds excessive prop passing through component trees |
| stale-closure-patterns | Catches stale closures in hooks (common AI mistake) |

---

MCP Server (AI Agent Integration)

Camouf exposes an MCP (Model Context Protocol) server that allows AI agents like Claude, Cursor, and Copilot to validate their own code before proposing it to you.

$3

`bash
npx camouf mcp
`

$3

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

`json
{
"mcpServers": {
"camouf": {
"command": "npx",
"args": ["camouf", "mcp"],
"cwd": "/path/to/your/project"
}
}
}
`

$3

| Tool | Description |
|------|-------------|
| camouf_validate | Validate code against architecture rules |
| camouf_analyze | Analyze project structure and conventions |
| camouf_suggest_fix | Get fix suggestions for violations |

$3

When Claude generates code, it can call camouf_validate to check for:

- Hallucinated imports (modules that don't exist)
- Contract mismatches (wrong function signatures)
- Context drift (inconsistent naming)
- Security issues (hardcoded secrets)

This creates a feedback loop where AI catches its own mistakes before you see them.

---

Documentation

- Getting Started
- Creating Plugins
- AI Agent Challenges
- Configuring Rules
- CI/CD Integration
- Changelog

---

Commands

$3

Initialize Camouf configuration in your project.

`bash
camouf init [options]

Options:
-f, --force Overwrite existing configuration
-t, --template Use a predefined template (clean-architecture, microservices, monolith)
--agent Generate agent integration files (claude, codex, all)
`

$3

Analyze project architecture and generate reports.

`bash
camouf analyze [options]

Options:
-c, --config Path to configuration file
-o, --output Output directory for reports
-f, --format Report format (text, json, html, sarif)
--visualize Generate architecture visualization
--rules Comma-separated list of rules to run
`

$3

Start real-time architecture monitoring.

`bash
camouf watch [options]

Options:
-c, --config Path to configuration file
--debounce Debounce time in milliseconds (default: 300)
--format Output format: text (default), vscode
--ci CI/agent mode: no spinners, no colors
`

$3

Validate architecture against configured rules (CI/CD friendly).

`bash
camouf validate [options]

Options:
-c, --config Path to configuration file
--format Output format: text (default), json, sarif, vscode
--strict Fail on warnings
--bail Exit on first error
--ci CI/agent mode: no spinners, no colors
`

$3

Generate architecture report from existing analysis.

`bash
camouf report [options]

Options:
-i, --input Path to analysis JSON
-o, --output Output path for report
-f, --format Report format (html, json, markdown)
`

$3

Apply a single quick-fix by ID.

`bash
camouf fix [options]

Options:
--id Quick-fix ID (e.g., sig-001)
-c, --config Path to configuration file
--dry-run Preview changes without applying
`

$3

Fix all function/field signature mismatches.

`bash
camouf fix-signatures [options]

Options:
--all Fix all mismatches automatically
--interactive Confirm each fix interactively
--file Fix only mismatches in specific file
--type Fix only function or field mismatches
-c, --config Path to configuration file
--dry-run Preview changes without applying
--ci CI/agent mode: no prompts, use --all for auto-fix
`

Configuration

$3

Camouf supports multiple configuration formats:
- camouf.config.json
- camouf.config.yaml
- camouf.config.js
- .camoufrc

$3

`json
{
"name": "my-project",
"rootDir": "./src",
"exclude": ["/node_modules/", "*/.test.ts"],
"layers": [
{
"name": "presentation",
"directories": ["./src/controllers", "./src/routes"],
"allowedDependencies": ["application", "domain"]
},
{
"name": "application",
"directories": ["./src/services", "./src/usecases"],
"allowedDependencies": ["domain"]
},
{
"name": "domain",
"directories": ["./src/domain", "./src/entities"],
"allowedDependencies": []
},
{
"name": "infrastructure",
"directories": ["./src/infrastructure", "./src/repositories"],
"allowedDependencies": ["domain"]
}
],
"rules": {
"builtin": {
"layer-dependencies": "error",
"circular-dependencies": "error",
"function-signature-matching": "error",
"performance-antipatterns": "warn",
"type-safety": "warn",
"data-flow-integrity": "error",
"distributed-transactions": "warn",
"api-versioning": "info",
"security-context": "error",
"resilience-patterns": "warn",
"ddd-boundaries": "info"
}
},
"output": {
"format": "text",
"colors": true,
"verbose": false
}
}
`

Built-in Rules

$3

| Rule | Description | Default |
|------|-------------|---------|
| layer-dependencies | Validates layer boundary compliance | error |
| circular-dependencies | Detects circular dependency cycles | error |
| contract-mismatch | Validates API contracts (OpenAPI/GraphQL) | error |
| ddd-boundaries | Validates DDD principles and bounded contexts | warn |
| function-signature-matching | Detects mismatched function/field names between contracts and usage | error |

$3

| Rule | Description | Default |
|------|-------------|---------|
| hardcoded-secrets | Detects hardcoded API keys, passwords, and tokens | error |
| data-flow-integrity | Validates data flow and input sanitization | error |
| security-context | Validates authentication and authorization | error |

$3

| Rule | Description | Default |
|------|-------------|---------|
| distributed-transactions | Validates distributed transaction patterns | warn |
| resilience-patterns | Validates circuit breakers, retries, timeouts | warn |

$3

| Rule | Description | Default |
|------|-------------|---------|
| performance-antipatterns | Detects N+1 queries, memory leaks | warn |
| type-safety | Detects unsafe type usage | warn |
| api-versioning | Validates API versioning practices | info |

$3

These rules catch mistakes that AI coding assistants commonly make:

| Rule | Description | Default |
|------|-------------|---------|
| ai-hallucinated-imports | Detects imports of non-existent files/modules | error |
| context-drift-patterns | Finds same concepts with different names across files | warn |
| phantom-type-references | Catches references to types that don't exist | warn |
| inconsistent-casing | Detects mixing of camelCase/snake_case in the same codebase | warn |
| orphaned-functions | Finds functions declared but never called anywhere | warn |

> See examples: Check test-fixtures/ai-errors/ in the repository for concrete examples of what each rule catches.

Report Formats

$3

Real-time colored output with violation details.

$3

Compact machine-readable format for CI/CD integration.

$3

JSON with Descriptions — A structured format optimized for AI agent consumption with rich context and actionable information.

`bash
npx camouf validate --format jsond
`

JSOND includes:
- Detailed descriptions for every field
- Violations grouped by file, rule, and severity
- AI-specific action items and priorities
- Ready-to-run fix commands
- Workflow instructions for automated remediation

Example output:
`json
{
"$description": "Camouf Architecture Violations Report - JSOND format optimized for AI agents",
"summary": {
"total_violations": 3,
"by_severity": {
"errors": {
"count": 2,
"description": "Critical violations that must be fixed..."
}
}
},
"action_items": [
{
"priority": "critical",
"action": "Remove hardcoded secrets",
"quick_fix": "Move secrets to environment variables"
}
],
"ai_instructions": {
"recommended_workflow": [
"1. Review the summary to understand the scope",
"2. Prioritize errors over warnings",
"3. Use 'suggestion' field for fixes"
]
}
}
`

$3

Interactive visualization with dependency graphs.

$3

Static Analysis Results Interchange Format for IDE integration.

$3

Documentation-friendly format for pull requests.

VS Code Integration

Camouf integrates seamlessly with VS Code's Problems panel for real-time violation feedback.

$3

When you run camouf init, it automatically creates:
- .vscode/tasks.json - Build tasks with problem matchers
- .vscode/settings.json - Optimal settings for Camouf

$3

#### Option 1: Run Tasks (Recommended)

1. Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (Mac)
2. Select one of the tasks:
- camouf: Validate - One-time scan, results in Problems panel
- camouf: Watch - Continuous monitoring (background task)

3. Open the Problems panel: Ctrl+Shift+M

#### Option 2: Terminal Commands

`bash

One-time validation with VS Code output format

npx camouf validate --format vscode

Watch mode with VS Code output format

npx camouf watch --format vscode
`

$3

Violations appear in the Problems panel with:
- Severity icon (error/warning/info)
- File location (clickable link)
- Rule ID and message
- Suggestion for fix

`
test.ts(10,1): error hardcoded-secrets: AWS Access Key ID detected
src/api.ts(45,1): warning performance-antipatterns: N+1 query pattern detected
`

$3

If you didn't run camouf init or need to add tasks manually, create .vscode/tasks.json:

`json
{
"version": "2.0.0",
"tasks": [
{
"label": "camouf: Validate",
"type": "shell",
"command": "npx camouf validate --format vscode",
"problemMatcher": {
"owner": "camouf",
"fileLocation": ["relative", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.+)\\((\\d+),(\\d+)\\):\\s+(error|warning|info)\\s+([^:]+):\\s+(.*)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"code": 5,
"message": 6
}
}
}
]
}
`

AI Agent Integration

Camouf integrates natively with AI coding agents. Use camouf init --agent to generate the appropriate configuration files.

$3

`bash
camouf init --agent claude
`

This creates:
- CLAUDE.md — Project instructions teaching Claude how to use Camouf
- .claude/commands/camouf-validate.md — /camouf-validate slash command for architecture-aware validation
- .claude/commands/camouf-fix.md — /camouf-fix slash command to automatically fix violations
- .claude/rules/camouf.md — Architecture rules loaded into every Claude session

Claude Code will automatically read these files and enforce architecture rules when writing code.

$3

`bash
camouf init --agent codex
`

This creates:
- AGENTS.md — Agent instructions with Camouf commands, output format, and workflow

Codex reads AGENTS.md and knows how to validate architecture before committing.

$3

`bash
camouf init --agent all
`

Generates integration files for all supported agents (Claude Code + Codex).

$3

For AI agent consumption, use JSOND format (recommended):

`bash
npx camouf validate --format jsond --ci
`

JSOND provides rich context and actionable instructions optimized for AI assistants:

`json
{
"$description": "Camouf Architecture Violations Report",
"summary": {
"total_violations": 2,
"by_severity": {
"errors": { "count": 1, "description": "Critical violations..." }
}
},
"action_items": [
{
"priority": "critical",
"action": "Remove hardcoded secrets",
"quick_fix": "npx camouf fix --id sec-001"
}
],
"ai_instructions": {
"recommended_workflow": [
"1. Review summary",
"2. Prioritize errors",
"3. Apply quick fixes"
]
}
}
`

For simpler JSON output:

`bash
npx camouf validate --format json --ci
`

CI/CD Integration

$3

Use --ci flag or CAMOUF_CI=1 environment variable for agent/CI environments:

`bash

Suppress spinners, colors, interactive prompts

npx camouf validate --ci

JSON output automatically enables CI mode

npx camouf validate --format json

Environment variable alternative

CAMOUF_CI=1 npx camouf validate
`

$3

- 0 — No violations found
- 1 — Violations found (or error)

$3

`yaml
name: Architecture Check
on: [push, pull_request]

jobs:
architecture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci
- run: npx camouf validate --strict
`

$3

`yaml
architecture:
stage: test
image: node:18
script:
- npm ci
- npx camouf validate --strict
`

Multi-language Support

| Language | Parser | Features |
|----------|--------|----------|
| TypeScript | ts-morph | Full AST analysis, type resolution |
| JavaScript | ts-morph | ES6+ module support |
| Python | tree-sitter | Import/export detection |
| Java | tree-sitter | Package and class analysis |
| Go | tree-sitter | Module and import analysis |
| Rust | tree-sitter | Crate and module analysis |

Architecture Visualization

Generate interactive HTML visualizations:

`bash
camouf analyze --visualize -o ./reports
`

Export to GraphViz DOT format:

`bash
camouf analyze --visualize -f dot -o ./reports
`

Extending Camouf

$3

For project-specific rules, implement the IRule interface:

`typescript
import { IRule, RuleContext, RuleResult } from 'camouf';

export class MyCustomRule implements IRule {
readonly id = 'my-custom-rule';
readonly name = 'My Custom Rule';
readonly description = 'Description of what the rule checks';
readonly severity = 'warning';
readonly tags = ['custom'];

async check(context: RuleContext): Promise {
// Your rule logic here
return { violations: [] };
}
}
`

Register custom rules in configuration:

`json
{
"rules": {
"custom": [
"./rules/my-custom-rule.js"
]
}
}
`

For framework-specific rules and publishing plugins, see Creating Plugins.

Docker

`bash
docker run -v $(pwd):/app ghcr.io/camouf/camouf analyze
``

License

Apache 2.0 - See LICENSE for details.

Contributing

Contributions are welcome. Please read the contributing guidelines before submitting pull requests.

Links

- npm Package
- GitHub Repository
- Epixiom Web & Marketing