Skip to content

[20260312_DOCS] Updated links to match the current website docs that exist locally.

Configuration

Code Scalpel uses configuration files in the .code-scalpel/ directory to customize behavior and define governance policies.

Quick Start

Run the following command in your project root to create .code-scalpel/ with a full default configuration scaffold:

codescalpel init

If you have an existing .code-scalpel/ directory (e.g. after upgrading Code Scalpel), running init again will add any new files introduced in the current release without touching your existing customisations:

# Safe to re-run after upgrading
codescalpel init

# Then verify everything looks good
codescalpel check

See Configuration Management CLI below for full reference.

Configuration Files

File Purpose Required
config.json Core settings: tier, paths, feature flags Yes
policy.yaml Security & coding-style policy rules Yes
budget.yaml Change-budget limits for AI operations Yes
response_config.json Response verbosity & token-efficiency settings Yes
dev-governance.yaml Development governance rules Recommended
project-structure.yaml Project structure expectations Recommended
response_config.schema.json JSON schema for response_config.json Recommended
policy.manifest.json Cryptographic manifest for policy integrity Recommended
audit.log Audit trail for agent operations Recommended
policies/ Rego policy files (architecture, devops, security) Recommended
license/README.md License directory setup instructions Recommended
.gitignore Prevents accidental secret commits Optional
ide-extension.json IDE extension settings Optional
HOOKS_README.md Git hooks integration guide Optional

Governance Profiles

Choose a profile that matches your team:

Profile Team Size Compliance Use Case
Permissive Solo None Hobby projects, learning
Minimal 1-5 Basic Small teams, startups
Default 5-20 Standard Professional teams
Restrictive 20+ SOC2/ISO Enterprise, regulated

See the profile comparison above and governance.yaml for the policy knobs used to enforce it.

Example: Minimal Setup

For most projects, you only need config.json:

{
  "project_name": "My Project",
  "language": "python",
  "governance_profile": "minimal"
}

Example: Full Setup

After running codescalpel init, your .code-scalpel/ directory will look like:

.code-scalpel/
├── config.json                    # Core settings (required)
├── policy.yaml                    # Security & style rules (required)
├── budget.yaml                    # AI operation budgets (required)
├── response_config.json           # Response verbosity (required)
├── response_config.schema.json    # Schema for the above (recommended)
├── dev-governance.yaml            # Development governance (recommended)
├── project-structure.yaml         # Structure expectations (recommended)
├── policy.manifest.json           # Cryptographic policy manifest (recommended)
├── audit.log                      # Agent operation audit trail (recommended)
├── license/
│   └── README.md                  # License key setup instructions
├── policies/
│   ├── architecture/layered_architecture.rego
│   ├── devops/docker_security.rego
│   ├── devsecops/secret_detection.rego
│   └── project/structure.rego
├── .gitignore                     # Excludes secrets from git
└── README.md                      # Configuration reference

Configuration Sections

  • General Settings

    Basic project configuration, license paths, and feature toggles.

    config.json

  • Governance

    Define security policies, compliance rules, and approval workflows.

    governance.yaml

  • Response & Budgets

    Control response verbosity, token budgets, and AI operation limits through the generated configuration set and validation commands.

    Configuration CLI

Priority Order

When multiple configurations exist, they're applied in this order:

  1. Environment variables (highest priority)
  2. Local .code-scalpel/ (project-specific)
  3. User config (~/.code-scalpel/)
  4. System defaults (lowest priority)

Environment Variables

Override any setting with environment variables:

Variable Purpose
CODE_SCALPEL_LICENSE_PATH Path to license file
CODE_SCALPEL_CONFIG_DIR Custom config directory
CODE_SCALPEL_TIER Force specific tier
CODE_SCALPEL_LOG_LEVEL Logging verbosity

Validation

Validate and maintain your configuration with the built-in CLI commands:

# Audit which files are present, missing, or corrupt
codescalpel check

# Audit AND fix (adds missing files, never overwrites existing)
codescalpel check --fix

# Machine-readable output for CI pipelines
codescalpel check --json

# Add missing files without running a full check
codescalpel init

codescalpel check validates file integrity on every run: JSON and YAML files are parsed, Rego files are checked for a package declaration, and empty files are flagged. Exit code 1 means a required file is missing or corrupt.

Configuration Management CLI

Command Description
codescalpel init Create .code-scalpel/ or add missing files to an existing one
codescalpel check Audit files: presence, required vs. recommended, integrity
codescalpel check --fix Audit + add missing files in one step
codescalpel check --json Machine-readable audit output
codescalpel verify-policies Verify HMAC signatures on policy files
codescalpel regenerate-manifest Regenerate policy.manifest.json after editing Rego files

Next Steps