Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 03. 15:44

단일 터미널에서 모든 Claude Code 세션을 관리하는 방법

요약

여러 개의 Claude Code 세션을 효율적으로 관리하기 위해 개발된 TUI 데몬 'Gatekeeper'를 소개합니다. 모든 도구 호출을 하나의 통합 대시보드로 라우팅하여 승인 프로세스를 간소화하고 컨텍스트 유지를 돕습니다.

핵심 포인트

  • Gatekeeper를 통한 통합 승인 대시보드 구축
  • Unix 소켓 기반의 PreToolUse 훅 활용
  • Bash, Edit, Write 등 도구 호출의 중앙 집중식 관리
  • 패턴 기반의 '항상 허용' 규칙 설정 기능

저는 하루 종일 여러 개의 Claude Code 세션을 실행합니다. 기능 하나당 하나, 서비스 하나당 하나, 때로는 한 번에 다섯 개까지 실행하기도 합니다.

이전에는 모든 세션이 각자의 터미널에서 저에게 권한을 요청했습니다. 백그라운드 탭에 파묻힌 요청을 놓치기도 했고, 단순히 git status를 승인하기 위해 생각의 흐름을 끊으며 창을 전환해야 했습니다. 끊임없이 컨텍스트 (Context)를 놓치곤 했습니다.

또한, 모든 세션에서 Claude가 무엇을 하고 있는지 한곳에서 확인할 수 있는 방법도 없었습니다.

그래서 저는 Gatekeeper를 만들었습니다. 이는 모든 Claude Code 도구 호출 (Tool call)을 가로채서 하나의 통합된 승인 대시보드로 라우팅하는 TUI 데몬 (Daemon)입니다.

대시보드

세 개의 창, 하나의 터미널:

  • 왼쪽 (Left) — 모든 활성 Claude 세션과 상태 배지 표시: [auto]는 자동 승인 (Auto-approve)이 켜져 있음을 의미하며, [linked]는 터미널 창에 연결되어 있음을 의미합니다.
  • 중간 (Middle) — 대기 중인 권한 요청과 함께, 무엇이 가장 오래 기다리고 있는지 알 수 있도록 경과 시간 타이머를 표시합니다.
  • 오른쪽 (Right) — 전체 요청 상세 정보, 위험 경고, 그리고 번호가 매겨진 승인 메뉴를 표시합니다.

모든 Claude Code 도구 호출 — Bash, Edit, Write, Agent — 은 실행되기 전에 PreToolUse 훅 (Hook)을 통과합니다. 이 훅은 Gatekeeper의 Unix 소켓 (Unix socket)에 연결하여 요청을 보내고 실행을 차단합니다. Gatekeeper는 이를 UI에 표시합니다. 사용자가 결정을 내리면 답변이 다시 전달되어 Claude가 진행하거나 중단합니다.

요청 승인하기

오른쪽 창의 메뉴는 Claude Code 자체의 스타일을 반영합니다:

1  Allow once (한 번 허용)
2  Always allow (항상 허용)
3  Deny (거부)

↑/↓로 커서를 이동하고 Enter로 확인합니다. 또는 1, 2, 3을 직접 누를 수도 있습니다. A와 D는 허용/거부를 위한 빠른 단축키입니다.

옵션 2 — 항상 허용 (Always allow) — 이 기능이 매우 유용합니다. 이 옵션을 선택하면 지속적인 규칙이 저장되어 동일한 요청이 다시 나타나지 않습니다:

  • Bash → 명령 패턴(예: npm run *)을 설정 (Config)에 저장합니다.
  • Edit / Write → 해당 디렉토리를 허용 목록 (Allowlist)에 저장합니다.
  • Agent → 해당 세션에 대해 자동 승인 (Auto-approve)을 활성화합니다.

이 규칙은 Gatekeeper 자체의 설정뿐만 아니라 Claude Code의 settings.json 허용 목록에도 기록됩니다. 따라서 Claude Code 자체에서도 더 이상 프롬프트(Prompt)가 뜨지 않게 됩니다.

자동 승인 세션

Sessions 창에서 A를 누르면 해당 세션을 신뢰할 수 있는 세션으로 표시합니다. 그러면 [auto]라고 표시되며, 일상적인 도구 호출(Tool calls)은 대기열에 나타나지 않고 조용히 통과됩니다.

하지만 어떤 상황에서도 항상 수동 승인이 필요한 항목들이 있습니다:

카테고리차단되는 항목
파일 삭제rm, rmdir, shred
...

읽기 전용 명령(Read-only commands)인 grep, find, ls, cat, git status, npm install 등은 항상 자유롭게 통과됩니다.

세션을 터미널에 연결하기 (Linking sessions to terminals)

이 기능은 다른 모든 기능의 잠금을 해제하는 핵심입니다.

Sessions 창의 아무 세션에서나 L을 누르세요. 오버레이가 나타나면 Claude 터미널 탭으로 전환하십시오 (alt+tab, 클릭 등 무엇이든 상관없습니다). 그러면 Gatekeeper가 포커스 변경을 감지하고 해당 세션을 해당 창에 자동으로 연결합니다. 세션에는 [linked]라고 표시됩니다.

연결 정보는 ~/.claude/perm-window-map.json에 저장되어 재시작 후에도 유지됩니다. 한 번 연결하면 계속 유지됩니다.

Gatekeeper에서 메시지 보내기

세션이 연결되면 M을 누르고, 메시지를 입력한 뒤 Enter를 누르세요.

Gatekeeper는 X11 XTEST를 사용하여 연결된 Claude 터미널에 텍스트를 주입(Inject)합니다. 이는 마치 사용자가 직접 타이핑하고 Enter를 누른 것처럼 텍스트가 나타남과 동시에 자동으로 제출됩니다. 사용자는 Gatekeeper 터미널을 떠날 필요가 없습니다.

이는 제가 직접 만들기 전까지는 몰랐던 문제를 해결해 줍니다. Claude가 작업 중간에 멈춰서 A / B / C?와 같이 명확한 질문을 던지는 경우입니다. 보통은 해당 터미널로 전환하여 답변하고 다시 돌아와야 합니다. 하지만 Gatekeeper를 사용하면 어디에 있든 그냥 M을 누르고 타이핑하면 됩니다.

다음과 같은 상황에서 유용합니다:

  • 창을 전환하지 않고 Claude의 작업 중간 질문에 답변하기
  • 요청을 거부한 이유 설명하기
  • Claude가 대기하는 동안 다른 접근 방식으로 유도하기

주의 사항: 주입(Injection) 기능은 각 Claude 세션이 별도의 터미널 **창(Window)**에 있을 때 작동합니다. 만약 여러 세션이 하나의 창 내에서 탭(Tab) 형태로 공유된다면, 동일한 X11 윈도우 ID를 공유하게 되어 Gatekeeper가 특정 탭을 타겟팅할 수 없습니다. 각 세션을 새 창(kitty, gnome-terminal --window 등)에서 실행하십시오.

설정 (Settings)

S를 눌러 설정 패널을 엽니다. 여기에서 다음 항목들을 구성할 수 있습니다:

  • Tool types (도구 유형) — Gatekeeper가 가로채는 도구들 (Bash, Edit, Write, Agent)
  • Bash categories (Bash 카테고리) — 명령어가 분류되는 방식 (읽기 전용 vs 파괴적 vs 네트워크 등)
  • Custom patterns (사용자 정의 패턴) — 기본 설정을 넘어선 사용자만의 허용/거부 규칙

설정 파일을 일일이 뒤져볼 필요가 없습니다. 모든 것은 대시보드 내부에서 편집할 수 있습니다.

통계 (Stats)

gatekeeper stats        # 오늘
gatekeeper stats 7      # 최근 7일
gatekeeper stats all    # 전체 기간

====================================================
 GATEKEEPER STATS
====================================================
...

모든 결정은 ~/.claude/perm-logs/YYYY-MM-DD.log에 기록되며, 하루에 파일 하나씩 생성되어 무기한 보관됩니다. 긴 세션이나 프로젝트 전체에 걸쳐 Claude가 무엇을 수행했는지 감사(Auditing)하는 데 유용합니다.

Gatekeeper가 실행 중이지 않을 때 발생하는 일

훅(Hook)은 Claude 터미널 내의 Y/n 프롬프트로 대체되며, 30초 후 자동 거부(Auto-deny)됩니다. 아무것도 멈춰 있거나 조용히 통과되지 않습니다. 또한 특정 세션에서 항상 터미널 프롬프트를 사용하려면 GATEKEEPER_TIMEOUT=0으로 설정할 수 있습니다.

연결 방식 (How it's wired up)

install.sh는 다음 네 가지 작업을 수행합니다:

  1. ~/.claude/bin/에 래퍼 스크립트(Wrapper scripts)를 설치합니다.
  2. ~/.claude/settings.json에 PreToolUse 훅을 등록합니다.
  3. Claude Code가 중복 프롬프트를 띄우지 않도록 포괄적인 permissions.allow 규칙을 추가합니다.
  4. permissions.defaultMode = "bypassPermissions"를 설정합니다 — 이는 Claude Code의 내장 대화창을 완전히 비활성화하여, Gatekeeper를 유일한 승인 게이트로 만듭니다.

마지막 항목이 중요합니다: 민감한 경로(/proc/, /sys/, ~/.bashrc)에 대해 Claude Code에 하드코딩된 자체 프롬프트는 bypassPermissions 모드에서 억제됩니다. 대신 Gatekeeper가 모든 것을 처리합니다.

설치 (Installation)

git clone https://github.com/Btocode/gatekeeper
cd gatekeeper
python3 -m venv .venv && source .venv/bin/activate
...

그 다음 전용 터미널을 열고 다음을 실행하십시오:

gatekeeper

다른 터미널, VS Code, JetBrains 등 어디에서든 Claude Code 세션을 시작하십시오. 모든 도구 호출(Tool call)이 Gatekeeper에 나타날 것입니다.

요구 사항: Linux + X11 + Python 3.11+

제작 이유

저는 서브시스템 하나당 하나의 세션을 할당하여, 총 5개의 Claude 세션을 병렬로 실행하며 프로젝트를 진행하고 있었습니다. 각 세션은 뛰어난 능력을 갖추고 있었지만, 제가 병목 현상(bottleneck)이었습니다. 한 시간 동안 다섯 번째로 npm run build를 승인하기 위해 끊임없이 창을 전환해야 했기 때문입니다.

Gatekeeper가 이 문제를 해결했습니다. 신뢰할 수 있는 세션(Trusted sessions)은 저를 방해하지 않고 일상적인 호출(calls)을 처리합니다. 새롭거나 위험한 요소는 대시보드에 나타납니다. 저는 메인 터미널을 떠나지 않고도 Claude의 질문에 답변할 수 있습니다. 그리고 하루가 끝날 때, gatekeeper stats 명령어가 정확히 어떤 일이 일어났는지 알려줍니다.

이 프로젝트는 오픈 소스이며, MIT 라이선스를 따릅니다.

👉 github.com/Btocode/gatekeeper

여러 세션으로 Claude Code를 실행 중이라면, 한 번 사용해 보세요. 그리고 만약 여러분도 이와 같은 도구를 개발하고 있다면, 저를 팔로우해 주세요. 더 많은 콘텐츠가 곧 공개될 예정입니다.

태그: claudecode ai devtools opensource

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0