AI 에이전트의 설정을 여러 AI 코딩 어시스턴트 전반에 걸쳐 심볼릭 링크(symbolic links)를 사용하여 빠르고 휴대 가능한 CLI 도구입니다.

AgentSync 작동 방식 개요: 많은 AI 도구들이 서로 다른 설정 위치를 기대하기 때문에, AgentSync는 .agents/ 디렉토리를 단일 진실 공급원(single source of truth)으로 만들고 이를 모든 곳에 동기화합니다.

flowchart LR
subgraph Problem[문제: 파편화된 AI 도구 설정]
Claude[Claude Code]
...

flowchart LR
Init[agentsync init<br/>설정 생성 또는 마이그레이션] --> Apply[agentsync apply<br/>심볼릭 링크 생성 또는 새로고침]
Apply --> Status[agentsync status<br/>동기화 상태 검사]
...

다양한 AI 코딩 도구들은 설정 파일을 여러 위치에 기대합니다:

AgentSync는 .agents/에 단일 진실 공급원을 유지하고 필요한 모든 위치에 심볼릭 링크를 생성합니다.

• 🔗 복사본 대신 심볼릭 링크 사용: 변경 사항이 즉시 전파됩니다. - 📝 TOML 설정 파일: 사람이 읽기 쉽고 관리하기 편리합니다. - 📋 .gitignore 관리: 자동으로 .gitignore 파일을 업데이트합니다.

• 🛡️ 안전성: 기존 파일을 대체하기 전에 자동으로 백업합니다. - 🖥️ 크로스 플랫폼: Linux, macOS, Windows를 지원합니다. - 🚀 CI 친화적: 바이너리가 사용 불가능할 경우 우아하게 건너뜁니다. - ⚡ 빠른 속도: 런타임 의존성이 없는 단일 정적 바이너리입니다. - 🧩 큐레이션된 스킬: dallay/agents-skills 컬렉션 또는 외부 제공업체로부터 설치할 수 있습니다.

AgentSync는 모든 스킬 항목이 여전히 올바르게 해결되고, 설치되며, 등록될 수 있는지 검증하는 전체 카탈로그 설치 E2E(End-to-End) 체크를 제공합니다.

• GitHub Actions 워크플로우:
  Catalog E2E

• 수동 실행: Actions → Catalog E2E→워크플로우 실행 - 예약 실행: 매주 월요일 08:00 UTC

• 로컬 실행:

git clone https://github.com/dallay/agents-skills ../agents-skills
export AGENTSYNC_LOCAL_SKILLS_REPO="$(pwd)/../agents-skills"
RUN_E2E=1 cargo test --test test_catalog_integration -- --ignored --nocapture

만약 이미 agents-skills를 이 리포지토리 옆에 있는 형제 체크아웃(sibling checkout)으로 유지하고 있다면, 환경 변수를 건너뛰고 테스트가 해당 형제 경로를 자동으로 감지하도록 할 수 있습니다.

이 체크는 외부 네트워크와 서드파티 스킬 레포지토리에 의존하기 때문에 일반적인 CI(Continuous Integration)와는 의도적으로 분리되어 있습니다.

Node.js (>=18)가 설치되어 있다면, 패키지 관리자를 통해 AgentSync를 설치하는 가장 쉬운 방법은 다음과 같습니다.

# npm 사용
npm install -g @dallay/agentsync
# pnpm 사용
...

영구적인 전역 설치 없이 AgentSync를 실행하려면:

# npx (npm) 사용
npx @dallay/agentsync apply
# dlx (pnpm) 사용
...

# npm 사용
npm install --save-dev @dallay/agentsync
# pnpm 사용
...

Rust가 설치되어 있다면, crates.io에서 AgentSync를 직접 설치할 수 있습니다:

cargo install agentsync

최신 버전 번호와 시스템에 맞는 정확한 플랫폼 식별자는 GitHub Releases 페이지를 방문하여 확인하세요.

터미널을 통해 설치하려면 다음 스크립트를 사용할 수 있습니다 (반드시 <version> 플레이스홀더를 실제 태그, 예: 1.28.0으로 교체해야 합니다):

# 버전 및 플랫폼 정의
VERSION="<version>"
# 아키텍처 감지 (macOS)
...

GitHub 리포지토리에서 직접 설치하려면 (Node.js 22.22.0+ 및 Rust 1.89+ 필요):

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

또는 클론하여 수동으로 빌드할 수 있습니다:

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

프로젝트에 설정 초기화하기:

cd your-project
agentsync init

이 명령어는 기본 설정을 가진 .agents/agentsync.toml 파일을 생성합니다.

만약 이미 프로젝트 전반에 걸쳐 에이전트 설정 파일들(예: CLAUDE.md, .cursor/, 또는 .github/copilot-instructions.md)이 분산되어 있다면, 대화형 마법사(interactive wizard)를 사용하세요:

cd your-project
agentsync init --wizard

마법사가 기존 파일을 스캔하고, 어떤 파일을 마이그레이션할지 선택하도록 하며, 모든 것을 자동으로 설정해 줍니다.

필요에 맞게 설정 편집하기(설정 참조) -
설정 적용하기:

agentsync apply

프로젝트 설정에 추가하기(예: package.json):

{
"scripts": {
"prepare": "agentsync apply || true"
... 
}

AgentSync는 기본적으로 관리되는 .gitignore 모드([gitignore].enabled = true)를 사용하며, 이는 대부분의 팀에게 권장되는 시작점입니다. 만약 팀이 의도적으로 AgentSync가 관리하는 목적지(destination)에 커밋하기를 원한다면, [gitignore].enabled = false를 명시적인 제외 워크플로우로 간주하십시오. 자세한 내용은 다음 가이드에서 확인하세요: https://dallay.github.io/agentsync/guides/gitignore-team-workflows/

만약 Windows 환경에서 AgentSync를 실행하고 네이티브 심볼릭 링크(symlink) 전제 조건, WSL 가이드 또는 복구 단계가 필요하다면, 전용 설정 가이드를 사용하세요: https://dallay.github.io/agentsync/guides/windows-symlink-setup/

만약 팀이 브랜치 전환, 병합(merge), 또는 리베이스(rebase) 후에 agentsync apply가 실행되기를 원한다면, Lefthook, Husky, simple-git-hooks 및 네이티브 훅 예제를 위한 Git 훅 자동화 가이드를 사용하세요: https://dallay.github.io/agentsync/guides/git-hook-automation/

# 새로운 설정 초기화
agentsync init
# 대화형 마법사로 초기화 (에이전트 파일이 있는 기존 프로젝트용)
...

AgentSync가 관리하는 대상(target)의 상태를 확인합니다. 로컬 검증 및 CI 환경에서 유용합니다.

agentsync status [--project-root <path>] [--json]

--project-root <path>
: 선택 사항. agentsync 설정을 찾을 프로젝트 루트 경로입니다.
--json

출력은 기계가 읽을 수 있는 JSON 형식(pretty-printed)입니다.

status

is sync-type aware:

symlink
targets는 하나의 관리되는 목적지 심볼릭 링크로 확인됩니다. symlink-contents
targets는 관리되는 자식 항목의 목적지 디렉터리로 확인되며, 이 자식 항목들이 심볼릭 링크입니다. - 기존에 비어 있는 .agents/commands/ 소스 디렉터리는 유효하므로, 현재 0개의 관리된 항목을 가지고 있다는 이유만으로 빈 목적지인 .claude/commands/가 누락되거나 "심볼릭 링크가 아님"으로 보고되지 않습니다.

종료 코드: 0 = 문제 없음, 1 = 문제 감지됨 (CI 친화적)
설정은 .agents/agentsync.toml에 저장됩니다.

# Source directory (relative to this config file)
source_dir = "." # 이 설정 파일 기준의 소스 디렉터리
# Optional: compress AGENTS.md and point symlinks to the compressed file
...

AgentSync는 지원되는 에이전트(Claude Code, GitHub Copilot, OpenAI Codex CLI, Gemini CLI, Cursor, VS Code, OpenCode, Z-Code, MiniMax Code)에 대한 MCP 설정 파일을 자동으로 생성할 수 있습니다.

이를 통해 agentsync.toml에서 MCP 서버를 한 번만 정의하고 모든 에이전트별 설정 파일과 동기화할 수 있습니다.

[mcp]
enabled = true
# Strategy for existing files: "merge" (default) or "overwrite"
...

Claude Code—.mcp.json
(에이전트 ID:claude)
— JSON; 표준 형식
Claude Desktop—Global OS-dependent config
(에이전트 ID:claude-desktop)
— JSON; 전역적이며 기본적으로 비활성화됨
GitHub Copilot—.vscode/mcp.json
(에이전트 ID:copilot)
— JSON; VS Code와 공유
OpenAI Codex CLI—.codex/config.toml
(에이전트 ID:codex)
— TOML; 헤더를 http_headers에 매핑
Gemini CLI—.gemini/settings.json
(에이전트 ID:gemini)
— JSON; trust: true 추가
VS Code—.vscode/mcp.json
(에이전트 ID:vscode)
— JSON; GitHub Copilot과 공유
Cursor—.cursor/mcp.json
(에이전트 ID:cursor)
— JSON; 표준 형식
OpenCode—opencode.json
(에이전트 ID:opencode)
— JSON; 표준 형식
Z-Code—.zcode/config.json
(에이전트 ID:zcode}

) — JSON; mcp.servers 객체를 사용하며 다른 Z-Code 설정은 유지합니다.MiniMax Code—.mcp.json

(agent id:minimax)

) — JSON; 프로젝트 레벨 표준 형식입니다.

AgentSync는 위에 언급된 네이티브 MCP 에이전트를 지원합니다. 타입 지정된 레지스트리 및 집중화된 CI 검증기(CI validator)가 권위적입니다.

AgentSync는 또한 Windsurf, Cline, Amazon Q, Aider, RooCode, Trae 등 32개 이상의 구성 가능한 에이전트를 지원합니다. 전체 목록은 문서를 참조하십시오.

포매터 세부 정보 및 병합 동작(merge behavior)에 대해서는 MCP Integration Guide를 참조하십시오.

agentsync revert

이 명령어는 리포지토리 외부에 저장된 전체 파일 스냅샷으로부터 MCP 설정을 복원합니다. 원본 설정에는 자격 증명(credentials)이 포함될 수 있으며, 스냅샷은 자동 만료되지 않습니다. 자세한 내용은 MCP 저널 및 복원 가이드(restore guide)를 참조하십시오.

merge_strategy = "merge"일 때

:

• AgentSync는 기존 구성 파일(존재하는 경우)을 읽습니다.
• agentsync.toml에 정의된 서버들을 추가합니다. 충돌 해결: 만약 두 곳 모두에 서버 이름이 존재하는 경우, agentsync.toml의 정의가 우선하여 기존 설정을 덮어씁니다. - agentsync.toml에 없는 기존 서버들은 보존됩니다.

symlink-contents 유형은 선택적으로 pattern 필드(예: *.md와 같은 glob 패턴)를 지원하여 어떤 항목을 링크할지 필터링할 수 있습니다. AgentSync는 목적지를 관리되는 디렉터리 컨테이너로 취급하므로, agentsync status는 해당 디렉터리 자체가 심볼릭 링크일 것으로 예상하는 대신 그 내부의 자식 링크들을 검증합니다.

nested-glob 유형은 재귀적 glob 패턴과 일치하는 파일을 검색하고 발견된 각 파일에 대해 심볼릭 링크를 생성합니다. 이는 서로 다른 하위 디렉터리에 자체 AGENTS.md 파일을 포함하는 모노레포 및 다중 모듈 프로젝트에 이상적입니다.

[agents.claude.targets.nested]

검색할 루트 디렉토리 (프로젝트 루트 기준)

source = "."
...

구조가 다음과 같다고 가정해 봅시다:

project-root/
├── .agents/
│ └── AGENTS.md # .agents/**에 의해 제외됨
...

AgentSync는 다음을 생성합니다:

clients/agent-runtime/CLAUDE.md
→ clients/agent-runtime/AGENTS.md에 대한 심볼릭 링크(symlink)

modules/core-kmp/CLAUDE.md
→ modules/core-kmp/AGENTS.md에 대한 심볼릭 링크(symlink)

.agents/
├── agentsync.toml # 설정 파일 (MCP의 진실 공급원, source of truth)
├── AGENTS.md # 주요 에이전트 지침 (단일 출처, single source)
...

agentsync apply를 실행한 후:

:

project-root/
├── CLAUDE.md → .agents/AGENTS.md
├── GEMINI.md → .agents/AGENTS.md
...

AgentSync는 바이너리가 사용 불가능한 CI 환경에서도 원활하게 작동합니다:

{
"scripts": {
"agents:sync": "pnpm exec agentsync apply",
...}

이 심볼릭 링크들은 주로 로컬 개발용입니다. CI 빌드에서는 일반적으로 필요하지 않습니다.

만약 CI에서 agentsync가 필요한 경우, jq를 사용하여 안정적인 파싱을 위해 최신 버전을 자동으로 다운로드할 수 있습니다:

- name: Install agentsync
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
...```

AgentSync는 110개 이상의 기술에 걸쳐 200개 이상의 스킬을 갖춘 엄선된 스킬 카탈로그를 포함하고 있습니다. 스킬은 프로젝트에 설치할 수 있는 AI 에이전트 지침의 작은 번들입니다.

**dallay/agents-skills**— dallay가 유지 관리하는 모든 스킬의 표준 홈(Canonical home)입니다. 커뮤니티 기여는 PR을 통해 환영합니다.**외부 제공업체(External providers)**— Angular, Vercel, Cloudflare, Expo, Stripe 등 여러 곳의 스킬은 해당 저장소에서 해결됩니다.

프로젝트 기술 감지 및 스킬 추천 받기

agentsync skill suggest

스킬 설치하기

...```

전체 문서는 Skills Guide를 참조하세요.

이 프로젝트는 Rust 코어와 JavaScript/TypeScript 래퍼(wrapper)를 포함하는 모노레포입니다.

src/
: Rust로 작성된 핵심 로직 및 CLI 구현체.npm/agentsync/
:
NPM 배포에 사용되는 TypeScript 래퍼. website/docs/
:
Starlight로 구축된 문서 사이트.tests/

⚠️ [IMG:N]

CLI를 위한 통합 테스트:

JavaScript 종속성 설치: pnpm install

Rust 바이너리 빌드: cargo build

이 프로젝트는 공통 작업을 조정하기 위해 Makefile을 사용합니다.

Rust 테스트 실행: make rust-test

JavaScript 테스트 실행: make js-test

모든 구성 요소 빌드: make all

전체 검증 실행 (린트 + 빌드 + 테스트): make verify-all

코드 린트: # Rust cargo clippy # JavaScript/TypeScript pnpm run biome:check

코드 포맷팅: make fmt

릴리스는 semantic-release와 GitHub Actions를 통해 관리됩니다. 로컬에서 드라이런을 트리거하려면 다음 명령어를 사용하세요:

pnpm run release:dry-run

만약 pnpm install