Configuration

Customize ClaudeKit CLI behavior with config files, environment variables, and project-specific settings.

Configuration Files

ClaudeKit CLI uses multiple configuration files at different levels.

Global CLI Config

Location: ~/.claudekit/config.json

Purpose: Store CLI defaults and authentication

Structure:

{
  "github": {
    "token": "stored_in_keychain"
  },
  "defaults": {
    "kit": "engineer",
    "dir": "."
  }
}

Auto-created: Yes, on first run

Fields:

Project Config

Location (Local): .claude/.ck.json Location (Global): ~/.claude/.ck.json

Purpose: Store project-specific folder configuration

Structure:

{
  "folders": {
    "docs": "documentation",
    "plans": "planning"
  }
}

Auto-created: When using custom folder names

Fields:

ClaudeKit Metadata

Location (Local): .claude/metadata.json Location (Global): ~/.claude/metadata.json

Purpose: Track installation version and ownership

Structure (Single Kit):

{
  "name": "ClaudeKit Engineer",
  "version": "1.17.0",
  "installedAt": "2025-01-15T10:30:00.000Z",
  "mode": "local",
  "files": [
    {
      "path": "agents/planner/agent.json",
      "hash": "sha256-abc123...",
      "ownership": "ck",
      "installedVersion": "1.17.0"
    }
  ]
}

Structure (Multi-Kit):

{
  "version": "1.17.0",
  "installedAt": "2025-01-15T10:30:00.000Z",
  "mode": "local",
  "kits": {
    "engineer": {
      "name": "ClaudeKit Engineer",
      "version": "1.17.0",
      "installedAt": "2025-01-15T10:30:00.000Z",
      "files": [ /* file tracking */ ]
    },
    "marketing": {
      "name": "ClaudeKit Marketing",
      "version": "1.5.0",
      "installedAt": "2025-01-16T14:20:00.000Z",
      "files": [ /* file tracking */ ]
    }
  }
}

Auto-created: Yes, by ck new or ck init

Fields:

Environment Variables

Configure CLI behavior via environment variables.

Authentication

GITHUB_TOKEN

Purpose: GitHub personal access token for API authentication

Fallback order:

1. GitHub CLI (gh auth token)
2. GITHUB_TOKEN environment variable
3. Config file (~/.claudekit/config.json)
4. OS keychain
5. User prompt

Usage:

export GITHUB_TOKEN=ghp_abc123...
ck new

Note: GitHub CLI (gh auth login) is recommended over PAT.

Behavior

CI

Purpose: Detect CI/CD environment, enable non-interactive mode

Values: "true" or "false"

Usage:

CI=true ck init --release v1.16.0

Effect:

• Disables interactive prompts
• Requires explicit --release flag for version selection
• Skips confirmation prompts

NON_INTERACTIVE

Purpose: Force non-interactive mode

Values: "true" or "false"

Usage:

NON_INTERACTIVE=true ck new --kit engineer --dir ./project

Effect: Same as CI=true

NO_UPDATE_NOTIFIER

Purpose: Disable update notifications

Values: "1" or any truthy value

Usage:

export NO_UPDATE_NOTIFIER=1
ck --version  # No update notification shown

Permanent:

# Add to ~/.bashrc or ~/.zshrc
echo 'export NO_UPDATE_NOTIFIER=1' >> ~/.bashrc

CLAUDEKIT_VERBOSE

Purpose: Enable verbose logging globally

Values: "1" or "true"

Usage:

CLAUDEKIT_VERBOSE=1 ck new

Effect: Same as --verbose flag on all commands

Caching

CK_CACHE_TTL

Purpose: Set cache time-to-live in seconds

Default: 3600 (1 hour)

Usage:

# Cache for 2 hours
CK_CACHE_TTL=7200 ck versions

# Disable caching (always fetch fresh)
CK_CACHE_TTL=0 ck versions

# Cache for 30 minutes (permanent)
export CK_CACHE_TTL=1800

What’s cached:

• GitHub release data
• Version check results

Cache locations:

• Releases: ~/.claudekit/cache/releases/
• Version checks: ~/.claudekit/cache/version-check.json

Command-Line Defaults

Set defaults to avoid repetitive flags.

Kit Default

Set default kit for ck new and ck init:

Via config file:

Edit ~/.claudekit/config.json:

{
  "defaults": {
    "kit": "engineer"
  }
}

Via command:

# First run with --kit flag
ck new --kit engineer

# Saves to config, future runs use it
ck new  # Uses engineer by default

Directory Default

Set default target directory:

Via config file:

{
  "defaults": {
    "dir": "~/projects"
  }
}

Effect:

ck new  # Creates project in ~/projects instead of current dir

Custom Folder Names

Use custom names for docs/ and plans/ directories.

Per-Project Configuration

Set during creation:

ck new --docs-dir documentation --plans-dir planning

Set during update:

ck init --docs-dir documentation --plans-dir planning

What happens:

1. Folder names changed in file system
2. All references updated in workflow files
3. Configuration saved to .claude/.ck.json
4. Future updates preserve custom names

Configuration File

Location: .claude/.ck.json

Structure:

{
  "folders": {
    "docs": "documentation",
    "plans": "planning"
  }
}

Read by: ck init during updates

Protected File Patterns

Files matching these patterns are never overwritten during updates.

Environment Files

• .env
• .env.local
• .env.*.local (e.g., .env.production.local)

Credential Files

• *.key (private keys)
• *.pem (certificates)
• *.p12, *.pfx (PKCS12 files)

User Configuration

• settings.json
• settings.local.json
• CLAUDE.md (global mode only)

Build Artifacts

• node_modules/**
• .git/**
• dist/**
• build/**

Custom Exclude Patterns

Add your own patterns:

ck new --exclude "*.log" --exclude "temp/**"
ck init --exclude "secrets/**"

Platform-Specific Paths

Configuration locations vary by platform.

macOS/Linux

Windows

Configuration Examples

Minimal Setup

Basic configuration for quick start:

{
  "defaults": {
    "kit": "engineer"
  }
}

Team Configuration

Shared settings for team projects:

{
  "defaults": {
    "kit": "engineer",
    "dir": "."
  }
}

Team workflow:

1. Team lead sets defaults
2. Team members use same config
3. Consistent project structure

CI/CD Configuration

Optimized for automation:

# .github/workflows/setup.yml
env:
  CI: true
  NO_UPDATE_NOTIFIER: 1
  CK_CACHE_TTL: 0

steps:
  - name: Install ClaudeKit
    run: ck init --yes --release v1.16.0 --skip-setup

Development vs Production

Development:

# Use beta versions
ck new --beta --install-skills

Production:

# Pin stable version
ck new --release v1.16.0

Debugging Configuration

View Current Config

# View global config
cat ~/.claudekit/config.json

# View project config
cat .claude/.ck.json

# View metadata
cat .claude/metadata.json

Validate Configuration

# Run health check
ck doctor

# Verbose mode for details
ck doctor --verbose

Reset Configuration

Reset CLI config:

rm ~/.claudekit/config.json
ck new  # Will recreate with prompts

Reset project config:

rm .claude/.ck.json
ck init  # Will use defaults

Best Practices

Version Pinning

For production projects:

# Pin to specific stable version
ck new --release v1.16.0

# Document in README
echo "ClaudeKit Version: 1.16.0" >> README.md

Team Synchronization

Keep team on same CLI version:

# In team docs
npm install -g claudekit-cli@3.10.1

# Or package.json (local install)
{
  "devDependencies": {
    "claudekit-cli": "3.10.1"
  }
}

Credentials Security

Never commit credentials:

# Add to .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo "*.key" >> .gitignore

# Use environment variables in CI
# Set GITHUB_TOKEN in CI secrets

Cache Management

Clear cache periodically:

# Clear release cache
rm -rf ~/.claudekit/cache/releases/

# Clear version check cache
rm -rf ~/.claudekit/cache/version-check.json

# Or set lower TTL
export CK_CACHE_TTL=1800  # 30 minutes

Troubleshooting Configuration

”Config file not found”

Normal behavior - Config is created on first run.

To pre-create:

mkdir -p ~/.claudekit
echo '{"defaults":{"kit":"engineer"}}' > ~/.claudekit/config.json

“Invalid JSON in config file”

Fix:

# Validate JSON
cat ~/.claudekit/config.json | jq .

# If invalid, recreate
rm ~/.claudekit/config.json
ck new  # Recreates with valid JSON

“Permission denied” on config file

Linux/macOS:

chmod 600 ~/.claudekit/config.json

Windows:

Run as administrator or check file permissions in Properties.

New in v3.36.0

StatuslineColors

Enable or disable ANSI color rendering in the Claude Code status line. Add to .claude/.ck.json (or ~/.claude/.ck.json for global):

{
  "statuslineColors": true
}

Hook Diagnostics Dashboard

ck config now includes a hook diagnostics panel showing:

• Execution logs for all registered hooks
• Timing data per hook run
• Error history and failure details

Use this to debug hook configuration issues or verify hooks are firing as expected.

Config Dashboard Access

By default, ck config binds the dashboard to 127.0.0.1, which keeps access local to the machine running the CLI.

Use --host when you intentionally want to reach the dashboard from another device on the same trusted network:

# Expose to your LAN/Tailscale
ck config --host 0.0.0.0 --no-open

# Bind to a specific interface or hostname
ck config --host 100.88.12.4 --no-open
ck config --host dashboard.local --no-open

The dashboard still enforces same-origin browser access. Remote access works when the browser opens the UI from the same host or origin that reaches the server.

Quality Gate Hooks

ClaudeKit automatically installs git pre-commit and pre-push hooks during ck init:

• pre-commit — Runs linter before every commit. Blocks commit if lint fails.
• pre-push — Runs test suite before every push. Blocks push if tests fail.

These hooks enforce code quality locally, preventing broken code from reaching CI. Hooks are idempotent — safe to re-run ck init without duplicating them.

To skip hooks in an emergency (not recommended):

git commit --no-verify
git push --no-verify

Next Steps

After configuring:

1. Test configuration:

ck doctor

2. Create a project:

ck new

3. Verify settings:

cat .claude/metadata.json

Related Commands

• ck doctor - Validate configuration
• ck new - Create project with config
• ck init - Update project preserving config
• Installation - Initial setup