heretic-cli local-init

Usage

heretic-cli local-init claude          # Create .heretic/cli/claude.yaml
heretic-cli local-init copilot         # Create .heretic/cli/copilot.yaml
heretic-cli local-init --compose       # Create .heretic/cli/compose.yaml for custom runner
heretic-cli local-init claude --force  # Overwrite existing files

What It Creates

• .heretic/cli/<profile>.yaml — Per-profile local overrides
• .heretic/cli/temp/ — Runtime temp directory for generated files (e.g., .mcp.json)
• .heretic/cli/claude-settings.json — Local Claude settings (auto-merged with global) — for Claude/Aider/Third-party agents
• .heretic/cli/opencode-settings.json — Local OpenCode settings (auto-merged with global) — for Kilocode agents only

You can call local-init multiple times with different profiles to create overrides for each.

Claude Settings Merge

Local settings (.heretic/cli/claude-settings.json) are automatically detected and merged with global settings at runtime:

Example: Third-Party Provider Overrides

{
  "permissions": {
    "allow": ["mcp__project-specific"]
  },
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "different-model"
  }
}

Example: Anthropic Permissions

{
  "permissions": {
    "allow": ["mcp__custom-server"],
    "deny": ["Bash(rm -rf *)"]
  }
}

The template generated by local-init is profile-aware (Anthropic, Third-Party, Copilot, or Kilocode).

OpenCode Settings Merge (Kilocode)

For Kilocode agents, local settings (.heretic/cli/opencode-settings.json) are merged with global settings at runtime using the same merge strategy as Claude settings:

Default OpenCode settings enable auto-approve mode:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": "allow"
}

Kilocode MCP Settings Merge

Kilocode agents also support a separate global MCP settings file (~/.heretic/<name>-kilocode-mcp.json) with local override at .heretic/cli/kilocode-mcp.json. These are mounted to ~/.config/kilo/mcp_settings.json inside the container — separate from the project-level MCP config.