Sync Claude Code Changes with KDX

Claude Code edits files. KDX sync moves those files between Git and Kodexa. This page shows the operational loop for taking Claude Code-authored metadata through validation, review, and deployment.

Pull Before You Edit

Start every session by pulling the latest platform state and Git state:

git pull
kdx sync pull --target my-org --env dev

Then inspect the diff:

git status --short
git diff

If kdx sync pull changed files, commit or intentionally review those changes before asking Claude Code to make new edits. A clean baseline makes conflicts easier to reason about.

Validate Local Files

Validate changed resource files before sync:

kdx validate -f kodexa-resources/activity-plans/invoice-intake.yaml
kdx validate -f kodexa-resources/data-definitions/invoice.yaml
kdx validate -f kodexa-resources/data-forms/invoice-review.yaml

For a broad pass:

find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f

kdx validate checks YAML against the platform OpenAPI schema without sending the resource to the server.

Dry-Run The Sync

Always preview before pushing:

kdx sync push --target my-org --env dev --dry-run

Review:

created resources
updated resources
deleted resources
dependency ordering
unresolved references
target organization and environment

If the dry run is not clean, ask Claude Code to inspect the output and the relevant files:

Review this kdx sync dry-run output. Identify which local files caused the errors,
which references are unresolved, and what edits are required before deployment.

Push To A Development Environment

Once the dry run is correct:

kdx sync push --target my-org --env dev

Commit the deployed change and sync state:

git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Add invoice intake Activity configuration"

Commit .sync-state/ after pull and push operations. It records server change sequences used for conflict detection.

Use Deploy For GitOps Promotion

Use sync deploy when your repository has branch or tag mappings in sync-config.yaml:

kdx sync deploy --branch main --dry-run
kdx sync deploy --branch main

For release-driven promotion:

kdx sync deploy --tag v2026.05.03 --dry-run
kdx sync deploy --tag v2026.05.03

For GitHub Actions, prefer the official kdx-sync-action. See CI/CD Integration.

Handling Conflicts

If KDX reports stale server state:

kdx sync pull --target my-org --env dev
git diff

Then decide whether to keep the server change, keep your local change, or merge both. Do not use --force until you understand which server-side change would be overwritten. Ask Claude Code to help with the merge, not to blindly force it:

kdx sync push detected a conflict. Review the pulled server changes and my local
changes. Propose a merged version that preserves the intended Activity behavior
and avoids overwriting unrelated platform edits.

A Safe Claude Code + KDX Loop

# 1. Refresh local state
git pull
kdx sync pull --target my-org --env dev

# 2. Let Claude Code edit files
claude

# 3. Review and validate
git diff
find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
kdx sync push --target my-org --env dev --dry-run

# 4. Push only after the dry run is expected
kdx sync push --target my-org --env dev

# 5. Commit the files and sync state
git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Update Kodexa metadata"

Next Steps

Sync Overview

Understand the sync repository model.

Pull, Push & Deploy

Learn command flags and operational behavior.

Conflict Detection

See how .sync-state/ protects against stale writes.

Resource Validation

Validate YAML against the platform schema before deployment.

Author Metadata with Claude Code Working with the Kodexa Agent

⌘I

Introduction

Activity Plans

Triggers

Task Templates

Task Groups

MCP Connector

Data Definitions

Excel Processing

Scripting

Intakes

Formulas

Project Templates

Data Forms

Working with Claude Code

Working with Kodexa Agent

Reference

Pull Before You Edit

Validate Local Files

Dry-Run The Sync

Push To A Development Environment

Use Deploy For GitOps Promotion

Handling Conflicts

A Safe Claude Code + KDX Loop

Next Steps

Sync Overview

Pull, Push & Deploy

Conflict Detection

Resource Validation

​Pull Before You Edit

​Validate Local Files

​Dry-Run The Sync

​Push To A Development Environment

​Use Deploy For GitOps Promotion

​Handling Conflicts

​A Safe Claude Code + KDX Loop

​Next Steps

Sync Overview

Pull, Push & Deploy

Conflict Detection

Resource Validation

Pull Before You Edit

Validate Local Files

Dry-Run The Sync

Push To A Development Environment

Use Deploy For GitOps Promotion

Handling Conflicts

A Safe Claude Code + KDX Loop

Next Steps