@carlrannaberg/cclint weekly downloads statistics

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)…