heretic-cli

Configuration

Understanding the three-layer configuration model — global profiles, local overrides, and CLI flags with variable interpolation

Three-Layer Config Model

Configuration is resolved by merging three layers (later wins):

  1. Global profile — ~/.heretic/agents/<name>.yaml
  2. Local override — .heretic/cli/<profile>.yaml (per-project, per-profile)
  3. CLI flags — Command-line options like --mcp

Variable Interpolation

String values support ${VAR} placeholders resolved after merge:

VariableValue
${CWD}Project directory (where you run the command)
${HOME}User home directory
${ANY_ENV_VAR}Value from the host environment

Escape with double dollar: $${LITERAL} becomes ${LITERAL}.

Directory Structure

~/.heretic/
  settings.yaml              # Global CLI settings (GitHub tokens, etc.)
  agents/
    claude.yaml              # Global agent profile
    kilocode.yaml            # Kilocode agent profile
    custom-agent.yaml        # Another profile
  get-anthropic-key.sh       # Secret script - Unix
  get-anthropic-key.cmd      # Secret script - Windows
  get-kilocode-key.sh        # Kilocode API key script
  get-github-token-key.sh    # Secret script
  claude-settings.json       # Global Claude Code settings
  kilocode-opencode.json     # Global OpenCode settings (Kilocode)
  kilocode-kilocode-mcp.json # Global Kilocode MCP settings

your-project/
  .heretic/
    cli/
      claude.yaml            # Local overrides for "claude" profile
      kilocode.yaml          # Local overrides for "kilocode" profile
      copilot.yaml           # Local overrides for "copilot" profile
      compose.yaml           # Custom compose file (for "custom" runner)
      claude-settings.json   # Local Claude settings (auto-merged)
      opencode-settings.json # Local OpenCode settings (Kilocode, auto-merged)
      kilocode-mcp.json      # Local Kilocode MCP settings (auto-merged)
    temp/                    # Runtime temp files (per-session subdirs)
      default/               # Default session
        .mcp.json            # Generated MCP config
        .claude.json         # Onboarding seed
        settings.json        # Merged Claude settings
        compose.yaml         # Generated compose file
        kilo-config/         # Kilocode config (mounted to ~/.config/kilo/)
          opencode.json      # Merged OpenCode settings
          mcp_settings.json  # Merged Kilocode MCP settings
        kilo-data/           # Kilocode data (mounted to ~/.local/share/kilo/)
          auth.json          # Kilocode auth credentials

Detailed Topics