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

# Sync Claude Code Changes with KDX

> Validate, dry-run, push, and deploy Claude Code-authored Kodexa metadata to dev, staging, and production environments using the KDX CLI sync workflow.

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:

```bash theme={null}
git pull
kdx sync pull --target my-org --env dev
```

Then inspect the diff:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```text theme={null}
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:

```bash theme={null}
kdx sync push --target my-org --env dev
```

Commit the deployed change and sync state:

```bash theme={null}
git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Add invoice intake Activity configuration"
```

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

## Use Deploy For GitOps Promotion

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

```bash theme={null}
kdx sync deploy --branch main --dry-run
kdx sync deploy --branch main
```

For release-driven promotion:

```bash theme={null}
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](https://github.com/kodexa-ai/kdx-sync-action). See [CI/CD Integration](/guides/kdx-cli/sync/ci-cd).

## Handling Conflicts

If KDX reports stale server state:

```bash theme={null}
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:

```text theme={null}
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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Sync Overview" icon="code-branch" href="/guides/kdx-cli/sync/overview">
    Understand the sync repository model.
  </Card>

  <Card title="Pull, Push & Deploy" icon="arrows-rotate" href="/guides/kdx-cli/sync/pull-push">
    Learn command flags and operational behavior.
  </Card>

  <Card title="Conflict Detection" icon="code-compare" href="/guides/kdx-cli/sync/conflict-detection">
    See how `.sync-state/` protects against stale writes.
  </Card>

  <Card title="Resource Validation" icon="shield-check" href="/guides/kdx-cli/validate">
    Validate YAML against the platform schema before deployment.
  </Card>
</CardGroup>