AgentSync

From Source (Requires Rust 1.89+)

Install directly from the GitHub repository (requires Node.js 22.22.0+ and Rust 1.89+):

cargo install --git https://github.com/dallay/agentsync

Or clone and build manually:

```bash git clone https://github.com/dallay/agentsync cd agentsync cargo build --release

Prerequisites

• Rust (1.89+ recommended)
• Node.js (v22.22.0+ recommended for development)
• pnpm

Installation

Extract and install

tar xzf "${TARBALL}" sudo mv agentsync-*/agentsync /usr/local/bin/ ```

Installing in CI

If you need agentsync in CI, you can download the latest version automatically using jq for robust parsing:

- name: Install agentsync
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    # Fetch latest version using GitHub API and jq
    LATEST_TAG=$(curl -s -H "Authorization: Bearer $GH_TOKEN" \
      https://api.github.com/repos/dallay/agentsync/releases/latest | jq -r '.tag_name')
    
    if [ "$LATEST_TAG" == "null" ] || [ -z "$LATEST_TAG" ]; then
      echo "Error: Failed to fetch latest release tag"
      exit 1
    fi
    
    VERSION=${LATEST_TAG#v}
    PLATFORM="x86_64-unknown-linux-gnu"
    
    curl -LO "https://github.com/dallay/agentsync/releases/download/${LATEST_TAG}/agentsync-${VERSION}-${PLATFORM}.tar.gz"
    tar xzf agentsync-${VERSION}-${PLATFORM}.tar.gz
    sudo mv agentsync-*/agentsync /usr/local/bin/

Install a skill

agentsync skill install docker-expert

Install all recommended skills non-interactively

agentsync skill suggest --install --all ```

See the Skills Guide for full documentation.

Getting Started (Development)

This project is a monorepo containing a Rust core and a JavaScript/TypeScript wrapper.

Setup

1. Install JavaScript dependencies:

    pnpm install
    

1. Build the Rust binary:

    cargo build
    

Lefthook installation failure

If pnpm install fails during the lefthook setup, you can try:

pnpm install --ignore-scripts

Build failures (Rust)

Ensure you have the latest stable Rust toolchain installed. You can update with rustup update stable.

Quick Start

Usage

```bash

Initialize a new configuration

agentsync init

Apply configuration (create symlinks)

agentsync apply

Use a custom config file

agentsync apply --config /path/to/config.toml

Configuration

Configuration is stored in .agents/agentsync.toml:

```toml

Source directory (relative to this config file)

source_dir = "."

Optional: compress AGENTS.md and point symlinks to the compressed file

"merge" preserves existing servers but overwrites conflicts with TOML config

merge_strategy = "merge"

Optional fields:

env = { "KEY" = "VALUE" }

Typical workflow

Node.js Package Managers (Recommended)

If you have Node.js (>=18) installed, the easiest way to install AgentSync is through a package manager.

Global Installation

```bash

Team workflow note

AgentSync defaults to managed .gitignore mode ([gitignore].enabled = true), which is the recommended starting point for most teams. If your team intentionally wants to commit AgentSync-managed destinations instead, treat [gitignore].enabled = false as an explicit opt-out workflow. See the canonical guide: <https://dallay.github.io/agentsync/guides/gitignore-team-workflows/>

If you run AgentSync from Windows and need native symlink prerequisites, WSL guidance, or recovery steps, use the dedicated setup guide: <https://dallay.github.io/agentsync/guides/windows-symlink-setup/>

If your team wants agentsync apply to run after branch switches, merges, or rebases, use the Git hook automation guide for Lefthook, Husky, simple-git-hooks, and native hook examples: <https://dallay.github.io/agentsync/guides/git-hook-automation/>

{stem} file name without extension (e.g. AGENTS)

{ext} file extension without leading dot (e.g. md)

destination = "{relative_path}/CLAUDE.md"

type = "nested-glob"

Given the structure:

AgentSync would create:

• clients/agent-runtime/CLAUDE.md → symlink to clients/agent-runtime/AGENTS.md
• modules/core-kmp/CLAUDE.md → symlink to modules/core-kmp/AGENTS.md

CI/CD Integration

AgentSync gracefully handles CI environments where the binary isn't available:

{
  "scripts": {
    "agents:sync": "pnpm exec agentsync apply",
    "prepare": "lefthook install && pnpm run agents:sync"
  }
}

The symlinks are primarily for local development. CI builds typically don't need them.

Troubleshooting