heretic-cli

Quick Start: Fast Lane

Get your first AI agent running in minutes — step-by-step examples for Claude, Copilot, and KiloCode with MCP support

Pick your agent and follow the steps. Each example gets you from zero to a running agent with MCP tools in under 5 minutes.

Prerequisites

Docker must be running. Install heretic-cli first — see Installation.

Example 1: Claude Agent

Set up an Anthropic Claude agent with filesystem and GitHub MCP servers.

Step 1: Initialize

heretic-cli init

Select Anthropic when prompted. Enter your API key and choose a Docker image (default: giglabo/claude-heretic:latest).

Step 2: Add MCP Servers

heretic-cli agents mcp claude --file ~/.vscode/mcp.json

Or define them inline in the profile (~/.heretic/agents/claude.yaml):

image: giglabo/claude-heretic:latest
runner: docker
provider: anthropic

mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GH_TOKEN}"

Step 3: Run

cd /path/to/your/project
heretic-cli local-init claude
heretic-cli claude

The CLI generates /workspace/.mcp.json inside the container automatically.

Example 2: Copilot Agent

Set up a GitHub Copilot CLI agent with MCP from your VS Code config.

Step 1: Initialize

heretic-cli init

Select Copilot when prompted. Enter your Copilot token.

Step 2: Add MCP Servers

Point to your existing VS Code MCP config:

# ~/.heretic/agents/copilot.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: copilot
agent_type: copilot-cli

mcp_file: ${CWD}/.vscode/mcp.json
mcp_override: true

Or paste MCP JSON directly:

heretic-cli agents mcp copilot --file .vscode/mcp.json

The CLI auto-converts to Copilot format — adds type: "stdio" and tools: ["*"] to every entry.

Step 3: Run

cd /path/to/your/project
heretic-cli local-init copilot
heretic-cli copilot

MCP config is mounted to ~/.copilot/mcp-config.json inside the container.

Example 3: KiloCode Agent

Set up a KiloCode (OpenCode) agent with project-level and global MCP servers.

Step 1: Initialize

heretic-cli init

Select Kilocode when prompted. Enter your KiloCode API key. The wizard creates three files:

  • ~/.heretic/agents/kilocode.yaml — agent profile
  • ~/.heretic/kilocode-opencode.json — OpenCode settings
  • ~/.heretic/kilocode-kilocode-mcp.json — global MCP settings

Step 2: Add MCP Servers

Project-level MCP — define in the profile:

# ~/.heretic/agents/kilocode.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: kilocode
agent_type: kilocode-cli
opencode_settings: ~/.heretic/kilocode-opencode.json
kilocode_mcp_settings: ~/.heretic/kilocode-kilocode-mcp.json

mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    alwaysAllow: ["read_file", "list_directory"]

secrets:
  KILOCODE_API_KEY: ~/.heretic/get-kilocode-key.sh
env:
  KILOCODE_API_KEY: "${KILOCODE_API_KEY}"

Global MCP — add servers available in every project (~/.heretic/kilocode-kilocode-mcp.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Step 3: Run

cd /path/to/your/project
heretic-cli local-init kilocode
heretic-cli kilocode

Two MCP configs are mounted:

  • /workspace/.kilocode/mcp.json — project-level servers
  • ~/.config/kilo/mcp_settings.json — global servers

Common Operations

After your agent is running:

heretic-cli ps                    # List running agents
heretic-cli stop claude           # Stop an agent
heretic-cli attach claude         # Re-attach to a detached agent
heretic-cli claude -s feature-x   # Run in a named session

Next Steps