# Atlas Collector

## Overview

![Sessions workflow: collect, analyze, review, and improve the next session.](https://agent-session-atlas.vercel.app/overview-cycle.svg)

## Collector 시작하기

PC당 하나만 설치합니다. 처음에는 설치 → pause → 범위 설정·inventory → connect → sync 순서로 실행하고, 자동 전송이 필요하면 resume 합니다.

### Collector 설치

macOS와 Node.js 22.15 이상이 필요합니다. 로그인 시와 30분마다 실행하는 스케줄러, 웹 조회에 응답하는 백그라운드 프로세스를 등록합니다.

```bash
npm install --global @agent-observatory/collector
atlas-collector setup
```

### 자동 전송을 멈추고 범위 선택

먼저 자동 전송을 멈추세요. 모든 프로젝트가 기본 대상이므로, 일부만 올리려면 아래 프로젝트·기간 설정의 configure 명령으로 범위를 지정한 뒤 진행하세요.

```bash
atlas-collector pause
```

### 수집 범위 확인

Codex와 Claude Code의 로컬 기록 수와 용량을 확인합니다. 이 명령은 파일을 전송하지 않습니다.

```bash
atlas-collector inventory
```

### GitHub 계정에 연결

명령에 표시된 주소를 열어 로그인하고, PC에 표시된 코드와 같은지 확인한 뒤 연결을 승인하세요. 연결해도 pause 설정은 유지됩니다. 확인한 범위만 수동 sync하고, 자동 전송이 필요하면 resume 하세요.

```bash
atlas-collector connect
```

### 지금 가져오기·분석

변경된 기록을 전송합니다. 완료 후 세션 페이지에서 전체 또는 선택한 세션을 분석하세요.

```bash
atlas-collector sync
```

## 웹에서 현재 수집 범위 확인

설정 → 연결된 기기 → 현재 설정 조회를 누르세요. 실행 중인 Collector가 요청을 받은 뒤 로컬 설정과 수집 대상 프로젝트를 읽습니다. 전송할 세션 본문을 읽거나 업로드하지 않습니다.

### Collector 실행

연결할 수 없다는 안내가 나오면 해당 PC에서 실행하세요. 기존 pause 설정을 유지하며 예약 실행과 웹 조회 응답을 시작합니다. 네트워크가 정상일 때 조회 요청은 보통 10초 이내 확인하며, 파일 수에 따라 결과 계산 시간이 더 걸릴 수 있습니다.

```bash
atlas-collector start
```

### Collector 종료

예약 실행과 웹 조회 응답을 종료합니다. 다시 start하거나 다음 로그인 시 시작됩니다. 자동 전송만 멈추려면 pause를 사용하세요.

```bash
atlas-collector stop
```

- **조회 결과**: 포함·제외 프로젝트, 기간, 활성 에이전트, 프로젝트별 로컬 세션 수·원본 크기와 조회 시각. 200개 초과 목록은 일부만 표시합니다.

- **대기 전송**: 이미 대기 중인 배치는 새 제외 설정과 별개입니다. 표시한 원본 크기는 실제 압축 전송량이나 새로 전송할 양이 아닙니다.

- **연결·보관**: 응답이 없으면 현재 설정을 표시하지 않습니다. 조회 결과는 5분 동안만 서버에서 읽을 수 있고, 만료 뒤 Collector 연결 또는 매시간 정리 작업에서 제거합니다. 키와 세션 본문은 포함하지 않습니다.

## 프로젝트·기간 설정

기본은 모든 프로젝트입니다. 경로와 그 하위 폴더가 함께 선택되며 exclude가 include보다 우선합니다. 여러 경로는 쉼표로 구분하고, 공백이 있는 값은 따옴표로 감싸세요.

### 자동 전송 중지

범위를 바꾸기 전에 실행하세요. 이미 실행 중인 sync를 종료하거나 기존 대기 파일을 지우지는 않습니다.

```bash
atlas-collector pause
```

### 포함할 프로젝트

예시 경로를 내 프로젝트의 절대 경로로 바꾸세요. 기존 include 목록을 교체합니다.

```bash
atlas-collector configure --include "/path/to/project-a,/path/to/project-b"
```

### 제외할 프로젝트

기존 exclude 목록을 교체합니다. 이미 서버에 올라간 세션은 웹에서 별도로 삭제합니다.

```bash
atlas-collector configure --exclude "/path/to/private-project"
```

### 기간 제한

세션 시작 시각으로 범위를 고릅니다. 세션 내부 메시지를 이 기간으로 자르지 않습니다. 날짜와 UTC 오프셋을 원하는 값으로 바꾸세요.

```bash
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의 해당 배열만 []로 수정합니다.

```bash
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 수집 제외 예시

아래는 변경할 부분만의 예시입니다. 파일 전체를 덮어쓰지 말고 기존 연결·경로·설정을 유지한 채 합치세요.

```json
{
  "sources": {
    "claude-code": { "enabled": false }
  }
}
```

## 동기화 관리

macOS launchd가 로그인 시와 30분마다 실행합니다. Codex 앱과 독립적이며, PC가 꺼져 있으면 전송하지 않습니다. 설정·진행 위치는 로컬에, 기기 토큰은 macOS Keychain에 보관합니다.

### 상태 확인

inventory와 status/doctor는 JSON을 출력합니다. status/doctor는 연결·pause·대기 배치를 표시합니다. 서버 마지막 활동은 웹 설정에서 확인합니다.

```bash
atlas-collector doctor
```

### 자동 전송 재개

선택한 범위가 맞는지 확인한 후 재개합니다. sync는 pause 중에도 수동 실행됩니다.

```bash
atlas-collector resume
```

### Collector 업데이트

설치할 Release 패키지의 update 명령을 실행합니다. 현재 설치본의 update만 실행하면 그 버전을 다시 설치하며 최신 버전을 자동 검색하지 않습니다. 설정·Outbox는 유지됩니다.

```bash
npm install --global @agent-observatory/collector
atlas-collector update
```

### 자동 실행 해제

LaunchAgent와 실행 링크를 해제합니다. 원본·설정·접수증·대기 파일은 보존합니다.

```bash
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 → 서버 접수와 분석 결과 확인. 원본·키를 출력하거나 범위를 임의 확대하지 마세요. 삭제는 정확한 세션을 확인한 뒤 웹에서 실행합니다.