agent-shift

Agent config versioning with environment promotion and rollback. The deploy step in the Preflight AI agent pipeline.

stepproof → agent-comply → agent-gate → agent-shift DEPLOY

Install

npm install -g agent-shift

What it does

Captures snapshots of your AI agent's configuration (prompts, model, tools, guardrails), tracks changes across environments (staging → production), enforces config integrity in CI, and gives you one-command rollback when deploys go wrong.

State lives in .agent-shift/ (like .terraform/). No server, no database, no LLM calls.

Commands

agent-shift init

Scaffold a .agent-shift.yaml config in the current directory.

agent-shift init

agent-shift snapshot --env <environment>

Capture the current config as a versioned snapshot with sha256 hash.

agent-shift snapshot --env staging
agent-shift snapshot --env production --tag v1.2.0

agent-shift diff <source> <target>

Compare configs between two environments or snapshots.

agent-shift diff staging production
agent-shift diff staging production --json

agent-shift promote <source> --to <target>

Move a validated config from one environment to another.

agent-shift promote staging --to production
agent-shift promote staging --to production --require-gate-pass ./gate-receipt.json
agent-shift promote staging --to production --dry-run

agent-shift rollback <environment>

Revert to a prior snapshot.

agent-shift rollback production           # go back 1 step
agent-shift rollback production --steps 3
agent-shift rollback production --to abc123
agent-shift rollback production --list    # show available snapshots

agent-shift check <source> <target>

CI/CD gate — exits 1 if config has drifted between environments.

agent-shift check staging production

Config schema (.agent-shift.yaml)

version: "1"
name: my-agent
environments:
  staging:
    model: claude-sonnet-4-6
    prompts:
      system: prompts/system.md
    tools:
      - name: web-search
        version: "1.0"
    guardrails:
      max_tokens: 4096
      allow_code_execution: false
  production:
    model: claude-opus-4-6
    prompts:
      system: prompts/system.md
    tools:
      - name: web-search
        version: "1.0"
    guardrails:
      max_tokens: 4096
      allow_code_execution: false

CI/CD integration

# GitHub Actions example
- name: Check agent config drift
  run: agent-shift check staging production

- name: Promote to production
  run: agent-shift promote staging --to production --require-gate-pass gate-receipt.json

Part of the Preflight suite

agent-shift is one tool in a suite of AI agent pre-deploy checks:

Tool	Purpose	Install
stepproof	Behavioral regression testing	npm install -g stepproof
agent-comply	EU AI Act compliance scanning	npm install -g agent-comply
agent-gate	Unified pre-deploy CI gate	npm install -g @bilkobibitkov/agent-gate
agent-shift	Config versioning + environment promotion	npm install -g agent-shift
agent-trace	Local observability — OTel traces in SQLite	npm install -g agent-trace

Install the full suite:

npm install -g @bilkobibitkov/agent-gate stepproof agent-comply agent-shift agent-trace

Structured reports (v0.2.0)

agent-shift outputs machine-readable SARIF 2.1.0 and JUnit XML for CI pipeline integration.

# Check config drift and output SARIF
agent-shift check staging production --format sarif
agent-shift check staging production --format sarif > drift-check.sarif

# Diff environments in JUnit XML
agent-shift diff staging production --format junit

Integrate with GitHub Advanced Security:

# .github/workflows/config-drift.yml
- name: Check agent config drift
  run: agent-shift check staging production --format sarif > drift-check.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: drift-check.sarif
  if: always()

Config drift (model changes, guardrail differences) appears as code scanning alerts in your GitHub Security tab. Default output (no --format flag) is unchanged — human-readable terminal output.

Contributing / build from source

npm install -g agent-shift

Or build from source:

npm install
npm run build   # compiles TypeScript to dist/
npm test        # 15 tests via vitest

The dist/ directory is built at publish time via prepublishOnly — clone users must run npm run build before using the CLI locally.

License

MIT