steersync

Sync the whole Kiro .kiro/ configuration, steering, specs, skills, agents, hooks and settings, between developer machines and a central git repository. A plain Python CLI runs from a git pre-push hook and shells out to the git binary, so your existing SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks are optional layers on top of the same core.

Kiro CLI has no built in command to import or sync its configuration from a remote repository; its guidance is to copy files from a central repository into ~/.kiro/ and .kiro/. steersync automates that in both directions for every collection it is configured with:

Collections

A collection is one kind of Kiro content. The packaged defaults cover the full .kiro/ layout; each one is configurable and new ones are added with a single YAML block.

Execute bits on skill scripts survive the round trip, hidden files are never synced, and files a collection's patterns do not select are never touched on either side. Limit any command to some collections with --collection NAME (repeatable), list them with steersync config collections, and see docs/central-layout.md for a worked example of a full .kiro/ tree in the central repository.

Install

Requires Python 3.14 or newer and git 2.18 or newer. Every GitHub release carries the wheel, the sdist and a SHA256SUMS file, with signed build provenance.

VERSION=0.2.0
uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
# with the MCP server
uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
# verify where the wheel came from
gh attestation verify "steersync-${VERSION}-py3-none-any.whl" --repo SCGIS-Wales/steersync

Every release is also published to PyPI through trusted publishing, so uv tool install steersync (or steersync[mcp]) installs the same files that the GitHub release carries.

Quick start

1. Point steersync at the central repository, once per machine:

   mkdir -p ~/.config/steersync
   cat > ~/.config/steersync/config.yaml <<'YAML'
   remote:
     url: git@gitlab.example.com:platform/kiro-steering.git
     allowed_hosts: [gitlab.example.com]
   YAML
   steersync config validate
   

2. Prepare a project. This adds every synced directory (.kiro/steering/, .kiro/specs/, .kiro/skills/, ...) and the lock file to .git/info/exclude (so centrally managed content is never committed to the project by accident; set git_exclude: false on a collection to keep committing it) and installs a chaining pre-push hook:

   cd ~/code/my-service
   steersync init --hook
   steersync pull
   

3. Edit anything under .kiro/. On your next git push, or on demand with steersync push, every collection is proposed to the central repository as one merge request.

Run steersync doctor at any time to see what steersync has resolved.

Central repository layout

kiro-config/
├── global/                        # applied to every machine (~/.kiro)
│   ├── steering/engineering-rules.md
│   ├── skills/release-checklist/SKILL.md
│   └── hooks/steersync.json
└── projects/
    └── acme/platform/api/         # derived from the project's origin URL
        ├── steering/product.md
        ├── specs/tls-cert-staged-rotation/tasks.md
        ├── skills/venafi-tpp-websdk/SKILL.md
        ├── agents/entra-app-registration.json
        ├── hooks/tests-on-stop.json
        └── settings/lsp.json

The project slug is the remote path with the host and .git removed and unsafe characters replaced, so ssh://git@gitlab.example.com/acme/platform/api.git becomes acme/platform/api. The global and projects directory names and every collection directory are configurable. Repositories created with steersync 0.1, which kept steering directly under global/ and projects/<slug>/, need their files moved into a steering/ subdirectory; pull and status print a warning pointing at them until that is done.

Commands

Global options: --config PATH, --log-level, --log-format text|json, --quiet.

Configuration

Configuration is layered: packaged defaults, then one YAML file, then environment variables. The file is found in this order: --config, $STEERSYNC_CONFIG, <repo>/.kiro/steersync.yaml, $XDG_CONFIG_HOME/steersync/config.yaml (default ~/.config/steersync/config.yaml). See steersync.example.yaml for every key and steersync config default for the packaged defaults.

Unknown keys, invalid patterns, unsafe paths and malformed push options are rejected at load time with a precise message. The pre 0.2 keys paths.workspace_steering and paths.global_steering still load, with a deprecation warning, as the steering collection's workspace_path and global_path.

Adding or changing a collection

Collections are merged over the packaged defaults, so a project only lists what differs:

collections:
  specs:
    enabled: false                # do not sync plans for this project
  settings:
    include: [lsp.json]           # keep mcp.json local
  runbooks:                       # a new collection, central directory runbooks/
    description: Operational runbooks
    workspace_path: docs/runbooks
    include: ["**/*.md"]
    lint: markdown
    git_exclude: false            # the project keeps committing these too
  agents-md:                      # a single file at the repository root
    workspace_path: .
    include: [AGENTS.md]
    max_depth: 1
    lint: markdown
    git_exclude: false

Every key is documented in steersync config default. A collection needs a workspace_path or a global_path; central_dir defaults to the collection name; enabled collections may not share a directory on either side.

Reliability

How pull decides what to write

steersync records the hash of every file it wrote, per collection, in a lock file (.kiro/steersync.lock.json in the workspace, ~/.kiro/steersync.lock.json globally). Version 1 lock files written by steersync 0.1 are read as the steering collection. On the next pull:

Kiro metadata is never written into steering front matter; all tool state lives in the lock file, so documents stay exactly as authored. Pulling a subset of collections leaves the lock entries of the others untouched.

Git hook

steersync install-hook writes .git/hooks/pre-push. An existing hook is preserved as pre-push.local and run first with the same arguments and stdin. core.hooksPath is never changed. The hook calls steersync push --from-hook --remote-url "$2", exits 0 on any sync failure unless hook.strict or STEERSYNC_STRICT=1 is set, and skips pushes that only delete branches.

Teams that already use pre-commit can use the published hook instead:

# .pre-commit-config.yaml in the project
default_install_hook_types: [pre-commit, pre-push]
repos:
  - repo: https://github.com/SCGIS-Wales/steersync
    rev: v0.2.0
    hooks:
      - id: steersync-push
      - id: steersync-lint

The lint hook receives the changed files under .kiro/ and lints each with the profile of the collection it belongs to.

GitLab merge requests

The default push options create a merge request against the default branch, remove the source branch on merge and set a title. Branch names follow steering/{project}/{user}-{hash}, where the hash covers every file, so two people proposing identical content share one branch and a second identical push is reported as already-proposed. Servers that do not advertise push options (GitHub, plain bare repositories) make git fail, so steersync retries once without them and says so. Push options may use {default_branch}, {project}, {user} and {hash}.

Lint rules

Each collection runs one lint profile. The steering profile applies every rule below. markdown (specs, prompts, references) applies the encoding, size, secret and markdown rules without Kiro front matter checks. skill adds skill-front-matter-required, skill-requires-metadata and skill-name-mismatch for SKILL.md. json adds json-syntax, hooks adds hook-schema, hook-trigger and hook-action, agent adds agent-schema, agent-name and agent-deprecated-key, and generic only enforces the size limit and secret scanning, allowing binary assets. New profiles are one function in steersync.lint.PROFILES.

Kiro integration

Session hook (V3). steersync kiro-hook --write creates .kiro/hooks/steersync.json with a SessionStart trigger that runs steersync pull --quiet --best-effort. For CLI 2.x agents paste the output of steersync kiro-hook --engine v2 into the agent's hooks block. Field reports say Kiro hooks fire only in headless runs or with a custom agent active, so treat them as a convenience and keep the git hook as the dependable trigger.

MCP server. Add the fragment from steersync mcp-config to .kiro/settings/mcp.json. The server exposes pull_steering, push_steering, diff_steering and lint_steering. Kiro does not pass the shell's PATH, SSH_AUTH_SOCK or proxy variables to MCP servers, so the rendered fragment forwards them explicitly through env; use an absolute --command if uvx is not on Kiro's path.

Custom agents. On Kiro CLI V3 custom agents inherit steering, skills and AGENTS.md by default, so list only the always on steering files in resources and reference skills with skill://.kiro/skills/*/SKILL.md. A file://.kiro/steering/**/*.md glob loads every document at startup and defeats the fileMatch, manual and auto inclusion modes. On CLI 2.x list the documents you need explicitly.

Security

See SECURITY.md. In short: no credentials of its own, no shell, validated remote URLs with an optional host allow list, path containment for every write, central symlinks never followed, git hooks disabled in the cache, secret scanning before a push, recursion guards in hooks, redacted logs, SHA pinned actions, locked and audited dependencies, signed provenance on releases.

Development

uv sync --all-extras --group dev
uv run pytest --cov
uv run ruff check . && uv run ruff format --check . && uv run mypy

See CONTRIBUTING.md and docs/architecture.md.

Licence

Apache 2.0. Kiro is a trademark of Amazon Web Services; this project is not affiliated with AWS.