포스트

Claude Code 세션 전환 및 백그라운드 작업 완벽 가이드

게시 업데이트
By BLUEBUG
16 분읽는 시간
Claude Code 세션 전환 및 백그라운드 작업 완벽 가이드

📋 목차

  1. 개요
  2. Teleport 기능 (웹→CLI)
  3. 백그라운드 작업 관리
  4. 실전 활용 사례
  5. 문제 해결
  6. 제한사항 및 주의사항

개요

Claude Code는 웹 인터페이스와 로컬 CLI 간의 원활한 작업 전환을 지원하여 개발자의 생산성을 극대화합니다. 이 가이드에서는 세션 전환 및 백그라운드 작업 관리 기능을 상세히 다룹니다.

지원되는 기능

기능방향상태
Teleport웹 → CLI✅ 공식 지원
Session TransferCLI → 웹⚠️ 미지원 (Feature Request 진행 중)
Background Tasks양방향✅ 공식 지원

Teleport 기능 (웹→CLI)

개념

Teleport는 웹 브라우저에서 시작한 Claude Code 세션을 로컬 터미널로 가져오는 기능입니다. 채팅 기록, 편집된 파일, 작업 컨텍스트가 모두 보존됩니다.

사용 방법

1단계: 웹에서 세션 시작

  1. claude.ai/code에 접속
  2. GitHub 저장소 연결 또는 새 프로젝트 시작
  3. 작업 진행

2단계: “Open in CLI” 버튼 클릭

웹 인터페이스에서 “Open in CLI” 또는 “Move to CLI” 버튼을 클릭하면 다음과 같은 명령어가 표시됩니다:

1

claude --teleport session_XXXXXXXXXXXX

3단계: 로컬에서 명령 실행

로컬 터미널에서 복사한 명령어를 실행합니다:

1
2
3
4
5
6

# 기본 사용법
claude --teleport session_011CUpE6ZSg5RQbETyMDpZha

# 특정 디렉토리에서 실행
cd /path/to/project
claude --teleport session_011CUpE6ZSg5RQbETyMDpZha

전송되는 데이터

Teleport 시 다음 정보가 전송됩니다:

  • ✅ 채팅 대화 기록
  • ✅ 편집된 파일 목록 및 내용
  • ✅ 프로젝트 컨텍스트
  • ✅ Git 브랜치 정보
  • ⚠️ 백그라운드 작업 (부분 지원)
  • ❌ 실시간 추가 프롬프트 (알려진 버그)

고급 사용 예시

1
2
3
4
5
6
7
8

# 1. 웹에서 긴 분석 작업 시작
# → Claude.ai/code에서 "전체 코드베이스 분석하고 문서 생성" 요청

# 2. 작업 중 로컬로 전환
claude --teleport session_abc123def456

# 3. 로컬에서 계속 작업
# → 분석 결과를 검토하고 추가 수정 진행

백그라운드 작업 관리

Ctrl+B를 사용한 백그라운드 실행

Claude Code가 명령을 실행할 때 Ctrl+B를 눌러 백그라운드로 전환할 수 있습니다.

기본 사용법

1
2
3
4
5
6
7
8
9
10
11

# 1. 명령 실행 요청
> "npm run dev를 실행해줘"

# 2. Claude가 명령 실행 시작
# → Bash 도구 호출 중

# 3. Ctrl+B 입력
# → 백그라운드로 전환됨 (bash_1)

# 4. 계속 작업 가능
> "새로운 컴포넌트 만들어줘"

Tmux 사용자: Tmux의 prefix key 충돌 때문에 Ctrl+B를 두 번 눌러야 합니다.

백그라운드 작업 모니터링

/bashes 명령어

모든 백그라운드 작업을 확인할 수 있습니다:

1

/bashes

출력 예시:

1
2
3
4
5
6

Background Tasks:
─────────────────────────────────────
ID      Status      Command              Runtime
bash_1  running     npm run dev          00:05:23
bash_2  completed   npm run build        00:02:15
bash_3  failed      npm test             00:00:43

BashOutput 도구로 출력 확인

Claude에게 특정 백그라운드 작업의 출력을 요청할 수 있습니다:

1
2
3
4
5
6
7
8

# 방법 1: 직접 요청
> "bash_1의 출력 보여줘"

# 방법 2: 에러 확인
> "bash_3에 에러가 있는지 확인해줘"

# 방법 3: 전체 상태 확인
> "모든 백그라운드 작업 상태 알려줘"

백그라운드 작업 종료

1
2
3
4
5

# 방법 1: 키보드 단축키
# → K 키를 눌러 선택적으로 종료

# 방법 2: Claude에게 요청
> "bash_1을 종료해줘"

자동 백그라운드 실행 설정

CLAUDE.md 설정

프로젝트의 .claude/CLAUDE.md 파일에 자동 백그라운드 규칙을 정의할 수 있습니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 프로젝트 개발 가이드라인

## 명령 실행 규칙

### 항상 백그라운드에서 실행:
- `npm run dev` - 프론트엔드 개발 서버
- `npm run api` - API 개발 서버
- `docker-compose up` - 로컬 서비스
- `npm run watch` - 파일 감시기
- `--watch` 플래그가 있는 모든 명령

### 백그라운드 모니터링:
백그라운드 작업 시작 후 주기적으로 BashOutput으로 상태를 확인하세요.
백그라운드 작업이 실패하거나 중단되면 알림을 표시하세요.

### 예시 워크플로우:
1. 개발 서버 시작 → 백그라운드로 실행
2. 주기적으로 로그 확인
3. 에러 발생 시 즉시 알림
4. 작업 완료 시 백그라운드 작업 정리

환경 변수 설정

1
2
3
4
5

# 장기 실행 작업 자동 백그라운드화
export FORCE_AUTO_BACKGROUND_TASKS=true

# Unified Read Tool 활성화
export CLAUDE_CODE_ENABLE_UNIFIED_READ_TOOL=true

Bash 모드 (! prefix)

Claude의 승인 없이 직접 명령을 실행할 수 있습니다:

1
2
3
4
5
6
7
8

# 기본 사용법
! npm test
! git status
! ls -la

# 백그라운드 실행 (Ctrl+B)
! npm run dev
# → Ctrl+B 눌러서 백그라운드로 전환

실전 활용 사례

사례 1: 병렬 개발 워크플로우

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 웹에서 시작
# 1. GitHub 저장소 연결
# 2. "전체 아키텍처 리뷰하고 개선 제안해줘" 요청

# 리뷰 진행 중 로컬로 전환
claude --teleport session_abc123

# 로컬에서 병렬 작업
> "백엔드 API 개발 시작해줘"
# → bash_1: npm run api (백그라운드)

> "프론트엔드 개발 환경 설정해줘"
# → bash_2: npm run dev (백그라운드)

> "데이터베이스 마이그레이션 실행해줘"
# → bash_3: npm run migrate

사례 2: 긴 빌드 프로세스 관리

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 빌드 시작
> "프로덕션 빌드 실행해줘"
# → Claude가 docker build 시작

# 2. Ctrl+B로 백그라운드 전환

# 3. 다른 작업 진행
> "테스트 코드 리팩토링해줘"
# (빌드는 백그라운드에서 계속 실행됨)

# 4. 빌드 완료 확인
> "bash_1 빌드 완료됐는지 확인해줘"

사례 3: 모바일에서 시작, 데스크톱에서 완료

1
2
3
4
5
6
7

# 모바일 (출퇴근 중)
# 1. Claude.ai/code 앱에서 버그 수정 시작
# 2. "Open in CLI" 링크 복사

# 데스크톱 (사무실 도착 후)
claude --teleport session_mobile123
# → 모바일에서 시작한 작업 계속 진행

사례 4: 여러 프로젝트 동시 관리

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 터미널 1: 프로젝트 A
cd ~/projects/frontend
claude --teleport session_frontend_xyz
> "React 컴포넌트 최적화 계속해줘"

# 터미널 2: 프로젝트 B
cd ~/projects/backend
claude --teleport session_backend_abc
> "API 성능 테스트 결과 분석해줘"

# 터미널 3: 프로젝트 C
cd ~/projects/microservice
claude
> "새로운 마이크로서비스 개발 시작"

문제 해결

일반적인 오류 및 해결 방법

1. “Failed to fetch session metadata”

원인:

  • 만료된 세션 ID
  • 네트워크 연결 문제
  • OAuth 토큰 만료

해결 방법:

1
2
3
4
5
6
7
8
9

# 1. OAuth 토큰 갱신
claude logout
claude login

# 2. 새로운 세션 ID로 재시도
# 웹에서 "Open in CLI" 다시 클릭

# 3. 네트워크 확인
curl -I https://api.anthropic.com

2. “API Error: 400 - tool use concurrency issues”

원인:

  • 동시 도구 사용 충돌
  • 세션 상태 손상

해결 방법:

1
2
3
4
5
6
7
8
9
10

# 1. /rewind 명령 사용
/rewind

# 2. 세션 재시작이 필요한 경우
/clear
> "이전 작업 컨텍스트 다시 로드해줘"

# 3. 심각한 경우: 새 세션 시작
exit
claude

3. Git 브랜치 불일치

원인:

  • 로컬과 웹 세션의 Git 상태가 다름

해결 방법:

1
2
3
4
5
6
7
8
9
10
11

# 1. 웹 세션에서 생성된 브랜치 확인
git branch -a

# 2. 원격 브랜치 fetch
git fetch origin

# 3. 해당 브랜치로 체크아웃
git checkout feature/web-session-branch

# 4. teleport 재시도
claude --teleport session_xyz

4. 터미널 화면 지워짐 (Clear on Failure)

원인:

  • Teleport 실패 시 터미널이 자동으로 지워짐

해결 방법:

1
2
3
4
5
6

# 1. 에러 메시지 보존하려면
claude --teleport session_xyz 2>&1 | tee teleport.log

# 2. Git 브랜치 수동 체크아웃 후 재시도
git checkout <branch-name>
claude --teleport session_xyz

5. 후속 프롬프트 누락

알려진 버그:

  • 웹에서 작업 중 추가한 프롬프트가 teleport 시 누락됨

임시 해결책:

1
2
3

# 1. 웹에서 중요한 프롬프트를 문서화
# 2. Teleport 후 수동으로 다시 입력
> "이전에 요청한 '보안 감사 추가' 작업 계속해줘"

디버깅 팁

1. 상세 로그 활성화

1
2
3
4
5
6
7
8

# 실행 전 환경 변수 설정
export CLAUDE_CODE_LOG_LEVEL=debug

# Teleport 실행
claude --teleport session_xyz

# 로그 파일 확인
cat ~/.claude/logs/claude-code.log

2. 네트워크 트래픽 검사

1
2
3
4
5

# 프록시 설정으로 트래픽 확인
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

claude --teleport session_xyz

3. 세션 상태 직접 확인 (비공식)

1
2
3

# 세션 메타데이터 API 호출
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/session_ingress/session/SESSION_ID

제한사항 및 주의사항

Teleport 제한사항

제한사항설명영향
단방향만 지원웹→CLI만 가능, CLI→웹 불가로컬 작업을 웹으로 넘길 수 없음
실시간 프롬프트 누락작업 중 추가한 프롬프트가 누락될 수 있음중요 지시사항 재입력 필요
브랜치 동기화 필요Git 브랜치가 로컬에 없으면 실패fetch 후 재시도 필요
백그라운드 작업 불완전일부 백그라운드 작업이 전송 안 됨수동 재시작 필요

백그라운드 작업 제한사항

제한사항설명해결 방법
세션 종료 시 작업 종료Claude Code 종료 시 백그라운드 작업도 종료Tmux/Screen 사용 권장
출력 버퍼링실시간 스트리밍 아닌 버퍼링된 출력주기적으로 BashOutput 호출
로그 손실 위험장시간 실행 시 초기 로그 손실 가능파일로 로그 리다이렉션

보안 고려사항

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 민감한 정보 제외
# .gitignore에 추가
.claude/secrets/
*.key
*.pem

# 2. API 키 환경 변수 사용
export ANTHROPIC_API_KEY="your-api-key"
# 직접 코드에 입력하지 말 것

# 3. 프록시 설정 시 주의
# HTTPS_PROXY 설정 시 트래픽이 노출될 수 있음

성능 최적화

1
2
3
4
5
6
7
8
9
10
11

# 1. 타임아웃 증가 (긴 작업용)
export MCP_TOOL_TIMEOUT=300000
export BASH_MAX_TIMEOUT_MS=600000

# 2. 컨텍스트 윈도우 관리
# 긴 세션의 경우 주기적으로 /clear
/clear
> "이전 작업 요약: [요약 내용]"

# 3. 체크포인트 활용
# Esc+Esc로 주요 시점에 체크포인트 생성

모범 사례

1. Git을 적극 활용

1
2
3
4
5
6
7
8
9

# Teleport 전후 커밋
git add .
git commit -m "Before teleport - web session work"

claude --teleport session_xyz

# 로컬 작업 후 커밋
git add .
git commit -m "After teleport - local modifications"

2. 문서화 습관

```markdown

AI, Claude Code
AI claude-code Claude.ai Developer Guide Claude.write
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.