AgentSync 설치 가이드: CLI와 크롬 확장 프로그램 설치 방법

AgentSync는 CLI를 명령 한 줄로 설치하고, 크롬 확장 프로그램은 zip을 압축 해제해 불러오면 됩니다. Node.js 18 이상이 있으면 Windows·macOS·Linux 어디서나 약 5분이면 첫 동기화까지 끝나며, Free 플랜(₩0)으로 기기 2대까지 바로 쓸 수 있습니다.

무료로 시작 확장 프로그램 다운로드

설치 전 준비물

Node.js 18 이상과 npm (node -v로 확인, 없으면 nodejs.org에서 LTS 설치)
AgentSync 계정 (계정 페이지에서 무료 가입)
Claude Code(~/.claude) 또는 Codex CLI(~/.codex)를 한 번 이상 실행한 컴퓨터
크롬 확장을 쓰려면 Chrome 114 이상 (사이드패널 지원)

CLI 설치 방법

macOS · Linux

curl -fsSL https://one.tnvjaos.com/agentsync/download/install.sh | sh

Windows (PowerShell)

irm https://one.tnvjaos.com/agentsync/download/install.ps1 | iex

직접 설치 (npm)

npm i -g https://one.tnvjaos.com/agentsync/download/agentsync-cli.bin

터미널에서 AgentSync CLI 설치 후 login·setup·sync를 실행하는 화면

첫 동기화

설치 스크립트가 끝나면 agentsync start 가 자동으로 실행됩니다. 직접 실행해도 같습니다.

이메일·비밀번호 입력 — 계정이 없으면 그 자리에서 만들어지고, 이 컴퓨터가 기기로 등록됩니다.
동기화 암호 입력 — 첫 컴퓨터에서 정한 암호를 두 번째 컴퓨터부터 똑같이 입력해야 복호화됩니다.
첫 동기화 — 다른 기기의 세션을 받고 내 세션을 올립니다. 기록이 많으면 몇 분 걸립니다.
자동 동기화 등록 — 이후에는 백그라운드에서 계속 동기화됩니다(systemd · launchd · 작업 스케줄러).

크롬 확장 프로그램 설치 방법

Chrome 웹 스토어 등록 전까지는 아래처럼 직접 불러옵니다.

agentsync-extension.zip을 내려받아 압축을 풉니다.
주소창에 chrome://extensions를 입력하고 오른쪽 위 개발자 모드를 켭니다.
압축해제된 확장 프로그램 로드를 눌러 압축을 푼 폴더를 선택합니다.
툴바의 AgentSync 아이콘(또는 Alt+Shift+S)을 눌러 사이드패널을 열고 로그인 후 같은 동기화 암호를 입력합니다.

크롬에 설치한 AgentSync 사이드패널에서 Claude Code·Codex 세션을 고르는 화면

ChatGPT·Claude.ai 화면 오른쪽 아래의 AS 버튼으로 최근 세션 10개 중 하나를 골라 입력창에 바로 넣을 수 있습니다.

CLI 명령어 목록

명령	설명
`agentsync start`	처음 한 번: 계정 연결(없으면 가입) → 동기화 암호 → 첫 동기화 → 자동 동기화 등록
`agentsync login`	계정 로그인, 이 컴퓨터를 기기로 등록 (--name 으로 기기 이름 지정)
`agentsync setup`	동기화 암호 설정·확인 (서버로 전송되지 않음)
`agentsync sync`	다른 기기 변경 받기(pull) 후 내 변경 올리기(push)
`agentsync push / pull`	올리기만 / 받기만
`agentsync watch`	파일 변경 감지 + 60초 간격 자동 동기화 (포그라운드)
`agentsync service install`	자동 동기화를 백그라운드 서비스로 등록 (systemd · launchd · 작업 스케줄러)
`agentsync status`	계정, 플랜, 사용량, 마지막 동기화 확인
`agentsync sessions --search 키워드`	모든 기기의 Claude·Codex 세션 검색
`agentsync resume <세션ID>`	세션을 받아와 claude --resume 또는 codex resume 명령 출력 (--run 으로 바로 실행)
`agentsync handoff <세션ID> --to codex`	세션을 다른 AI에 넘길 마크다운 프롬프트로 변환
`agentsync inbox`	크롬 확장에서 보낸 메모·프롬프트 확인
`agentsync devices`	기기 목록, rm <ID> 삭제, rename <ID> <이름> 이름 변경
`agentsync config pathmap add <원래경로> <내경로>`	OS·사용자명이 다른 기기 사이의 프로젝트 경로 매핑
`agentsync logout`	로그아웃 (이 기기의 토큰 폐기)

동기화 대상 파일

도구	동기화됨	제외됨
Claude Code	`projects/*/.jsonl`, CLAUDE.md, commands, agents, skills, output-styles, settings.json(비밀값 제거)	.credentials.json, cache, shell-snapshots, todos, debug, file-history, plugins
Codex CLI	`sessions/*/.jsonl`, AGENTS.md, config.toml, prompts, instructions.md	auth.json, log, tmp, 토큰·키·.env 파일

50MB를 넘는 파일은 건너뜁니다(agentsync config set maxFileMB 100으로 변경). Free 플랜은 최근 30일 안에 수정된 세션만 올라갑니다.

문제 해결

agentsync 명령을 찾을 수 없다고 나오면 어떻게 하나요?

npm 전역 설치 폴더가 PATH에 없어서 생기는 문제입니다. npm prefix -g 로 나온 경로의 bin(Windows는 그 경로 자체)을 PATH에 추가하고 터미널을 새로 여세요. 그래도 안 되면 node -v 가 18 이상인지 확인한 뒤 설치 스크립트를 다시 1번 실행하면 됩니다.

Windows에서 설치 스크립트 실행이 막히면 어떻게 하나요?

PowerShell 실행 정책 때문이며 현재 창에서만 허용하면 됩니다. Set-ExecutionPolicy -Scope Process Bypass 를 실행한 뒤 irm https://one.tnvjaos.com/agentsync/download/install.ps1 | iex 를 다시 입력하세요. 이 설정은 창을 닫으면 원래대로 돌아가므로 시스템 보안 설정은 바뀌지 않습니다.

기기 수 제한 오류(limit_devices)가 나오면 어떻게 하나요?

플랜의 CLI 기기 대수를 다 쓴 상태입니다. Free는 2대, Pro는 10대까지이며 크롬 확장은 대수에 포함되지 않습니다. 계정 페이지나 agentsync devices rm <ID> 로 쓰지 않는 기기를 삭제하면 바로 다시 로그인할 수 있고, 더 필요하면 Pro(월 ₩9,900)로 올리면 됩니다.

다른 컴퓨터에서 세션이 resume 목록에 안 보이면 어떻게 하나요?

대부분 프로젝트 폴더 경로가 달라서 생깁니다. agentsync config pathmap add 로 예를 들어 /Users/kim 을 C:\Users\kim 으로 매핑한 뒤 agentsync pull 을 다시 실행하세요. 홈 폴더 차이는 자동으로 맞추며, agentsync sessions 로 1번 전체 목록을 확인하면 어느 기기 세션인지 알 수 있습니다.

동기화 충돌이 생기면 내 파일이 지워지나요?

아니요, 로컬 파일은 지워지지 않습니다. 같은 세션이 두 기기에서 서로 다르게 이어진 경우 내 파일은 그대로 두고 상대 기기 버전을 ~/.agentsync/conflicts 폴더에 저장합니다. 설정 파일은 더 최근 것이 적용되며 덮어쓰기 전 원본을 ~/.agentsync/backups 에 시간별로 백업합니다.

해결되지 않으면 tnvjaos88@gmail.com로 agentsync status 결과와 함께 문의하세요.