asheshgoplani/agent-deck

Agent Deck에 대해 AI에게 물어보세요

옵션 1: Claude Code Skill (Claude Code 사용자에게 권장)

/plugin marketplace add asheshgoplani/agent-deck
/plugin install agent-deck@agent-deck-help

그 다음 다음과 같이 질문하세요: "How do I set up MCP pooling?" (MCP 풀링을 어떻게 설정하나요?)

옵션 2: OpenCode (내장된 Claude skill 호환성 보유)

# 스킬 디렉토리 생성
mkdir -p ~/.claude/skills/agent-deck/references
# 스킬 및 참조 파일 다운로드
...

OpenCode는 ~/.claude/skills/에서 스킬을 자동으로 탐색합니다.

.

옵션 3: 모든 LLM (ChatGPT, Claude, Gemini 등)

https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/llms-full.txt 를 읽고
다음 질문에 답하세요: How do I fork a session? (세션을 어떻게 포크하나요?)

agent-deck-overview-web.mp4

0에서 시작하여 여러분이 실행 중인 모든 Claude 세션을 감시하는 Telegram 봇을 만들기까지 단 5분이면 충분합니다.

# 1. @BotFather를 통해 Telegram 봇을 생성하고, @userinfobot에서 토큰과 사용자 ID를 가져옵니다.
# 2. 위저드(wizard)를 실행합니다 — 한 번에 conductor, bridge daemon, heartbeat를 설정합니다.
agent-deck conductor setup work --description "Work fleet"
...

그게 전부입니다. 이제부터 여러분이 실행하는 다른 모든 agent-deck 세션은 일상적인 질문에 답하고, 흥미로운 질문은 여러분의 휴대폰으로 에스컬레이션(escalate)하며, waiting 상태인 워커(worker)가 방치되지 않도록 관리하는 단일 "conductor" 세션에 의해 감독됩니다.

다음에 읽어볼 두 가지 짧은 가이드:

— 5분 요약 가이드, Telegram/Slack/Discord 연결, 주의 사항 (왜 플러그인이 전역적으로 자동 비활성화되는지, 채널 토폴로지, 멀티-conductor 패턴 등). docs/CONDUCTOR-SETUP.md

— 외부 세계(GitHub 이벤트, gmail, ntfy 푸시, 회의)가 conductor를 깨울 수 있도록 "doorbells"를 추가하는 방법. docs/WATCHER-SETUP.md

10개의 프로젝트에서 Claude Code를 실행 중이신가요? 5개의 프로젝트에 OpenCode를 사용 중인가요? 백그라운드 어딘가에 또 다른 에이전트가 있나요?

여러 개의 AI 세션을 관리하는 것은 금방 엉망이 됩니다. 터미널 탭이 너무 많아집니다. 무엇이 실행 중인지, 무엇이 대기 중인지, 무엇이 완료되었는지 추적하기 어렵습니다. 프로젝트를 전환하려면 창을 뒤져야 합니다.

Agent Deck은 여러분의 AI 코딩 에이전트를 위한 미션 컨트롤(mission control)입니다.

하나의 터미널. 모든 에이전트. 완전한 가시성.

한눈에 모든 것을 확인하세요— 모든 에이전트의 실행 중(running), 대기 중(waiting), 또는 유휴(idle) 상태를 즉시 확인 가능
밀리초 단위의 전환— 단 한 번의 키 입력으로 어떤 세션이든 즉시 전환
체계적인 관리— 그룹화, 검색, 알림, 그리고 git worktrees를 통해 모든 것을 관리 가능한 상태로 유지

컨텍스트(context)를 잃지 않고 다양한 접근 방식을 시도해 보세요. 어떤 Claude 대화든 즉시 포크(Fork)할 수 있습니다. 각 포크는 전체 대화 기록을 상속받습니다.

• 빠른 포크를 위해 f를 누르거나, 이름/그룹을 사용자 정의하려면 F를 누르세요. - 필요한 만큼 많은 브랜치(branch)를 탐색할 수 있도록 포크한 내용을 다시 포크할 수도 있습니다.

설정 파일(config files)을 건드리지 않고도 MCP 서버를 연결하세요. 웹 검색이 필요하신가요? 브라우저 자동화가 필요하신가요? 프로젝트별로 또는 전역(globally)으로 토글(toggle)하세요. Agent Deck이 재시작을 자동으로 처리합니다.

• 열기 위해 m을 누르고, 토글하려면 Space, 범위를 순환(cycle scope, LOCAL/GLOBAL)하려면 Tab을 누른 뒤 입력하여 이동하세요. - MCP를 ~/.agent-deck/config.toml에 한 번 정의한 다음, 세션별로 토글하세요 — 설정 참조(Configuration Reference) 확인

관리형 풀(managed pool) 워크플로우를 통해 프로젝트별로 Claude 스킬(skills)을 연결하거나 분리하세요.

• Claude 세션의 스킬 매니저(Skills Manager)를 열려면 s를 누르세요. - 연결/분리를 결정론적(deterministic)으로 유지하기 위해 사용 가능한 목록은 풀 전용(~/.agent-deck/skills/pool)입니다. - 적용 시 프로젝트 상태가 .agent-deck/skills.toml에 기록되며 .claude/skills로 구체화(materializes)됩니다. - 대화 상자 내에서 입력하여 이동(Type-to-jump) 기능이 지원됩니다 (MCP 매니저와 동일한 패턴).

Agent Deck은 그룹별 CLAUDE_CONFIG_DIR 및 env_file 오버라이드(overrides)를 지원합니다. 이는 단일 프로필 내에서 서로 다른 Claude 계정으로 인증해야 하는 그룹들을 호스팅할 때 유용합니다. 예를 들어, 개인 프로필이 ~/.claude-work에 고정된 conductor 그룹을 호스팅하는 동안 다른 그룹들은 ~/.claude에 머물게 할 수 있습니다.

~/.agent-deck/config.toml에 [groups."<name>".claude] 테이블을 추가하여 특정 그룹을 오버라이드할 수 있습니다:

[groups."conductor".claude]
config_dir = "~/.claude-work"
env_file = "~/git/work/.envrc"

조회 우선순위: env > group > profile > global > default. env_file은 claude가 실행되기 전에 tmux 창에 source 됩니다.

(또는 사용자 정의 명령)을 실행하므로, 그 안에 포함된 모든 export 항목이 세션 환경의 일부가 됩니다.

사람이 확인할 수 있는 검증 방법: bash scripts/verify-per-group-claude-config.sh

이 하네스 (harness)는 두 개의 일회성 그룹을 생성하고, 하나는 일반 세션을, 다른 하나는 사용자 정의 명령 세션을 실행한 뒤 통과/실패 (pass/fail) 테이블을 출력합니다.

Conductor는 agent-deck의 일급 객체 (first-class entity)입니다 (agent-deck conductor setup 참조).

각 conductor는 최상위 [conductors.<name>.claude] 블록을 통해 자체적인 Claude config_dir 및 env_file을 가질 수 있습니다:

[conductors.gsd-v154.claude]
config_dir = "~/.claude-work"
env_file = "~/git/work/.envrc"

conductor 이름은 agent-deck conductor setup <name>에 전달한 문자열이며, 이는 세션 제목(conductor-<name>)에 나타나는 이름과 동일합니다.

우선순위 체인 (가장 구체적임 → 가장 일반적임):

1. CLAUDE_CONFIG_DIR 환경 변수
2. [conductors.<name>.claude] (세션이 conductor 세션인 경우, 즉 제목이 conductor-로 시작하는 경우)
3. [groups."<group>".claude] (PR #578)
4. [profiles.<profile>.claude]
5. [claude] (전역 (global))
6. ~/.claude (기본값 (default))

이는 단 하나의 [conductors.gsd-v154.claude] 라인이 [groups."conductor".claude]에 설정을 중복해서 작성해야 할 필요성을 대체함을 의미합니다. conductor 블록은 conductor 그룹을 공유하는 모든 conductor가 아니라, 정확히 해당 conductor에만 범위를 제한합니다.

하위 호환성: 일치하는 [conductors.<name>.claude] 블록이 없는 conductor 그룹 내의 세션들은 v1.5.4 Phase 1–3에서와 마찬가지로 [groups."conductor".claude]를 통해 계속해서 설정을 해석합니다.

Issue #602를 해결합니다.

많은 세션을 실행 중이신가요? 소켓 풀링 (Socket pooling)은 Unix 소켓을 통해 모든 세션 간에 MCP 프로세스를 공유하여, MCP 메모리 사용량을 85-90%까지 줄여줍니다. 연결은 재연결 프록시 (reconnecting proxy)를 통해 MCP 충돌 시 약 3초 내에 자동으로 복구됩니다. config.toml에서 pool_all = true로 설정하여 활성화할 수 있습니다.

/를 눌러 모든 세션에 대해 퍼지 검색 (fuzzy-search)을 수행하세요. ! (실행 중 (running)), @ (대기 중 (waiting)), # (유휴 상태 (idle)), $ (오류 (error)) 기호를 사용하여 상태별로 필터링할 수 있습니다. G를 누르세요.

모든 Claude 대화에 대한 전역 검색 (global search)을 수행합니다.

두 단계의 키 바인딩 (keybindings)을 통해 세션 목록 내에서 커서를 이동할 수 있습니다. 전역 (global) 단계는 이전 버전과 동일하며, Alt+ 단계 (v1.7.60에서 추가됨)는 이동 범위를 현재 그룹으로만 제한합니다. TUI에서 ?를 누르면 앱 내에서 전체 표를 확인할 수 있습니다.

범위 (Scope)	키 (Keys)	기능
전역 (Global, 평면 목록)	j / k 또는 ↓ / ↑	모든 항목을 따라 커서를 아래로 / 위로 이동
전역 (Global)	gg	목록의 맨 위로 점프
전역 (Global)	G	모든 Claude 대화에 대한 전역 검색 (global search) 열기
전역 (Global)	1 – 9	N번째 루트 그룹 헤더 (root group header)로 점프
전역 (Global)	/	모든 세션에 대한 퍼지 검색 (fuzzy search) 열기
그룹 (Group, 현재 그룹만)	Alt+j / Alt+k	현재 그룹 내에서 다음 / 이전 세션으로 이동 (그룹 경계는 건너뜀)
그룹 (Group)	Alt+1 – Alt+9	현재 그룹 내에서 N번째 세션으로 점프
그룹 (Group)	Alt+g / Alt+G	현재 그룹의 첫 번째 / 마지막 세션
그룹 (Group)	Alt+/	현재 그룹의 세션으로 필터링된 퍼지 검색 (fuzzy search) 열기

"현재 그룹"은 커서 위치를 기반으로 도출됩니다: 세션 위에 있을 때는 해당 세션의 그룹, 그룹 헤더 위에 있을 때는 해당 그룹, 윈도우 (window) 위에 있을 때는 부모 세션의 그룹이 됩니다. 그룹 경계에서 Alt+j / Alt+k는 다음 그룹으로 넘어가지 않고 아무 동작도 하지 않습니다 (no-op).

스마트 폴링 (Smart polling)은 모든 에이전트 (agent)가 현재 무엇을 하고 있는지 감지합니다:

상태 (Status)	기호 (Symbol)	의미 (What It Means)
실행 중 (Running)	● 녹색 (green)	에이전트가 활발히 작업 중
대기 중 (Waiting)	◐ 노란색 (yellow)	사용자의 입력이 필요함
유휴 상태 (Idle)	○ 회색 (gray)	명령을 받을 준비가 됨
오류 (Error)	✕ 빨간색 (red)	문제가 발생함

대기 중 (Waiting)인 세션은 tmux 상태 표시줄에 바로 나타납니다. Ctrl+b를 누른 후 떼고, 1 – 6을 누르면 해당 세션으로 직접 점프할 수 있습니다.

⚡ [1] frontend [2] api [3] backend

여러 에이전트가 충돌 없이 동일한 리포지토리 (repo)에서 작업할 수 있습니다. 각 워크트리 (worktree)는 자체 브랜치 (branch)를 가진 격리된 작업 디렉토리 (working directory)입니다.

agent-deck add . -c claude --worktree feature/a --new-branch

새로운 worktree (worktree)에 세션을 생성합니다.

agent-deck add . --worktree feature/b -b --location subdirectory

worktree를 .worktrees/ 아래에 배치합니다.

저장소(repo) 내부

agent-deck worktree finish "My Session"

브랜치를 병합하고, worktree를 제거하며, 세션을 삭제합니다.

agent-deck worktree cleanup

고아(orphaned) worktree를 찾아 제거합니다.

~/.agent-deck/config.toml에서 기본 worktree 위치를 설정합니다:

[worktree]
default_location = "subdirectory" # "sibling" (기본값), "subdirectory", 또는 사용자 정의 경로

sibling은 저장소 옆에 worktree를 생성합니다 (repo-branch). subdirectory는 저장소 내부에 생성합니다 (repo/.worktrees/branch). ~/worktrees 또는 /tmp/worktrees와 같은 사용자 정의 경로는 <path>/<repo_name>/<branch> 형식으로 저장소 네임스페이스가 지정된 worktree를 생성합니다. --location 플래그는 세션별로 설정을 재정의(override)합니다.

Gitignore 처리된 파일들 (.env, .mcp.json 등)은 기본적으로 새로운 worktree로 복사되지 않습니다. 어떤 gitignore 파일들을 자동으로 복사할지 선언하려면, 저장소 루트에 .worktreeinclude 파일을 생성하세요:

# .worktreeinclude — gitignore 구문 패턴
.env
.env.local
...

패턴에 매칭되면서 동시에 gitignore 처리된 파일만 복사됩니다. 추적 중인(tracked) 파일은 절대 중복 생성되지 않습니다. 디렉토리는 재귀적으로 복사되어 기존 대상 위치에 병합됩니다. worktree 내의 기존 파일은 덮어쓰여지지 않습니다.

이는 단일 저장소(single-repo) 및 다중 저장소(multi-repo) worktree 세션 모두에서 작동합니다. Claude Code Desktop의 의미론(semantics)과 일치합니다.

명령형 설정 작업(의존성 설치, 마이그레이션 실행 등)을 위해 .agent-deck/worktree-setup.sh에 스크립트를 생성하세요. Agent-deck은 worktree를 생성하고 .worktreeinclude를 처리한 후 이 스크립트를 자동으로 실행합니다.

#!/bin/sh
npm install

스크립트는 두 개의 환경 변수를 전달받습니다:

AGENT_DECK_REPO_ROOT — 메인 저장소로의 경로
AGENT_DECK_WORKTREE_PATH — 새로운 worktree로의 경로

스크립트는 sh -e를 통해 실행됩니다.

60초의 타임아웃 (timeout)과 함께 실행됩니다. 만약 실패하더라도 worktree는 여전히 생성됩니다. 경고 메시지가 표시되지만 세션은 정상적으로 진행됩니다.

Agent-deck은 모든 worktree가 동등한 위치에 있는 (즉, "main" 체크아웃이 없는) 두 가지 방식의 bare-repo 레이아웃을 지원합니다. 이 두 방식은 관례에 따라, 즉 bare git 디렉토리의 basename으로 구분됩니다.

bare git 메타데이터가 일반적인 프로젝트 디렉토리 내부의 .bare/에 위치하는 경우:

:

project/
├── .bare/ # bare git repo (refs, objects, HEAD를 보유)
├── .agent-deck/
...

단순한 git clone --bare repo.git의 결과:
: 디렉토리 자체가 bare repo이며, 연결된 worktrees는 내부 파일들과 함께 직접적인 자식으로 존재합니다:

project.git/ # 이 디렉토리가 바로 bare repo임
├── HEAD, config, objects/, refs/, packed-refs, worktrees/, ...
├── .agent-deck/
...

agent-deck이 이러한 레이아웃을 해결(resolve)하는 방식 (중첩된 레이아웃은 v1.7.58+, 루트 위치 레이아웃은 v1.9.10+부터 지원):

세 가지 방식 모두 작동합니다. agent-deck add <project-root>, agent-deck add <bare-dir>, 그리고 agent-deck add <linked-worktree>는 모두 동일한 프로젝트 루트로 해결됩니다. 중첩된(nested) 레이아웃의 경우 .bare/를 보유하고 있는 디렉토리가 루트가 됩니다. 루트 위치(at-root) 레이아ayout의 경우 bare 디렉토리 자체가 루트가 됩니다 (project.git/). 모든 연결된 worktree는 동등하게 취급됩니다.

프로젝트 루트는 공유 설정(shared config)이 저장되는 곳입니다.
.agent-deck/worktree-setup.sh 파일을 <projectRoot>/.agent-deck/worktree-setup.sh 위치에 배치하세요. Agent-deck은 정확히 해당 경로에서 이 파일을 찾으며, 개별 worktree를 검색하지 않습니다. 루트 위치 레이아웃의 경우, 이는 .agent-deck/이 HEAD 및 objects/와 함께 bare 디렉토리 내부에 존재함을 의미합니다. 위와 동일하게, 루트 위치 레이아웃에서는 bare 디렉토리 자체가 해당 위치가 됩니다. 설정 스크립트 내부의 AGENT_DECK_REPO_ROOT는 프로젝트 루트를 가리킵니다.

새로운 worktree 위치는 레이아웃에 따라 달라집니다:
중첩된(Nested) 레이아웃: 사용자의 [worktree] 설정 설정을 따릅니다. default_location = "subdirectory"로 설정하면 worktree는 <projectRoot>/.worktrees/<branch>에 위치하게 되며, "sibling"으로 설정하면 프로젝트 디렉토리 옆에 위치하게 됩니다.
루트 위치(At-root) 레이아웃: sibling 또는 subdirectory 설정을 자동으로 재정의(override)합니다.

그리고 새로운 워크트리(worktree)를 베어 디렉터리(bare dir)의 직계 자식으로 생성합니다 (<bareDir>/<branch>). 프로젝트 루트 자체가 베어 리포지토리(bare repo)인 경우에는 그 어떤 기본 설정도 적절하지 않습니다. 완전히 커스텀된 경로를 원한다면 path_template 설정이 여전히 우선 적용됩니다.

예시 — 어디에서든 베어 리포지토리를 대상으로 새로운 워크트리 생성:

# 중첩된 .bare/ 레이아웃
agent-deck add project/ -c claude --worktree feature/c --new-branch
agent-deck add project/.bare -c claude --worktree feature/c --new-branch
...

agent-deck worktree list와 agent-deck worktree finish 명령어를 통해 해당 위치 중 어디에서나 작업할 수 있습니다.

흔히 발생하는 실수(Common gotchas):

.agent-deck/와 나란히 있는 중첩된 레이아웃의 경우 .bare/는 반드시 프로젝트 루트에 위치해야 합니다. 루트 위치(at-root) 레이아웃의 경우 .bare/는 베어 디렉터리 내부에 위치해야 합니다. 만약 .agent-deck/를 커밋한다면