ccaudit

Audit tool for Claude Code projects. Runs compliance checks on code and agent actions from .ccaudit/audits/ directories.

Installation

# Via npm (recommended)
npm install -g @ccdevkit/ccaudit

# Via Go
go install github.com/ccdevkit/ccaudit/cmd/ccaudit@latest

Quick Start

# List available audits
ccaudit list

# Run an audit
ccaudit run security

# Run with verbose output
ccaudit run security -v

Concepts

Audit

An audit is a named collection of checks. An audit is defined by a directory in .ccaudit/audits/{name}/ containing an audit.yaml file. The directory name becomes the audit name.

.ccaudit/audits/
├── security/
│   ├── audit.yaml       # Required - defines the audit
│   ├── check-secrets.sh # Shell check
│   └── check-xss.md     # Agent check
└── quality/
    └── audit.yaml

Check

A check is an individual verification test. Two types exist:

Shell checks (.sh files): Execute shell scripts. Exit code 0 = pass, 1 = fail. Stdout on failure becomes the failure reason.

#!/bin/bash
# ---
# name: check-secrets
# ---
if grep -r "API_KEY=" .; then
    echo "Hardcoded API key found"
    exit 1
fi
exit 0

Agent checks (.md files): Use Claude to analyze code or agent actions. The markdown content is the audit prompt.

---
name: check-code-quality
model: sonnet  # Optional: haiku (default), sonnet, opus
---

Review the code for:
1. Complex functions that should be refactored
2. Inconsistent error handling
3. Missing input validation

Check vs Audit

• Check: Single verification (one .sh or .md file)
• Audit: Collection of checks (directory with audit.yaml)

Checks run in parallel by default, respecting any declared dependencies.

audit.yaml

The audit.yaml file configures the audit:

cwd: ../..                   # Working directory for checks (relative to audit.yaml)
checks:
  - ../shared/*              # All checks from shared/ directory
  - ../other-audit           # All checks from another audit (recursively)
  - ./check-custom.sh        # Specific check file
  - file: ./check-slow.sh    # Object syntax with dependencies
    dependencies:
      - ./check-setup.sh     # Must complete before check-slow.sh runs

Fields

| Field | Description | |-------|-------------| | cwd | Working directory for all checks (absolute or relative to audit.yaml). Default: where ccaudit was invoked. | | checks | List of checks to run. Supports strings or objects with file and dependencies. |

Check Discovery

• No checks: field: All .sh and .md files in the audit directory are loaded (default)
• checks: with items: Only the specified items are loaded (exclusive mode)
• checks: [] (empty): No checks are loaded (audit runs nothing)

Paths are relative to the audit directory. Wildcards (*, ?, [...]) are supported.

Dependencies

Checks can declare dependencies to control execution order:

checks:
  - ./setup.sh
  - file: ./test.sh
    dependencies: ./setup.sh          # Single dependency (string)
  - file: ./integration.sh
    dependencies:                      # Multiple dependencies (array)
      - ./setup.sh
      - ./test.sh

Checks with satisfied dependencies run in parallel. Dependent checks wait for their prerequisites to complete.

Configuration

Settings file: .ccaudit/settings.json (project) or ~/.ccaudit/settings.json (global)

{
  "claudeCommand": "claude --local",
  "claudeCommandSummary": "~/.local/bin/claude",
  "maxRunners": 4
}

| Setting | Default | Description | |---------|---------|-------------| | claudeCommand | claude | Command to invoke Claude CLI (supports arguments) | | claudeCommandSummary | claude | Command for internal summary operations (MCP haiku calls) | | maxRunners | 0 | Maximum parallel check runners. 0 = unlimited parallelism. |

CLI Reference

ccaudit run <audit-name>    Execute an audit
  -v, --verbose             Enable debug output
  --output <mode>           Force output mode: interactive, plain, or hook

ccaudit list                List available audits
  -v, --verbose             Enable debug output

ccaudit completion <shell>  Generate shell completion script
                            Shells: bash, zsh, fish, powershell

Shell Completion

Tab completion is automatically installed when using npm. For manual setup:

# Bash
ccaudit completion bash > /etc/bash_completion.d/ccaudit

# Zsh
ccaudit completion zsh > "${fpath[1]}/_ccaudit"

# Fish
ccaudit completion fish > ~/.config/fish/completions/ccaudit.fish

Output Modes

• Interactive: TUI with spinner and progress (default in terminal)
• Plain: Text output (default when piped)
• Hook: JSON output for Claude Code hook integration (auto-detected from stdin)

Claude Code Hook Integration

Run ccaudit as a Claude Code hook to audit agent actions in real-time:

{
  "hooks": {
    "Stop": [
      {
        "command": "ccaudit run security"
      }
    ]
  }
}

Supported hook events: PreToolUse, PostToolUse, Stop, UserPromptSubmit

When running as a hook:

• Hook context is read from stdin (JSON with hook_event_name, cwd, transcript_path, etc.)
• Agent checks gain access to MCP tools (get_history, get_instructions) for inspecting the audited session
• Output is JSON on failure only

Check Frontmatter

All checks require a name field in YAML frontmatter:

Shell:

#!/bin/bash
# ---
# name: check-name
# requires: transcript  # Optional: skip if no transcript available
# ---

Markdown:

---
name: check-name
model: haiku           # Optional: haiku (default), sonnet, opus
requires: transcript   # Optional: skip if no transcript available
---

Frontmatter Fields

| Field | Applies to | Description | |-------|-----------|-------------| | name | Both | Check name (required) | | model | Agent only | AI model to use: haiku (default), sonnet, opus | | requires | Both | Requirements that must be met. Currently supports transcript to skip when running standalone (not as a hook). |

Agent Check Behavior

Agent checks run in read-only mode. They can use Read, Glob, Grep, and Bash (for read operations only).

When running as a hook with transcript access, agent checks also have MCP tools to inspect the audited session's history and actions.

Agent checks return structured JSON:

{
  "passed": false,
  "reason": "Single failure explanation",
  "failures": ["Issue 1", "Issue 2"],
  "hint": "How to fix"
}

Project Structure

.ccaudit/
├── settings.json           # Optional configuration
└── audits/
    ├── my-audit/
    │   ├── audit.yaml      # Required
    │   ├── check-foo.sh
    │   └── check-bar.md
    └── shared/
        └── check-common.sh

Exit Codes

• 0: All checks passed (skipped checks don't affect exit code)
• 1: At least one check failed or error occurred