Collector 시작하기
PC당 하나만 설치합니다. 처음에는 설치 → pause → 범위 설정·inventory → connect → sync 순서로 실행하고, 자동 전송이 필요하면 resume 합니다.
Collector 설치
macOS와 Node.js 22.15 이상이 필요합니다. 로그인 시와 30분마다 실행하는 스케줄러, 웹 조회에 응답하는 백그라운드 프로세스를 등록합니다.
npm install --global @agent-observatory/collector atlas-collector setup자동 전송을 멈추고 범위 선택
먼저 자동 전송을 멈추세요. 모든 프로젝트가 기본 대상이므로, 일부만 올리려면 아래 프로젝트·기간 설정의 configure 명령으로 범위를 지정한 뒤 진행하세요.
atlas-collector pause수집 범위 확인
Codex와 Claude Code의 로컬 기록 수와 용량을 확인합니다. 이 명령은 파일을 전송하지 않습니다.
atlas-collector inventoryGitHub 계정에 연결
명령에 표시된 주소를 열어 로그인하고, PC에 표시된 코드와 같은지 확인한 뒤 연결을 승인하세요. 연결해도 pause 설정은 유지됩니다. 확인한 범위만 수동 sync하고, 자동 전송이 필요하면 resume 하세요.
atlas-collector connect지금 가져오기·분석
변경된 기록을 전송합니다. 완료 후 세션 페이지에서 전체 또는 선택한 세션을 분석하세요.
atlas-collector sync
웹에서 현재 수집 범위 확인
설정 → 연결된 기기 → 현재 설정 조회를 누르세요. 실행 중인 Collector가 요청을 받은 뒤 로컬 설정과 수집 대상 프로젝트를 읽습니다. 전송할 세션 본문을 읽거나 업로드하지 않습니다.
Collector 실행
연결할 수 없다는 안내가 나오면 해당 PC에서 실행하세요. 기존 pause 설정을 유지하며 예약 실행과 웹 조회 응답을 시작합니다. 네트워크가 정상일 때 조회 요청은 보통 10초 이내 확인하며, 파일 수에 따라 결과 계산 시간이 더 걸릴 수 있습니다.
atlas-collector startCollector 종료
예약 실행과 웹 조회 응답을 종료합니다. 다시 start하거나 다음 로그인 시 시작됩니다. 자동 전송만 멈추려면 pause를 사용하세요.
atlas-collector stop
- 조회 결과
- 포함·제외 프로젝트, 기간, 활성 에이전트, 프로젝트별 로컬 세션 수·원본 크기와 조회 시각. 200개 초과 목록은 일부만 표시합니다.
- 대기 전송
- 이미 대기 중인 배치는 새 제외 설정과 별개입니다. 표시한 원본 크기는 실제 압축 전송량이나 새로 전송할 양이 아닙니다.
- 연결·보관
- 응답이 없으면 현재 설정을 표시하지 않습니다. 조회 결과는 5분 동안만 서버에서 읽을 수 있고, 만료 뒤 Collector 연결 또는 매시간 정리 작업에서 제거합니다. 키와 세션 본문은 포함하지 않습니다.
프로젝트·기간 설정
기본은 모든 프로젝트입니다. 경로와 그 하위 폴더가 함께 선택되며 exclude가 include보다 우선합니다. 여러 경로는 쉼표로 구분하고, 공백이 있는 값은 따옴표로 감싸세요.
자동 전송 중지
범위를 바꾸기 전에 실행하세요. 이미 실행 중인 sync를 종료하거나 기존 대기 파일을 지우지는 않습니다.
atlas-collector pause포함할 프로젝트
예시 경로를 내 프로젝트의 절대 경로로 바꾸세요. 기존 include 목록을 교체합니다.
atlas-collector configure --include "/path/to/project-a,/path/to/project-b"제외할 프로젝트
기존 exclude 목록을 교체합니다. 이미 서버에 올라간 세션은 웹에서 별도로 삭제합니다.
atlas-collector configure --exclude "/path/to/private-project"기간 제한
세션 시작 시각으로 범위를 고릅니다. 세션 내부 메시지를 이 기간으로 자르지 않습니다. 날짜와 UTC 오프셋을 원하는 값으로 바꾸세요.
atlas-collector configure --since "2026-09-01T00:00:00+09:00" --until "2026-09-07T23:59:59+09:00"포함·기간 제한 해제
--all은 include와 since/until만 초기화합니다. exclude는 유지됩니다. exclude를 비우려면 config.json의 해당 배열만 []로 수정합니다.
atlas-collector configure --all이미 대기 중인 파일
범위 변경은 새 수집에 적용됩니다. 기존 Outbox 대기 파일은 sync에서 전송될 수 있습니다. status의 batches에 대기 항목이 있으면 전송 전 별도로 검토하세요.
기록 소스와 로컬 설정
Codex(~/.codex)와 Claude Code(~/.claude/projects)가 기본 활성화됩니다. ~/.agent-session-atlas/config.json의 sources에서 enabled와 절대 home 경로를 조정합니다. 소스 전용 CLI 옵션은 아직 없습니다.
Claude Code 수집 제외 예시
아래는 변경할 부분만의 예시입니다. 파일 전체를 덮어쓰지 말고 기존 연결·경로·설정을 유지한 채 합치세요.
{ "sources": { "claude-code": { "enabled": false } } }
동기화 관리
macOS launchd가 로그인 시와 30분마다 실행합니다. Codex 앱과 독립적이며, PC가 꺼져 있으면 전송하지 않습니다. 설정·진행 위치는 로컬에, 기기 토큰은 macOS Keychain에 보관합니다.
상태 확인
inventory와 status/doctor는 JSON을 출력합니다. status/doctor는 연결·pause·대기 배치를 표시합니다. 서버 마지막 활동은 웹 설정에서 확인합니다.
atlas-collector doctor자동 전송 재개
선택한 범위가 맞는지 확인한 후 재개합니다. sync는 pause 중에도 수동 실행됩니다.
atlas-collector resumeCollector 업데이트
설치할 Release 패키지의 update 명령을 실행합니다. 현재 설치본의 update만 실행하면 그 버전을 다시 설치하며 최신 버전을 자동 검색하지 않습니다. 설정·Outbox는 유지됩니다.
npm install --global @agent-observatory/collector atlas-collector update자동 실행 해제
LaunchAgent와 실행 링크를 해제합니다. 원본·설정·접수증·대기 파일은 보존합니다.
atlas-collector uninstall
Data residency & retention
변경된 텍스트와 이미지 메타데이터를 압축해 전송합니다. 이미지 본문은 로컬에 남기며, 민감정보 마스킹은 기본적으로 서버 저장 전에 적용합니다.
- 웹·API
- Vercel · Seoul (icn1)
- DB·비공개 파일
- Supabase · Seoul (ap-northeast-2)
- 상세 데이터
- 세션 파일·이벤트·상세 분석 결과: 최대 7일
- 집계 요약
- 간단한 결과 요약: 최대 30일
- AI 처리
- 분석 근거는 선택된 AI 제공자에게 전달됩니다. 처리 위치와 보관은 해당 제공자의 정책을 따르며 Free tier와 BYOK 모두 적용됩니다.
에이전트에서 사용하기
이 문서의 Markdown 원문과 /llms.txt를 에이전트에 전달하세요. 웹과 Markdown은 같은 내용에서 생성합니다. Skill·MCP·플러그인은 아직 배포하지 않았습니다.
권장 작업 순서
요청한 프로젝트·기간 파악 → 현재 설정과 status 확인 → 필요 시 pause → configure → inventory의 규모 검토 → 승인된 범위만 sync → 서버 접수와 분석 결과 확인. 원본·키를 출력하거나 범위를 임의 확대하지 마세요. 삭제는 정확한 세션을 확인한 뒤 웹에서 실행합니다.