cclint (Claude Code Lint)

A comprehensive linting tool for Claude Code projects that validates agent definitions, command configurations, settings files, and project documentation.

Features

• Agent/Subagent Linting: Validates frontmatter, tools configuration, and naming conventions
• Command Linting: Checks slash command definitions and tool permissions
• Settings Validation: Validates .claude/settings.json hook configurations
• Documentation Linting: Ensures CLAUDE.md follows best practices and template structure
• Custom Schema Support: Extend base schemas with Zod for project-specific validation
• Project Auto-Detection: Automatically finds project root using directory climbing
• Multiple Output Formats: Console, JSON, and Markdown reports
• CI/CD Friendly: Configurable exit codes and quiet mode

Installation

# Install globally
npm install -g @carlrannaberg/cclint

# Install as dev dependency
npm install --save-dev @carlrannaberg/cclint

# Use without installing
npx @carlrannaberg/cclint

Usage

Basic Linting

# Lint current project (auto-detects root)
cclint

# Lint specific directory
cclint --root /path/to/project

# Quiet mode (minimal output)
cclint --quiet

# Verbose mode (show all files)
cclint --verbose

Specialized Linting

Lint only specific file types for faster, focused validation:

# Lint only agent definition files
cclint agents

# Lint only command definition files  
cclint commands

# Lint only settings.json files
cclint settings

# Lint only CLAUDE.md context files
cclint context

# Use with options for specialized linting
cclint agents --verbose --follow-symlinks
cclint commands --root /path/to/project --quiet

Report Generation

# Generate JSON report
cclint --format json --output lint-report.json

# Generate Markdown report
cclint --format markdown --output reports/lint-report.md

CI/CD Integration

# Fail on errors only (default)
cclint --fail-on error

# Fail on warnings or errors
cclint --fail-on warning

# Fail on suggestions, warnings, or errors
cclint --fail-on suggestion

# Disable custom schema validation
cclint --no-custom-schemas

Symlink Support

# Follow symlinks when discovering files (secure by default)
cclint --follow-symlinks

# Symlinks are NOT followed by default for security
# When enabled, validates that symlink targets remain within project root
# Useful for projects with shared agent/command definitions

SDK/Programmatic Usage

CCLint can be used programmatically in your Node.js applications:

import CClint from '@carlrannaberg/cclint';

// Create linter instance
const linter = new CClint();

// Lint entire project
const summary = await linter.lintProject('./my-project', {
  quiet: true,
  followSymlinks: true  // Enable symlink support
});

// Lint specific file types
const agentResults = await linter.lintAgents('./my-project');
const commandResults = await linter.lintCommands('./my-project');

Return Types Explained

lintProject() returns a LintSummary:

{
  totalFiles: 35,
  validFiles: 24,
  totalErrors: 11,
  totalWarnings: 2,
  totalSuggestions: 0,
  duration: 150,
  results: [...] // Array of all individual file results
}

lintAgents(), lintCommands(), etc. return LintResult[]:

[
  {
    file: '/path/to/agent.md',
    valid: true,
    errors: [],
    warnings: [],
    suggestions: [],
    missingFields: []
  },
  // ... more individual file results
]

Use Cases

• lintProject(): Full project validation, CI/CD integration, comprehensive reports
• lintAgents(): Validate only agent definitions, useful for agent-focused tools
• lintCommands(): Validate only command definitions, useful for command management tools
• lintSettings(): Validate settings.json, useful for configuration tools

What It Checks

Official Claude Code Fields

cclint validates against the official Claude Code specifications. Any additional fields must be added via custom schema extensions.

Agent/Subagent Frontmatter Fields

Required:

• name - Agent identifier (lowercase, alphanumeric with hyphens)
• description - Natural language description of when to invoke

Optional:

• tools or allowed-tools - Tool access: "*" for all, or array of tool names
• model - Preferred model: sonnet, opus, haiku, sonnet[1m], opusplan, inherit
• color - UI color (must be one of: red, blue, green, yellow, purple, orange, pink, cyan)

Command Frontmatter Fields

All fields are optional:

• description - Command description (defaults to first heading or line from content)
• allowed-tools - Tools the command can use (string format: "Tool1, Tool2")
• argument-hint - Hint for command arguments shown in UI
• model - Model to use (same values as agents)

Agent/Subagent Files (*.md with frontmatter)

• ✅ Required fields: name, description
• ✅ Tool configurations and syntax
• ✅ Color validation (8 valid Claude Code colors: red, blue, green, yellow, purple, orange, pink, cyan)
• ✅ Naming conventions and filename matching
• ⚠️ Unknown tools and deprecated fields
• 💡 Content optimization suggestions

Command Files (*.md with frontmatter)

• ✅ Frontmatter schema validation
• ✅ Tool permissions in allowed-tools
• ✅ Bash command usage validation
• ✅ File reference patterns
• ⚠️ Unknown tools and syntax errors
• 💡 Missing descriptions and argument hints

Settings Files (.claude/settings.json)

• ✅ JSON syntax and schema validation
• ✅ Hook configuration structure
• ✅ Event types and matchers
• ✅ Command syntax validation
• ⚠️ Unknown hook events and tools
• 💡 Configuration optimization suggestions

Documentation (CLAUDE.md/AGENTS.md)

• ✅ Required sections presence
• ✅ Document structure validation
• ✅ Template compliance checking
• ⚠️ Missing sections and content
• 💡 Content quality improvements

Project Structure Detection

cclint automatically detects your project root by climbing up directories looking for:

• .git directory
• package.json file
• .claude directory

It then scans for files in common locations:

project-root/
├── .claude/
│   ├── settings.json     # Settings validation
│   ├── agents/           # Agent definitions
│   └── commands/         # Command definitions
├── src/
│   ├── agents/           # Alternative agent location
│   └── commands/         # Alternative command location
├── CLAUDE.md             # Documentation validation
└── AGENTS.md             # Alternative documentation

Configuration

cclint works without configuration by using sensible defaults and auto-detection. For advanced usage, you can:

1. Specify custom paths with --root
2. Control output verbosity with --quiet/--verbose
3. Choose output formats with --format
4. Set failure thresholds with --fail-on
5. Create custom schemas with configuration files

Custom Schema Configuration

cclint supports extending the base validation schemas with your own Zod schemas for project-specific requirements.

Configuration Files

cclint looks for configuration in the following files (in order of precedence):

• cclint.config.js - JavaScript configuration
• cclint.config.mjs - ES Module configuration
• cclint.config.ts - TypeScript configuration (requires compilation)
• .cclintrc.json - JSON configuration
• .cclintrc.js - JavaScript configuration
• .cclintrc.mjs - ES Module configuration

JSON Configuration Example

{
  "agentSchema": {
    "extend": {
      "priority": "number",
      "tags": "array",
      "experimental": "boolean"
    }
  },
  "commandSchema": {
    "extend": {
      "timeout": "number",
      "retryCount": "number"
    }
  },
  "rules": {
    "unknownFields": "warning",
    "strict": true,
    "excludePatterns": ["**/legacy/**"]
  }
}

JavaScript Configuration Example

// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    extend: {
      // Custom fields for agents
      priority: z.number().min(1).max(5).describe('Agent priority level'),
      tags: z.array(z.string()).optional().describe('Categorization tags'),
      experimental: z.boolean().optional().describe('Experimental feature flag'),
      owner: z.string().email().describe('Agent maintainer email')
    },
    customValidation: (data) => {
      const errors = [];
      
      // Custom validation logic
      if (data.experimental && !data.description?.includes('EXPERIMENTAL')) {
        errors.push('Experimental agents must include "EXPERIMENTAL" in description');
      }
      
      if (data.priority > 3 && !data.owner) {
        errors.push('High priority agents must have an owner assigned');
      }
      
      return errors;
    }
  },
  
  commandSchema: {
    extend: {
      timeout: z.number().positive().describe('Command timeout in milliseconds'),
      retryCount: z.number().min(0).max(3).default(0),
      async: z.boolean().optional().describe('Run command asynchronously')
    },
    customValidation: (data) => {
      const errors = [];
      
      if (data.async && !data.timeout) {
        errors.push('Async commands must specify a timeout');
      }
      
      return errors;
    }
  },
  
  settingsSchema: {
    extend: {
      // Custom settings fields
      customHooks: z.record(z.array(z.string())),
      teamSettings: z.object({
        lead: z.string(),
        members: z.array(z.string())
      }).optional()
    }
  },
  
  claudeMdRules: {
    requiredSections: [
      'project overview',
      'setup instructions', 
      'development workflow',
      'testing strategy'
    ],
    customValidation: (content, sections) => {
      const errors = [];
      
      if (!content.includes('## Security')) {
        errors.push('CLAUDE.md must include a Security section');
      }
      
      return errors;
    }
  },
  
  rules: {
    unknownFields: 'error',
    strict: true,
    includePatterns: ['custom-agents/**'],
    excludePatterns: ['**/legacy/**', '**/deprecated/**']
  }
};

TypeScript Configuration Example

// cclint.config.ts
import { z } from 'zod';
import type { CclintConfig } from 'cclint';

const AgentPriority = z.enum(['low', 'medium', 'high', 'critical']);

const config: CclintConfig = {
  agentSchema: {
    extend: {
      priority: AgentPriority,
      team: z.string().min(1),
      version: z.string().regex(/^\d+\.\d+\.\d+$/)
    }
  }
};

export default config;

Schema Override Example

For complete control, you can override the entire schema:

// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    override: z.object({
      // Completely custom schema
      id: z.string().uuid(),
      name: z.string().min(1),
      version: z.string(),
      config: z.record(z.unknown())
    }).strict()
  }
};

Configuration Options

| Field | Type | Description | |-------|------|-------------| | agentSchema.extend | Record<string, ZodType> | Additional fields for agent frontmatter | | agentSchema.override | ZodType | Complete replacement for agent schema | | agentSchema.customValidation | (data) => string[] | Custom validation function | | commandSchema.* | Same as agent | Custom command schema configuration | | settingsSchema.* | Same as agent | Custom settings schema configuration | | claudeMdRules.requiredSections | string[] | Required sections in CLAUDE.md | | claudeMdRules.recommendedSections | string[] | Recommended sections | | claudeMdRules.customValidation | (content, sections) => string[] | Custom validation | | rules.unknownFields | 'error' \| 'warning' \| 'suggestion' \| 'ignore' | How to handle unknown fields | | rules.strict | boolean | Enable strict mode validation | | rules.includePatterns | string[] | Additional file patterns to include | | rules.excludePatterns | string[] | File patterns to exclude |

Examples

GitHub Actions Integration

name: Claude Code Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install -g @carlrannaberg/cclint
      - run: cclint --fail-on warning

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
cclint --quiet --fail-on error

Report Generation Script

#!/bin/bash
# scripts/lint-report.sh
mkdir -p reports
cclint --format markdown --output reports/claude-lint-$(date +%Y%m%d).md
echo "Lint report generated in reports/"

Exit Codes

• 0: Success (no issues above failure threshold)
• 1: Failure (issues found above failure threshold)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT

Related Projects

• Claude Code - AI-powered coding assistant