heretic-cli

Local Overrides

Per-project configuration with profile-specific YAML files, settings merge, and MCP file integration

Example

# .heretic/cli/claude.yaml — local override for "claude" profile

# Project-specific secrets (merged with profile secrets)
secrets:
  PROJECT_API_KEY: "~/.heretic/get-project-key.sh"

env:
  PROJECT_NAME: my-app
  DEBUG: "app:*"

# Load MCP servers from project's VS Code config
mcp_file: ${CWD}/.vscode/mcp.json

# Inline MCP servers (merged with mcp_file servers by name)
mcp:
  - name: project-docs
    command: npx
    args: ["-y", "@mcp/server-filesystem", "/workspace/docs"]

mcp_override: true  # Force profile MCP servers even if .mcp.json exists

git:
  author_name: "Project Bot"

dind: true

Key Behaviors

  • The extends field is optional — the filename determines which global profile to extend
  • Legacy .heretic/cli/agent.yaml with an extends field is still supported as a fallback
  • Per-profile files take precedence over the legacy format
  • You can have multiple override files for different profiles in the same project

MCP File Handling

  • If your project already has a .mcp.json and you want to use it as-is, omit the mcp section or set mcp_override: false (default)
  • When mcp_file is set alongside inline mcp, servers are merged by name: inline entries override file entries with the same name