> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chkk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code + Chkk

> A walkthrough of using Claude Code with Chkk Upgrade Agent to produce environment-aware IaC pull requests

<Info>
  Agent Responses on this page are illustrative. Exact phrasing from your AI
  model may vary depending on the model, settings, and repository context.
</Info>

<Note>
  For the best experience, it is recommended to use the **claude-4-sonnet** model with the Chkk-Upgrade-Context-MCP Server.
</Note>

This guide shows how to use **Claude Code** with the **Chkk-Upgrade-Context-MCP** to generate precise, environment-aware diffs and apply them to your Cloud Native Project IaC (e.g., Helm).

For a deep conceptual overview of how the Upgrade Agent works (powered by the Upgrade Context MCP server), see **[Upgrade Agent](/ai/upgrade-agent)** first.

## Prerequisites

1. [Install Docker](https://docs.docker.com/get-docker/): Required to run the Chkk-Upgrade-Context-MCP Server.

2. [Install Claude Code](/resources/installation-guides/claude-code): Required to begin generating environment-aware pull requests.

3. A [Claude.ai](https://claude.ai/) (recommended) or [Anthropic Console](https://console.anthropic.com/) account

## Initialization of Chkk Upgrade Agent

<Steps>
  <Step title="Clone the Sample Chkk IaC repo">
    Run the following command to clone the sample Chkk IaC repo:

    ```bash theme={"dark"}
    git clone git@github.com:chkk-io/upgrade-playground.git && \
    cd upgrade-playground
    ```
  </Step>

  <Step title="Retrieve your Chkk Access Token">
    1. In the **Chkk Dashboard**, expand **Configure** on the left menu and click **Settings**.
    2. Select the **Tokens** tab. Here you'll see a list of all your active tokens (if any), along with options to create new ones or revoke existing ones.
    3. Click on the **clipboard** icon next to a token to copy it.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/chkk-access-token.gif?s=f0f979e1e97c8531d96868a9db175c25" alt="Tokens Tab" width="1920" height="1080" data-path="images/features/chkk-access-token.gif" />
  </Step>

  <Step title="Install in Claude Code">
    Install the `Chkk-Upgrade-Context-MCP` using the Claude Code CLI:

    ```bash theme={"dark"}
    claude mcp add Chkk-Upgrade-Context-MCP --env CHKK_ACCESS_TOKEN="<CHKK_TOKEN>"  -- docker run -i --rm -e CHKK_ACCESS_TOKEN public.ecr.aws/chkk/chkk-mcp-upgrade-context:latest
    ```

    Replace `<CHKK_TOKEN>` with your Chkk Access Token.
  </Step>

  <Step title="Verify Chkk-Upgrade-Context-MCP Server is installed">
    Verify via CLI that the server is registered:

    ```bash theme={"dark"}
    claude mcp get Chkk-Upgrade-Context-MCP
    ```

    The command should return server details indicating it is installed and enabled.

    <img src="https://mintcdn.com/chkk/jVz5fXAMivd3Hr6E/images/ai/claude-code-mcp-setup.png?fit=max&auto=format&n=jVz5fXAMivd3Hr6E&q=85&s=8c9d625d12d42a5fdc2db59701a14677" alt="Claude Code Chkk MCP Server" width="3010" height="414" data-path="images/ai/claude-code-mcp-setup.png" />
  </Step>

  <Steps title="Retrieve the Upgrade ID">
    1. In the **left-hand column** of the **Chkk Dashboard**, expand **Upgrade Copilot**.

    2. Under **Upgrade Plans** select **Add-on & App Services**.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/navigation/nav-project-upgrade-plans.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=5f7a62b414f23a14f92997ef9c855916" alt="Navigate to Project Upgrade Plans" width="3516" height="2166" data-path="images/navigation/nav-project-upgrade-plans.png" />

    3. On the **Middle Right** corner of the page, enable the **Show Example Data** toggle, as shown in the image below.

    4. This will switch the view to only show example data and displays a confirmation banner.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/enable-show-example-data-toggle.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=014dc909a160122f2b2c08ea0bdc140e" alt="Enable Example Data" width="3510" height="2160" data-path="images/features/enable-show-example-data-toggle.png" />

    5. In the table below, you will see a list of Projects **Example Upgrade Plans**.

    6. Select any Upgrade Plan from the table that has the **AI Context Generated** badge, as shown in the image below.

    <Info>
      The **AI Context Generated** badge indicates that these Upgrade Plans are supported by the **Chkk-Upgrade-Context-MCP Server**.
    </Info>

    <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/highlight-example-project-plan-with-ai-context-generated.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=70657d45165b34cf2d4146ab9eebdf7c" alt="Example Project Upgrade Plan with AI Context Generated Badge" width="3516" height="2110" data-path="images/features/highlight-example-project-plan-with-ai-context-generated.png" />

    7. At the top of the page, under the name of the Upgrade Plan, you will see the **Upgrade ID**.
    8. Click the **clipboard** icon to copy the Upgrade ID to your clipboard.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/step-copy-project-upgrade-plan-id.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=785f980f08904d1dd8cce4e4b6eb4bde" alt="Upgrade ID" width="3516" height="2160" data-path="images/features/step-copy-project-upgrade-plan-id.png" />
  </Steps>

  <Step title="Open a new chat in Claude Code">
    * Open Claude Code and start a new chat from your IaC repo root.
  </Step>

  <Step title="Load the Chkk Upgrade Agent">
    Open a chat in Claude Code and send:

    <CodeBlock wrap language="text">
      You're in a K8s repo. Fetch "addon-upgrade-agent" from Chkk MCP and upgrade the package listed in the upgrade plan. Start by asking for the upgrade ID.
    </CodeBlock>

    <Info>
      Your opening prompt is flexible, but it **must** explicitly instruct the assistant to **fetch "addon-upgrade-agent" from Chkk MCP**.
    </Info>

    **Agent Response:**

    <img src="https://mintcdn.com/chkk/jVz5fXAMivd3Hr6E/images/ai/claude-code-init-prompt.png?fit=max&auto=format&n=jVz5fXAMivd3Hr6E&q=85&s=dbd03222df1be9e4ec36ab8917f8c04a" alt="Claude Code Chkk MCP Server start" width="3024" height="394" data-path="images/ai/claude-code-init-prompt.png" />
  </Step>

  <Step title="Provide the upgrade ID of the Example Upgrade Plan">
    Paste your **upgrade ID** (from your instantiated [Project Upgrade Plan](/resources/glossary#project-upgrade-plan)), for example:

    <CodeBlock copy={false}>
      upgr\_ea53db65-3d8d-4744-b8b7-92e3c7552932
    </CodeBlock>

    **Agent Response:**

    <img src="https://mintcdn.com/chkk/jVz5fXAMivd3Hr6E/images/ai/claude-code-upgrade-id.png?fit=max&auto=format&n=jVz5fXAMivd3Hr6E&q=85&s=65aa6381b36b760d934c2c5a53c93a12" alt="Claude Code Chkk MCP Server upgrade" width="2936" height="826" data-path="images/ai/claude-code-upgrade-id.png" />
  </Step>
</Steps>

## Upgrade Agent Workflow

Connect your environment to Chkk and generate an Upgrade Plan. From the Claude Code IDE, ask the
Chkk Upgrade MCP to fetch Upgrade Context from that plan for the Cloud Native Project you're about to
change—say cert-manager or External Secrets Operator. The assistant retrieves the recommended target
version and rationale, detects your IaC pattern, identifies which files need to be updated,
creates an environment-specific diff, and attaches the notes reviewers want (deprecations, critical fixes, notable features).
Your IDE applies the diff and opens the PR, with optional preflight and postflight checks to keep code and running state aligned.

The entire flow happens in your Claude Code editor chat, end-to-end. Below is exactly what you'll see, phase by phase,
using a live example that upgrades **cert-manager** from **v1.14.4 → v1.17.2** with a forked Helm chart.

<Steps>
  <Step title="Kickoff & ID Handshake">
    **What you do:** You connect Chkk-Upgrade-Context-MCP server to Claude Code. In chat, you invoke the PR creation workflow (e.g., *"Use the Chkk upgrade agent to apply the IaC changes. Start by asking for the upgrade ID."*).

    **What you see:** The assistant asks you for the **upgrade\_id**—a single natural key that ties your request to a Chkk **Upgrade Plan** (precomputed for your environment).

    **Why it matters:** The **upgrade\_id** is how the assistant fetches the precise context—including resources, subagents and diffs—for *your* cluster constraints, not "generic upstream."
  </Step>

  <Step title="Environment Snapshot & State Setup">
    **What you do**: Provide the upgrade\_id.

    **What you see**: The assistant resolves plan metadata immediately (package name and from/to versions) and prepares a safe workspace:

    * Confirms the **package** (e.g., `cert-manager`) and version span (`1.14.4 → 1.17.2`).
    * Creates a project-local scratchpad (e.g., `.chkk/scratchpad/`) which enables workflow tracing and checkpointing.

    **Why it matters**: This isolates automation artifacts from your source tree while keeping a local, inspectable record of every change.
  </Step>

  <Step title="Context Retrieval (MCP Tool Call)">
    **What you do**: Nothing; the assistant drives.

    **What you see**: A short progress line—"Now fetching the context". The Context contains:

    * The **authoritative Upgrade Plan** for `cert-manager`.
    * Exact **file artifacts** to add and **unified diff** files to apply.
  </Step>

  <Step title="Plan Load & Sanity Summary">
    **What you do**: Nothing; the assistant reads the plan.

    **What you see**: Compact, human-readable instructions from the plan:

    * **Upgrade Details**: `cert-manager v1.14.4 → v1.17.2`
    * **Reasons**: e.g., "1.14.4 is EOL/Unsupported" and "1.14.4 incompatible with Kubernetes 1.32."
    * **Inventory**: **Added: 2 files, Modified: 23 files, Deleted: 0** (your counts will vary by package).

    **Why it matters**: This is the first concrete signal that the plan is **environment-aware**
    (incompatible K8s version, distro nuances, etc.) and scoped to what you actually run.
  </Step>

  <Step title="Target Locator (Chart Finder)">
    **What you do:** Nothing, unless you have multiple candidates.

    **What you see:** The assistant identifies your IaC repo pattern and locates the exact **Helm chart root**
    for the package/version you're on (e.g., `.../helm/cert-manager/`) by scanning for **Chart.yaml** where
    `name == cert-manager` and `version == 1.14.4` (exact, case-sensitive).

    **Edge cases you might see:**

    * **Multiple matches:** You'll get a list of absolute paths and a prompt to choose one—no guessing.
    * **No match:** The assistant asks for an explicit absolute path (it won't "best-effort" a wrong chart).
  </Step>

  <Step title="Preflight Checks">
    **What you do:** Review pass/fail lines.

    **What you see:** Two precise checks with ✅❌ outcomes:

    * **Chart Name & Version Match** — confirms **Chart.yaml** matches the *current* package & version.
    * **Upgrade Plan Metadata Match** — confirms the plan's **from/to** are consistent with resolved metadata.

    **Why it matters:** Preflight checks safeguard against pointing the patcher at the wrong subtree
    or the wrong plan. Any failure **stops the run** until fixed.
  </Step>

  <Step title="Reviewer Context, Upfront">
    **What you do:** Skim.

    **What you see:** The assistant surfaces the "**why**"—the exact notes reviewers care about:

    * **Critical drivers** (e.g., EOL, K8s version compatibility).
    * **Breaking changes** (e.g., structured logging, stricter Helm schema validation, API removals).
    * **Security & bug fixes** (e.g., DoS mitigations, renewal logic).
    * **Notable features** (e.g., Gateway API support, metrics exposure).

    **Why it matters:** Your future PR will **inherit** these callouts so reviewers don't need to hunt docs to understand risk, scope and impact.
  </Step>

  <Step title="Deterministic Apply Pass">
    **What you do:** Watch the live counter; no prompts needed.

    **What you see:** A strict, linear, and **complete** application of the plan:

    * **Full inventory printout:**
      *"Processing 25 total files: 2 added, 23 modified, 0 deleted"*

    * **Adds:** Each source file from the context is copied to the correct relative target (e.g.,\
      `templates/cainjector-service.yaml`, `templates/extras-objects.yaml`) with immediate ✅ **Added** confirmations.

    * **Mods:** Every single `*.diff` is applied **one-by-one** with a visible sequence:\
      *"Processing diff 1 of 23: Chart.yaml … ✅ Modified"*\
      *"Processing diff 2 of 23: README.md … ✅ Modified"*\
      …through to the last template/value file.

    * **Deletions:** If any exist, they're backed up to `.bak`, then removed with ✅ **Deleted** confirmations.
  </Step>

  <Step title="CRD Copy">
    **What you do:** Nothing.

    **What you see:** If the context includes CRDs, the assistant copies them into the target CRD directory and prints the exact path used.

    **Why it matters:** Reviewers see CRD changes alongside template and values edits.
  </Step>

  <Step title="Update Custom Resources">
    **What you do:** Nothing.

    **What you see:** If the plan includes Custom Resources, they're edited based on the changes in the CRD schema.

    **Why it matters:** Custom Resources are validated against their CRDs; migrating specs to the new schema
    (handling renamed/deprecated fields and default changes) prevents admission failures,
    reconcile churn, and subtle behavior drift during rollout.
  </Step>

  <Step title="Postflight Checks">
    **What you do:** Review.

    **What you see:** Two final gates:

    * **Chart version updated** — `Chart.yaml version == to_version` (e.g., `v1.17.2`) → ✅❌
    * **All planned changes applied** — match exactly and all items carry ✅ → ✅❌

    **Any failure here stops the flow** and lists the exact mismatches.
  </Step>

  <Step title="Human-Readable Summary (PR-Ready)">
    **What you do:** Read once; this becomes your PR body.

    **What you see:** A concise, celebratory completion message (never "upgraded," always "IaC updated"), plus reviewer-focused details:

    * **Completion:** 🎉 `cert-manager` IaC Successfully Updated — `v1.14.4 → v1.17.2.`
    * **Reasons** (EOL, K8s compatibility) and **most-critical notes** (breaking changes, security fixes).
    * **Applied changes** (counts + important files).
    * **CRD location** (exact path).
    * **Next step:** *"Create a Pull Request to review and apply these IaC changes."*
  </Step>
</Steps>

## Review and commit

<Steps>
  <Step title="Review workspace changes">
    * Use your editor's Source Control panel to inspect the diff.
    * Verify `Chart.yaml`, `values.yaml`, and any template updates.
  </Step>

  <Step title="Commit and open a pull request">
    Use your normal Git flow (Git UI or terminal) to commit on a branch and open a PR for review.\
    Chkk's MCP server is read-only; your IDE/assistant holds the pen and performs edits locally.
  </Step>
</Steps>