tabby-agentdeck 1.1.3 → 1.2.1

package/README.ko.md

@@ -1,590 +1,52 @@
-# tabby-agentdeck
-
-[![npm](https://img.shields.io/npm/v/tabby-agentdeck)](https://www.npmjs.com/package/tabby-agentdeck)
-[![downloads](https://img.shields.io/npm/dm/tabby-agentdeck)](https://www.npmjs.com/package/tabby-agentdeck)
-[![CI](https://github.com/jghwang2/tabby-agentdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/jghwang2/tabby-agentdeck/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/tabby-agentdeck)](LICENSE)
-
-**[홈](https://jghwang2.github.io/tabby-agentdeck/ko.html) · [사용 설명서](https://jghwang2.github.io/tabby-agentdeck/guide/ko.html) · [English README](README.md) · [문제 신고](https://github.com/jghwang2/tabby-agentdeck/issues/new/choose)**
-
-## 1.1.3
-
-- Codex 상태 통보 훅과 세션 재개·분기 처리를 개선했다.
-- Windows에서 Codex 커서 표시, Shift+Enter 줄바꿈, 마우스 휠로 대화 기록 보기를 보정했다.
-- 하위 프로세스가 콘솔 제목을 바꾸어도 Codex 감지를 유지하고, 현재 입력창·상태줄과 프로세스 확인으로 감지를 복구한다.
-- 기존 테스트와 Codex 회귀 테스트를 함께 실행한다. GitHub Actions 배포 설정은 [npm 배포 안내](docs/NPM-PUBLISH.md)를 참고한다.
-
-Tabby 터미널 플러그인. **Claude Code · Codex 같은 AI 에이전트 CLI 를 여러 탭에 띄워 놓고 쓰는 사람**을 위한 것이다.
-
-터미널 뷰포트를 **4:3 으로 고정**하고 남는 공간에 **세션 목록 + 작업 상태 사이드바**를 그린다.
-어느 에이전트가 돌고 있고 어느 쪽이 내 입력을 기다리는지 탭을 옮겨 다니지 않고 한눈에 본다.
-에이전트가 만든 문서·그림은 **미리보기 패널**에서 터미널 옆에 띄워 확인한다.
-거기에 에이전트 CLI 가 터미널에서 겪는 문제들(이미지 붙여넣기, 줄바꿈 키, pty 폭 어긋남)을 같이 손봐 둔다.
-
-```
-┌────────────────────┬──────────────────┬──────────────────┐
-│                    │ note.md   ＋ ⟳ ✕ │ AGENT DECK    4  │
-│  터미널 (4:3 기준)   ├──────────────────┼──────────────────┤
-│                    │ note.md  shot.png│ ● 진행중  리팩터링 │
-│  Tabby 순정 탭바는   ├──────────────────┤ ⏸ 승인대기 재빌드 │
-│  숨김               │ # 제목            │ ✔ 완료   테스트   │
-│                    │ 본문이 그려진다     │ ○ 대기            │
-│                    │ [그림]            ├──────────────────┤
-│                    │ 742 B · 방금      │ + 새 탭 │ 설정    │
-└────────────────────┴──────────────────┴──────────────────┘
-      터미널              미리보기 패널        세션 목록
-```
-
-Windows 에서 만들고 검증했다. 상태 통보 훅은 PowerShell 스크립트라 Windows 전용이고, 그 외 기능은 플랫폼을 가리지 않는다.
-
-## 기능
-
-| | 동작 |
-|---|---|
-| **4:3 기준 폭 계산** | 창 높이에서 폭을 역산해 터미널을 고정폭으로 만든다. 남는 폭은 사이드바가 갖고, 그러고도 남으면 터미널이 흡수한다 |
-| **사이드바 탭 관리** | 클릭=선택, `×`=닫기, 더블클릭=작업 이름 편집, 우클릭=상태 직접 지정 |
-| **검색 · 상태 필터** | 헤더 아래 검색창으로 제목·작업이름·작업폴더를 좁히고, 상태 칩을 눌러 그 상태만 본다. Esc 로 해제 |
-| **순서 바꾸기** | 사이드바 줄을 끌어 옮긴다(순정 탭바 순서도 함께). 목록 끝에 커서를 대고 있으면 **저절로 흘러가** 화면 밖 자리로도 한 손짓에 옮긴다. 상태순 정렬이 켜져 있으면 막고 이유를 알린다 |
-| **키보드로 다루기** | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓` 로 훑고 Enter 로 고른다. **훑는 동안 탭은 바뀌지 않는다** — 지나가는 탭의 출력이 화면을 채우지 않게 포커스와 선택을 갈랐다. `Ctrl+W` 로 지금 탭(목록에서는 포커스 줄)을 닫는다 |
-| **결과물 미리보기** | 에이전트가 만진 md · 이미지 · 표(csv/tsv) · 코드를 터미널 옆 패널에서 본다. 화면에 찍힌 경로를 스스로 주우므로 Claude Code · Codex · Gemini 를 가리지 않는다 |
-| **끌어다 놓기** | 파일을 패널에 놓으면 바로 열리고, **터미널 위에 놓으면** `패널에 띄우기` / `경로 붙여넣기` 를 물어본다 |
-| **변경 보기** | 같은 패널의 `변경` 탭이 작업트리의 `git diff` 를 보여준다 — 파일 목록 · `+N -M` · 줄번호 붙은 유니파이드 diff. 누가 고쳤는지와 무관하게 성립한다 |
-| **`파일:라인` 참조** | diff 나 코드 보기에서 줄을 누르면 그 위치를 터미널에 넣는다(Shift+클릭=범위). "이 줄 고쳐" 를 타이핑 없이 |
-| **스테이지 · 커밋** | `변경` 탭에서 파일 딱지를 눌러 `git add`/`unstage` 하고, 메시지를 적어 커밋한다. **두 번 눌러야 커밋된다**(첫 누름은 확인 대기) |
-| **세션 그룹** | 탭을 프로젝트별로 묶고 접는다. 경계는 저장소 루트(`.git` 등)를 위로 훑어 자동으로 잡으므로 설정이 없다. 그룹이 하나뿐이면 헤더를 그리지 않고 순서도 건드리지 않는다 |
-| **지난 세션 이어받기** | 그룹 안 `⟲ 지난 세션` 을 펴면 **닫힌 Claude Code 세션**이 사람이 친 프롬프트로 보인다. 누르면 그 세션의 작업 폴더에서 `claude --resume` 으로 대화가 되살아난다 |
-| **한글 조합 보정** | 조합 중인 음절이 커서를 따라가거나 새 줄로 내려가지 않게, pty 에 쓰기 전에 조합이 끝나기를 기다린다 |
-| **에이전트 프로필** | 어느 CLI 가 도는 탭인지 알아내고(프로세스 → 제목) 그에 맞는 규칙을 쓴다. 새 CLI 지원은 프로필 한 덩이 추가로 끝난다 |
-| **마우스 도킹** | 헤더를 끌어 좌/우/상/하 어느 가장자리에나 붙이고, 경계선을 끌어 크기를 바꾼다 |
-| **작업 상태** | 진행중 / 승인대기 / 한도 도달 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시. 훅이 없어도 화면 문구로 판정하고, **왜 멈췄는지**(승인 대상·한도)를 배지에 붙인다 |
-| **상태별 집계** | 헤더 오른쪽에 상태별 탭 수를 `⏸ 2 ● 3 ○ 1` 처럼 급한 순서(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 보여준다. `sortByStatus` 를 켜면 같은 순서로 탭이 정렬된다 |
-| **서브에이전트 개수** | 그 세션이 백그라운드 에이전트를 몇 개 돌리고 있는지 줄에 `❖3` 으로 보인다. 대화 기록에서 **띄운 것과 끝난 것을 대조**해 세므로 훅이 알려주지 않아도 맞는다 |
-| **작업 이름** | Enter 로 프롬프트를 보내는 순간 입력창 원문을 읽어 라벨로 삼는다 |
-| **Claude Code 훅 연동** | 설정 창에서 한 번 설치하면 에이전트가 상태를 직접 알려준다 (선택) |
-| **기본 프로필** | 새 탭을 항상 지정한 작업 루트에서 연다 |
-| **자동 업데이트** | 기동할 때 npm 을 보고 새 버전이 있으면 물어본 뒤, Tabby 를 닫고 → 설치하고 → **스스로 다시 켠다**. 개발 설치(소스 링크)에는 손대지 않는다 |
-| **입력 보정** | `Ctrl+V` 이미지 붙여넣기, `Ctrl+Enter`/`Shift+Enter` 줄바꿈, 우클릭 복사/붙여넣기 |
-| **화면 복구** | 깨진 TUI 의 **입력창 잔상만** 지우고 크기를 맞춰 다시 그리게 한다 — 보고 있던 대화는 건드리지 않는다. 사이드바 `↻` / 탭 우클릭 / `agentdeck-repair` 핫키 |
-
-## 설치
-
-**Tabby 안에서**: 설정 → 플러그인 → `agentdeck` 검색 → 설치 → Tabby 재시작.
-
-**소스에서**:
-
-```powershell
-npm install
-npm run build
-powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1
-```
-
-`install.ps1` 은 Tabby 플러그인 디렉토리(`%APPDATA%\tabby\plugins\node_modules\tabby-agentdeck`)에
-이 폴더를 가리키는 junction 을 건다. 소스를 고치고 `npm run build` 하면 Tabby 재시작으로 반영된다.
-
-### 자동 업데이트
-
-기동하고 8초 뒤, npm 레지스트리에 `tabby-agentdeck` 의 최신 버전을 묻는다.
-새 버전이 있으면 **물어본다** — `지금 업데이트` / `나중에` / `다시 묻지 않기`.
-승낙하면 이렇게 흐른다:
-
-```
-Tabby 가 닫힌다  →  (밖에서) npm install  →  Tabby 가 스스로 다시 켜진다
-```
-
-**사람이 할 일은 처음 한 번 누르는 것뿐이다.** 설치가 끝나면 알아서 다시 켜진다.
-설치가 실패해도 Tabby 는 반드시 다시 켠다 — 업데이트를 고르느라 터미널을 잃는 일은 없어야 한다.
-기록은 `%LOCALAPPDATA%\tabby-agentdeck\update.log` 에 남는다.
-
-| 설정 | 기본값 | |
-|---|---|---|
-| `autoUpdate` | `true` | 끄면 확인도 하지 않는다 |
-| `updateCheckIntervalHours` | `6` | 기동마다 묻지 않는다 |
-| `updateRegistry` | `https://registry.npmjs.org` | 사내 미러를 쓰면 바꾼다 |
-| `updateSkipVersion` | — | `다시 묻지 않기` 를 누른 버전. **그 버전만** 건너뛰고 다음 버전은 다시 묻는다 |
-
-> **왜 Tabby 를 닫고 까나.** 두 가지 때문이다. ① 돌고 있는 플러그인은 자기를 갈아끼울 수 없다 —
-> Tabby 는 기동할 때 `dist/index.js` 를 한 번 읽어 메모리에 올리므로, 디스크를 바꿔도 돌던 코드는
-> 옛것 그대로다. ② Windows 는 로드된 파일을 잡고 있어서, 떠 있는 동안 npm 이 그 폴더를 지우려 들면
-> 반쯤 지운 채 실패할 수 있다 — 플러그인이 깨진 채 남는 것이 가장 나쁜 결과다.
-> 그래서 설치는 임시 폴더로 떼어낸 `updater/agentdeck-update.ps1` 이 **Tabby 종료를 확인한 뒤** 한다.
-> 기다리는 대상은 **업데이트를 건 그 인스턴스의 메인 프로세스 PID** 하나다 — 이름으로 전부 세면
-> 다른 Tabby 창 하나 때문에 업데이트가 영영 안 된다.
-
-> **개발 설치에는 설치하지 않는다.** 플러그인 폴더의 `tabby-agentdeck` 이 소스 트리를 가리키는
-> 링크일 때(`install.ps1` 로 깐 개발 환경), 거기에 `npm install` 이 돌면 **작업 중인 소스를 덮어쓴다.**
-> `src/`·`.git`·`webpack.config.js` 중 하나라도 보이거나 항목이 링크면 새 버전이 있다는 것만 알리고
-> 손대지 않는다 (판정은 `update.ts` 의 `canSelfUpdate`).
-
-### 버전은 한 곳에만 적는다
-
-**`package.json` 의 `version` 이 유일한 출처다.** 나머지는 전부 거기서 파생된다 —
-`npm run build` 가 매번 `tools/sync-version.js` 를 먼저 돌려(`prebuild`) `package-lock.json` 과
-사용설명서(`docs/guide/index.html` 의 `<span class="ad-version">`)를 맞추고,
-진단 로그의 `plugin=` 은 런타임에 `package.json` 을 읽는다(`diag.ts` `pluginVersion`).
-
-```powershell
-npm run sync-version              # 지금 맞추기
-node tools/sync-version.js --check  # 어긋난 곳만 알리기 (어긋나면 종료코드 1)
-```
-
-`test/version.test.js` 가 어긋남을 잡으므로 빌드를 안 거친 수정도 `npm test` 에서 걸린다.
-
-### 릴리스는 한 명령으로
-
-```powershell
-npm run release -- 1.1.3        # 또는 patch | minor | major
-npm run release -- 1.1.3 --dry-run
-npm publish
-```
-
-순서가 정해져 있다 — **버전을 박고 → 파생시키고 → 재고 → 커밋하고 → 태그를 단다.**
-테스트나 빌드가 깨지면 버전 변경을 되돌리고 멈춘다(반쯤 올라간 버전이 작업트리에 남지 않게).
-막는 것 셋: 같은 버전, 이미 있는 태그, **커밋 안 된 변경**(릴리스 커밋은 버전 변경만 담아야
-태그가 무엇을 가리키는지 흐려지지 않는다).
-
-태그는 `vX.Y.Z` 이고 그 버전을 **처음 들여온 커밋**을 가리킨다. `test/tags.test.js` 가
-① 태그 이름과 그 커밋의 버전이 같은지 ② 커밋된 버전에 태그가 빠지지 않았는지를 전수로 잰다.
-
-> **왜 `npm version` 을 안 쓰나.** 그쪽은 자기 방식으로 커밋·태그를 만들고 우리 파생 파일
-> (`docs/guide/index.html`)은 모른다. 맞추고 → 재고 → 커밋하는 순서를 우리가 쥐어야 한다.
-
-> 이 절차가 생긴 이유: 태그가 `v0.2.1` 에서 멈춘 채 버전 커밋만 20개 넘게 쌓여 있었다
-> (2026-09-11 `v0.1.0`~`v1.1.2` 23개 소급 등록). 버전 네 곳이 전부 달랐던 것과 같은 종류의
-> 드리프트이고, 원인도 같다 — 사람이 릴리스 때 여러 곳을 기억해서 고치는 방식.
-**문서·주석의 `0.18.0 부터 …` 같은 이력 표기는 대상이 아니다** — 그건 "지금 버전" 이 아니라
-그 기능이 들어온 시점이라 갱신하면 오히려 거짓이 된다.
-
-> 이 규칙이 생긴 이유: 2026-09-11 에 같은 버전을 네 곳이 각자 적고 있었고 **전부 달랐다**
-> (`package.json` 1.0.0 / `package-lock.json` 0.3.0 / 사용설명서 0.17.0 / 커밋된 값 0.17.0).
-
-## 작업 이름과 상태
-
-사이드바 한 줄은 **작업 이름(라벨)** 과 **상태 배지** 로 이루어진다.
-둘 다 **설정 없이 플러그인만으로 돈다.** 더 정확하게 하려면 Claude Code 훅을 건다.
-
-### 작업 이름
-
-Enter 로 프롬프트를 보내는 그 순간, 화면에 그려져 있는 입력창(`❯ ...`, `> ...`)을 읽어 40자로 잘라 라벨에 넣는다.
-붙여넣기·↑ 히스토리·IME 로 들어온 글자도 화면에 그려진 대로 잡힌다.
-Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력창 머리를 못 찾으면(일반 셸, y/n 확인 등) 라벨을 그대로 둔다.
-
-### 상태
-
-- **자동 감지(기본)**: PTY 출력이 흐르면 `진행중`, `idleAfterMs`(기본 2.5초) 동안 조용하면 `대기`.
-  `Do you want to`, `❯ 1. Yes`, `(y/n)` 같은 패턴이 보이면 `승인대기`. Claude Code 가 제목에 넣는 스피너도 진행중으로 읽는다.
-  `승인대기` 인 탭에 `esc to interrupt` 같은 작업 중 문구가 다시 보이면 사람이 승인한 것으로 보고 `진행중` 으로 올린다 —
-  훅이 고정한 탭에도 적용된다 (승인 뒤 첫 훅은 도구가 끝난 뒤라, 긴 빌드를 승인하면 그동안 승인대기에 박혀 있었다).
-- **Claude Code 훅(권장)**: 설정 → AgentDeck → "상태 통보 훅" 설치. `~/.claude/settings.json` 의
-  UserPromptSubmit / Notification / PostToolUse / PostToolUseFailure / PermissionDenied / Stop / StopFailure 에 통보 스크립트를 건다.
-  다른 훅은 건드리지 않고 쓰기 전에 백업을 남긴다. 0.3.0 에서 이벤트가 늘었으므로 옛 설치는 "설치 안 됨" 으로 보인다 — 설치를 다시 누르면 된다.
-  에이전트가 "지시를 받았다 / 승인을 기다린다 / 도구가 돌았다(=승인됐다) / 끝났다 / 실패로 끝났다" 를 직접 알려주므로 판정이 흔들리지 않는다. 설정 창의 "제거" 로 되돌린다.
-  승인대기에는 이유(예: `Bash 권한`, `입력 대기`)가 함께 표시된다 — `⏸ 승인대기 · Bash 권한`. 상태가 바뀌면 이유는 사라진다.
-- **한도 도달**: Claude Code 가 사용량 한도(세션/주간)에 걸려 턴이 끊기면 `StopFailure` 훅이 `error: rate_limit` 로 알려주고
-  사이드바는 `⛔ 한도 도달 · 12pm 리셋` 처럼 리셋 시각과 함께 보여준다. 승인할 것이 없는 상태라 승인대기와 구분한다.
-  한도 외의 실패(overloaded, server_error …)는 `✖ 오류 · overloaded` 로 표시된다. 한도가 풀려 세션이 이어지면(다음 프롬프트·도구 실행) 진행중으로 돌아온다.
-  훅 보고는 플러그인이 탭 셸에 심은 `AGENTDECK_TAB` 환경변수로 어느 탭인지 확정한다
-  (0.2.2 이전에 열린 탭·재시작으로 복원된 탭은 프로세스 계보로 폴백).
-
-### 어느 에이전트인지 알아내는 법
-
-탭마다 **어떤 CLI 가 도는지** 알아내고(자식 프로세스 이름 → 안 잡히면 탭 제목), 그 에이전트의 규칙을 쓴다.
-지금 아는 것은 Claude Code · Codex CLI · Gemini CLI 셋이고, 새 CLI 는 프로필 한 덩이를 더하면 된다.
-
-프로필이 정하는 것 — 상태 문구(대기·작업중), 제목 스피너, **이미지 붙여넣기 키**(Claude=`ESC v` / Codex=`0x16`),
-입력창 머리글자. 셸만 떠 있는 탭은 `알 수 없음` 이고, 그때는 아는 규칙을 모두 합쳐 판정한다.
-
-> **관측된 값만 좁게 쓴다.** Codex·Gemini 의 화면 문구는 이 리포에서 관측된 바가 없어, 그 두 에이전트는
-> 상태 판정에 합집합(= 예전과 같은 규칙)을 쓴다. 프로필을 붙였다는 이유로 판정이 예전보다 나빠지면
-> 개선이 아니기 때문이다. 실측이 생기면 그 프로필의 `patternsProven` 을 켜면 된다.
-
-### 직접 지정
-
-- 사이드바에서 **우클릭 → 상태 고르기**, **더블클릭 → 이름 편집**.
-- 셸 스크립트 안에서라면 콘솔 제목을 `[AD:<status>] <라벨>` 로 바꾼다. 접두사는 표시에서 지워진다.
-
-  ```powershell
-  $host.UI.RawUI.WindowTitle = "[AD:waiting] 배포 승인 대기"
-  ```
-
-  status 는 `running` / `waiting` / `done` / `error` / `idle`.
-  직접 지정한 상태는 **고정**되어 자동 감지가 덮어쓰지 않는다(배지에 점선 밑줄). 우클릭 → `↺ 자동 감지로` 로 해제한다.
-  이 경로는 셸 안에서 직접 실행할 때만 통한다 — 에이전트 훅에서는 콘솔 제목이 터미널까지 오지 않는다.
-
-### 서브에이전트 몇 개 돌고 있나
-
-Claude Code 가 백그라운드로 에이전트를 띄우면 그 개수가 줄에 `❖3` 으로 붙는다.
-줄에 마우스를 올리면 무엇이 도는지 목록과 가장 오래된 것의 경과가 나온다.
-
-세는 방법은 **그 세션의 대화 기록에서 띄운 것과 끝난 것을 대조**하는 것이다
-(`~/.claude/projects/*/<세션 id>.jsonl`). 훅이 알려 주는 값이 아니라 기록이 근거이므로,
-훅이 상태를 안 보내는 동안에도 개수는 맞는다. 세션과 탭을 잇는 것은 훅이 쓰는 상태 파일이라
-**훅을 설치하지 않으면 이 표시도 나오지 않는다**(`notifyChannel` 이 꺼져 있어도 마찬가지다).
-
-기록 파일은 수십 MB까지 자라므로 **자란 만큼만** 읽는다 — 2초에 한 번 크기만 확인하고,
-커진 경우에만 그 뒤쪽을 읽어 누적한다. 처음 붙는 세션은 한 번 전체를 훑어야 해서
-개수가 몇 초 늦게 나타날 수 있다.
-
-한 가지 알아 둘 것 — 에이전트를 Esc 로 취소하거나 CLI 가 죽으면 **끝났다는 기록이 안 남아**
-개수가 줄지 않을 수 있다. 그걸 시간으로 감추지 않는다(진짜 오래 도는 것을 지우게 된다).
-대신 툴팁의 경과가 계속 늘어나므로 그것으로 알아볼 수 있다.
-
-### 알림
-
-창이 다른 앱 뒤에 가 있을 때(포커스 없음) 어느 탭이 `승인대기` · `오류` · `한도 도달` 로 넘어가면 OS 쪽에 알린다 —
-작업표시줄 아이콘이 깜빡이고(`alertFlash`), 아이콘 위에 그런 탭의 개수가 뱃지로 얹힌다(`alertBadge`).
-뱃지는 상태가 풀리는 대로 실제 개수를 따라가고 0 이면 사라진다. 깜빡임은 창을 다시 앞으로 가져오면 멈춘다.
-OS 토스트(`alertToast`)는 기본으로 꺼져 있다 — 켜면 토스트를 눌러 바로 그 탭으로 갈 수 있다.
-창이 앞에 있을 때는 셋 다 아무 일도 하지 않는다. 사이드바가 이미 보이고 있기 때문이다.
-
-## 지난 세션 이어받기
-
-Tabby 가 꺼져도 **Claude Code 대화는 디스크에 남는다** (`~/.claude/projects/<프로젝트>/<세션id>.jsonl`).
-`claude --resume <세션id>` 로 그대로 이어받을 수 있는데, 실제로 막히는 곳은 명령이 아니라
-**UUID 목록에서 내 작업을 찾는 것**이다.
-
-agentdeck 은 그 답을 이미 갖고 있다 — Enter 를 칠 때 입력창에서 주운 프롬프트 원문.
-그래서 그룹 끝에 서랍을 하나 둔다:
-
-```
-▾ Root                          ⏸1 ●2
-   ● Agent Root      진행중 ❖2
-     시즌패스 보상 지급경로 정리     3분
-   ⟲ 지난 세션  5              ▸        ← 기본 접힘. 누르면 펴진다
-```
-
-편 모습:
-
-```
-   ⟲ 지난 세션  5              ▾
-      백그라운드에서 뭐 돌고있나본데 이거 뭐야
-        완료                        14:12
-      시즌패스 미수령 보상 우편지급 전환
-        한도 도달                     어제
-```
-
-| 조작 | 하는 일 |
-|---|---|
-| 클릭 | **그 세션의 작업 폴더**에서 새 탭을 열고 `claude --resume <세션id>` 를 보낸다 |
-| 우클릭 → `분기해서 이어받기` | `--fork-session`. 원본 기록을 그 시점 그대로 두고 **복사본**에서 이어간다 — 같은 지점에서 다른 방향을 시도할 때만 쓴다 (매번 쓰면 기록이 불어난다) |
-| 우클릭 → `세션 ID 복사` · `목록에서 숨기기` | 목록에서만 감춘다. 기록 파일은 건드리지 않는다 |
-
-알아 둘 것:
-
-- **작업 폴더가 다르면 목록에 없다.** `--resume` 은 cwd 로 세션을 묶으므로 이어받기도 그 폴더에서 연다.
-- **이미 열려 있는 세션**은 `● 열림` 으로 보이고, 누르면 이어받지 않고 그 탭으로 간다 —
-  같은 세션을 두 탭에서 이어받으면 두 프로세스가 한 기록 파일에 덧쓴다.
-- **대화만 돌아온다.** 그때 띄워 둔 로컬 서버나 백그라운드 프로세스는 되살아나지 않는다.
-- 죽은 줄은 색이 아니라 **형태**(점선 바 + 흐림)로 구분한다. 상태 6색은 이미 살아 있는 탭이 쓰고 있어서,
-  일곱 번째 색을 들이면 배지가 뜻하는 바가 흐려진다.
-- 라벨은 두 곳에서 온다 — 살아 있을 때 주운 프롬프트(원장, `%LOCALAPPDATA%\tabby-agentdeck\sessions.json`)와
-  기록 파일 앞부분에서 읽은 첫 프롬프트. 앞엣것이 우선이고, 플러그인을 깔기 전 세션이나 다른 터미널에서
-  띄운 세션은 뒤엣것으로 잡힌다.
-- 기록 파일이 사라진 세션은 목록에서도 원장에서도 지운다. 이어받아도 복원할 것이 없기 때문이다.
-
-이 기능이 있는 이유는 아래 `기동 시 탭 복원 끄기` 와 한 쌍이다 — 순정 복원은 **셸만** 되살리고
-그 안의 세션은 이미 죽어 있어서 빈 프롬프트 탭만 줄줄이 남는다. 그래서 그쪽은 끄고, 진짜 복원을 여기 둔다.
-
-## 결과물 미리보기 패널
-
-에이전트가 만든 것이 문서나 그림이면 터미널 안에서는 확인할 수 없다. 그래서 탐색기로 나가서 열게 되고,
-그 왕복 때문에 결과물을 안 보고 넘어간다. 그 자리를 메우는 패널이다 — 사이드바의 **▤** 버튼이나
-`agentdeck-view` 단축키로 여닫는다. 여닫은 상태는 다음 기동에도 복원된다.
-
-**보여주는 것**
-
-| 종류 | 어떻게 |
-|---|---|
-| `md` `markdown` `mdx` | 제목·표·목록·코드·인용·체크박스·이미지까지 그려서 보여준다. 문서 안의 이미지도 같이 뜬다 |
-| `png` `jpg` `gif` `webp` `svg` `bmp` `ico` `avif` | 원본 크기로(패널보다 크면 폭에 맞춰) 그린다 |
-| `csv` `tsv` | 표로 그린다. 따옴표로 감싼 칸(`"a,b"`)을 한 칸으로 읽는다 |
-| 코드·텍스트 (`.ts` `.cs` `.py` `.json` `.log` …) | 줄 번호를 붙여 보여준다 |
-
-**파일이 패널에 올라오는 세 경로**
-
-1. **화면에 찍힌 경로를 줍는다** — `Edited src/hero.tsx`, `Wrote D:\a\b.md`, `Read build.py` 처럼
-   에이전트가 만진 파일을 찍으면 그것을 최근 목록(위쪽 칩)에 쌓는다. **어느 에이전트든 통한다** —
-   훅이 있는 Claude Code 뿐 아니라 Codex·Gemini 도 경로는 화면에 찍기 때문이다.
-   상대경로는 그 탭의 작업 폴더로 풀고, 실제로 있는 파일만 올린다. 최근 목록은 **탭마다 따로**다.
-2. **끌어다 놓기** — 탐색기·에디터에서 파일을 패널에 떨어뜨린다.
-3. **경로 직접 입력** — **＋** 를 눌러 경로를 넣는다(`Enter` 로 열고 `Esc` 로 접는다).
-   **없는 파일이면 만들어 준다** — `Enter` 를 한 번 더 치면 (필요하면 상위 폴더까지) 만들고
-   곧바로 편집으로 들어간다. 메모 한 장 시작하려고 탐색기로 나갈 일이 없다. 두 번 치게 한 이유는
-   오타로 친 경로에 빈 파일이 조용히 생기면 나중에 그 오타를 찾는 값이 더 크기 때문이다.
-
-열어 둔 파일이 바뀌면 **스스로 다시 읽는다** — 에이전트가 문서를 고치는 동안 옆에서 따라간다.
-패널이 닫혀 있어도 **읽어는 둔다**(`문서 패널에 읽어두기`, 기본 켬) — 그리지만 않고 최근 칩과
-"다음에 열면 보여줄 파일" 을 계속 갈아 두므로, 작업이 한창일 때 `▤` 를 누르면 **그때까지 건드린
-파일들이 칩으로 쌓여 있고 본문은 가장 최근 파일**이다(`변경` 을 보고 있었으면 그 자리에서 diff 를
-다시 읽는다). 같은 파일이라도 여는 김에 다시 읽는다 — 닫힌 동안에는 파일 감시가 꺼져 있어서다.
-**여닫기는 사람 몫이 기본**이다 — 결과물이 나오는 순간 패널까지 저절로 열리기를 원하면
-**설정 → 미리보기 패널 → `패널 자동으로 열기`** 를 켠다(기본 꺼짐). 반대로 `읽어두기` 를 끄면
-아무것도 자동으로 하지 않는다 — 경로는 최근 칩에만 쌓이고 무엇을 볼지는 사람이 고른다.
-문서 안의 링크는 웹이면 브라우저로, 로컬 파일이면 이 패널에서 연다.
-
-**탭을 옮기면 패널도 그 탭 것으로 바뀐다** — 최근 칩과 `변경` 탭뿐 아니라 **본문도** 그 세션이
-마지막으로 보던 파일로 돌아간다. 아무것도 안 본 탭에서는 빈 화면이다. 옆에 남의 탭 문서가 떠 있으면
-그것이 지금 탭의 것이라고 착각하기 때문이다. 탭을 옮기는 것만으로 패널이 **열리지는 않는다** —
-닫혀 있으면 다음에 열 때 맞춰진다.
-
-**고쳐서 저장한다 — `✎`**
-
-읽기만 되면 오타 하나에도 에디터를 따로 열어야 하고, 그 왕복이 이 패널이 없애려던 것과 같다.
-`✎` 를 누르면 본문 자리가 편집기가 된다. `저장`(`Ctrl+S`) · `취소`(`Esc`).
-
-- 글자 파일(`md` · 코드 · 텍스트 · `csv`)만 편집한다. 이미지·바이너리에서는 버튼이 흐려진다.
-- **너무 큰 파일은 열지 않는다** (1.5MB 넘음). 보기는 앞부분만 읽어도 되지만 저장은 파일을 통째로
-  다시 쓰므로, 앞부분만 들고 저장하면 뒷부분이 사라진다. 그래서 전체를 읽을 수 있을 때만 연다.
-- **BOM 과 개행(CRLF/LF)을 원본 그대로 되돌린다.** 안 그러면 한 줄만 고쳐도 P4·git diff 가
-  파일 전체를 바뀐 것으로 본다.
-- 편집하는 동안에는 **아무도 화면을 덮지 못한다** — 파일 감시의 자동 재읽기도, 새 파일 따라가기도
-  비켜 간다. 그 사이 파일이 밖에서 바뀌었으면 저장할 때 한 번 더 묻는다(두 번째 누름이 덮어쓴다).
-- **읽기 전용 파일은 열자마자 알린다** (`읽기 전용` 표시). 다 쳐 놓고 저장할 때 알면 그 타이핑이
-  헛일이 되기 때문이다. 저장을 누르면 `읽기 전용이다 (P4 면 p4 edit 먼저) — 다시 누르면 속성을
-  풀고 저장한다` 로 한 번 막는다. **말없이 속성을 풀지 않는 이유** — 이 환경에서 읽기 전용의
-  정체는 대개 P4 에서 체크아웃하지 않은 파일이고, 체크아웃 없이 쓴 내용은 다음 `p4 sync` 에
-  조용히 덮인다.
-- 저장하지 않은 편집이 있으면 다른 파일이나 `변경` 탭으로 넘어가지 않는다.
-
-**찾는다 — `🔍` / `Ctrl+F`**
-
-대소문자를 가리지 않고 본문에서 찾아 표시하고, `Enter`(다음) · `Shift+Enter`(이전) 로 오간다.
-`Esc` 로 닫으면 표시만 걷히고 본문 글자는 그대로다. 편집 중이면 편집기 안에서 찾아 그 자리를
-선택한다. **`Ctrl+F` 는 패널 안에서만 듣는다** — 터미널의 `Ctrl+F`(less·vim)를 뺏지 않으려는 것이라,
-본문을 한 번 누른 뒤에 쓴다.
-
-패널 폭은 터미널과 닿는 경계선을 끌어 바꾼다. **패널을 열면 4:3 이 완화되고 터미널이 그만큼 좁아진다** —
-사이드바는 줄지 않는다. 울트라와이드에서는 패널을 열어도 4:3 이 그대로 유지된다.
-
-> 문서 안의 원문 HTML 은 **글자로만** 보여준다(태그로 만들지 않는다). 참조 링크(`[a][1]`)와 각주는 지원하지 않는다.
-
-### `변경` 탭 — 작업트리의 diff
-
-헤더 아래 `파일` / `변경` 스위치로 바꾼다. `변경` 은 그 탭의 작업 폴더에서 `git diff HEAD` 를 읽어
-
-- `3개 파일 · +716 -15` 요약과 파일 목록(상태 딱지 + `+N -M`). 파일명을 누르면 그 파일 diff 로 스크롤한다
-- 파일별 유니파이드 diff — 구/신 줄번호를 양쪽에 붙이고 추가·삭제·문맥·헝크를 색으로 가른다
-- 추적되지 않은 파일은 이름만 따로 (내용 diff 는 하지 않는다)
-
-를 보여준다. **에이전트를 가리지 않는 이유가 미리보기와 같다** — 근거가 훅이 아니라 git 작업트리라서
-누가 고쳤든 성립한다. 저장소가 아니거나 git 이 없거나 작업 폴더를 아직 모르면 그 사실을 한 줄로 알린다.
-
-#### 스테이지 · 커밋
-
-파일 줄 왼쪽의 딱지가 **스테이지 상태**다 — `unstaged` / `staged` / `both`(일부만 올라감) /
-`untracked` / `conflict`. 누르면 그 파일을 `git add` 하거나 되돌린다(`git reset`). 아래 줄에
-`staged N · unstaged M` 요약과 메시지 입력창, 커밋 버튼이 있다.
-
-**우발 커밋을 막는 네 겹 —**
-
-1. 메시지가 비어 있으면 버튼이 잠긴다
-2. 공백만 넣으면 거부하고 이유를 적는다
-3. 첫 누름은 커밋하지 않고 `커밋 확인` 으로 바뀐다(색도 경고색). **두 번째 누름**에 실행된다
-4. 확인 대기 중에 메시지를 고치면 그 대기가 풀린다 (다른 메시지로 잘못 커밋되지 않게)
-
-스테이지된 것이 없으면 커밋하지 않는다 — `git commit -a` 로 넓히지 않는다.
-
-> 작업 폴더는 **탭이 열릴 때의 cwd** 다. 셸에서 `cd` 로 옮겨도 Tabby 가 알려주는 값은 바뀌지 않으므로
-> (Windows 로컬 세션 실측), 다른 저장소를 보려면 그 폴더에서 새 탭을 연다.
-> `git` 은 상위 폴더로 올라가며 저장소를 찾는다 — 홈 디렉토리가 저장소면 아무 폴더에서나 그것이 잡힌다.
-
-## 키
-
-| 키 | 동작 |
-|---|---|
-| `Ctrl+Enter` / `Shift+Enter` | 줄바꿈 (`0x0A` 전송). `agentdeck-newline` |
-| `Ctrl+V` | 붙여넣기. 클립보드에 **이미지만** 있으면 텍스트 대신 이미지 붙여넣기 키를 앱에 넘긴다 — Claude Code·Codex 가 클립보드를 직접 읽는다. `agentdeck-paste` |
-| 우클릭 | 선택이 있으면 복사, 없으면 붙여넣기. 길게(기본 250ms) 누르면 컨텍스트 메뉴 |
-| `Ctrl+Shift+L` | 사이드바 목록에 포커스를 준다 / 같은 키로 터미널로 돌아온다. `agentdeck-focus-list` |
-| `Ctrl+W` | 지금 탭을 닫는다 — 터미널에서 누르면 **활성 탭**, 목록이 키보드를 가졌으면 **포커스 줄의 탭**. `keyboardNav` + `keyboardCloseTab` 이 켜져 있을 때만이고, 끄면 터미널의 앞 단어 지우기(`0x17`)로 그대로 흐른다 |
-| (미배정) | `agentdeck-toggle` — 사이드바/4:3 즉시 on-off |
-| (미배정) | `agentdeck-repair` — 화면 복구 |
-| (미배정) | `agentdeck-view` — 미리보기 패널 여닫기 (사이드바 `▤` 와 같다) |
-| (미배정) | `agentdeck-view-mode` — 패널의 `파일` / `변경` 모드 전환 |
-
-키 배정은 Tabby 설정 → 단축키의 `agentdeck-*` 항목에서 바꾼다.
-`Ctrl+V` 는 **핫키가 아니라 캡처 단계에서 한 번만** 처리한다. 그래서 기동할 때 순정 `hotkeys.paste` 와
-`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다 — 핫키에 남겨 두면 Tabby 가 같은 키를 두 경로로 밀어 넣어
-한 번 눌러 두 번 붙는 일이 있었다(`docs/DEVELOPMENT.md` 에 원인).
-
-터미널 앱에 리터럴 `Ctrl+V`(0x16, quoted-insert)를 보내야 하면 `claimCtrlV: false`.
-그러면 우리도 잡지 않고 핫키에도 없으므로 xterm 이 0x16 을 그대로 PTY 로 흘린다 —
-**대신 그 상태에서는 `Ctrl+V` 붙여넣기 자체가 안 된다**(그게 이 설정의 목적이다).
-붙여넣기는 `Ctrl+Shift+V`·`Shift+Insert`(Tabby 순정) 또는 우클릭으로 한다.
-
-### 키보드로 사이드바 다루기
-
-`Ctrl+Shift+L` 로 목록에 들어간다. 마우스 없이 탭을 훑어보려고 만든 것이고, 규칙은 이렇다.
-
-| 키 | 하는 일 |
-|---|---|
-| `↑` `↓` | 줄 사이 이동. **활성 탭은 바뀌지 않는다** |
-| `Home` `End` | 첫 줄 / 마지막 줄 |
-| `Enter` | 탭 줄이면 그 탭으로 전환하고 키를 터미널에 돌려준다. 그룹 헤더면 접기/펴기 |
-| `Esc` | 검색어·필터가 걸려 있으면 **먼저 그것을 지운다**. 지울 게 없을 때 터미널로 나간다 |
-| `Tab` `Shift+Tab` | 검색창으로 |
-| `Ctrl+W` | 포커스 줄의 탭을 닫는다 (그룹 헤더에서는 아무 일도 하지 않는다). 목록 밖 — 터미널에서 누르면 활성 탭이다 |
-
-**포커스와 선택을 가른 이유** — 줄을 지날 때마다 탭이 바뀌면 그 탭의 출력이 화면을 덮고
-터미널 폭이 매번 다시 적용되어 화면이 튄다. 그러면 "어느 탭이었나" 를 훑어볼 수가 없다.
-그래서 `↑↓` 는 테두리(키보드 포커스)만 옮기고, 탭을 실제로 여는 것은 `Enter` 하나다.
-
-검색창과 목록은 `↓`(검색창 → 결과 첫 줄)와 `↑`(첫 줄 → 검색창)로 오간다.
-검색창의 `↑` 는 가로채지 않는다 — 한 줄 입력에서 `↑` 는 커서를 맨 앞으로 보내는
-편집 동작이고, 치던 검색어를 고칠 때 실제로 쓴다.
-
-포커스가 사이드바에 없는 동안에는 **키를 한 개도 가로채지 않는다**(리스너가 목록
-엘리먼트에 걸려 있어서 이벤트가 아예 오지 않는다). 그래도 끄고 싶으면 `keyboardNav: false`.
-
-`Ctrl+W` 만 예외다 — 그건 터미널에서도 받아야 하므로 **document 캡처 단계**에서 잡는다.
-대신 **닫을 탭이 정해졌을 때만** 키를 먹는다: 그룹 헤더에 포커스가 있거나 설정 화면 입력창이면
-그대로 흘린다. 핫키 테이블에 넣지 않은 이유도 그것이다 — Tabby 핫키는 등록만으로 키를 먹어서
-설정을 꺼도 터미널의 `Ctrl+W`(앞 단어 지우기)가 죽는다. 그 키를 그대로 쓰려면
-`keyboardCloseTab: false`(설정 창의 `Ctrl+W 로 탭 닫기`)로 끄면 되고 목록 조작은 남는다.
-닫기는 사이드바 `✕` 와 같은 경로라 돌아가는 프로세스가 있으면 Tabby 가 평소처럼 한 번 물어본다.
-
-### 한글 입력 — 조합 중인 음절이 커서를 따라가지 않게
-
-한글을 치다가 `Home` · `End` · `Shift+Enter` 를 누르면 **조합 중인 마지막 음절이 옮겨간 자리로 따라가는**
-문제가 있었다. 방향키만 멀쩡한데 그 차이가 원인이다 — xterm 은 자기 키 경로로 들어온 키에 대해서는
-조합을 **먼저 확정**하고 키를 보내지만, 그 경로를 거치지 않고 pty 에 바이트를 직접 쓰면
-(터미널 핫키·플러그인의 줄바꿈 전송) 확정이 `setTimeout` 으로 밀려 **바이트가 먼저, 음절이 나중**에 나간다.
-
-그래서 pty 에 쓰는 지점을 한 곳으로 모아, 쓰기 직전에 조합 상태를 보고
-
-- 조합 중이면 **조합이 끝나기를 기다렸다가** 쓴다
-- 확정 전송이 이미 예약돼 있으면 우리가 한 틱 물러난다
-- 상태를 못 읽으면 그냥 쓴다 (이 보정이 정상 입력을 막는 일은 없어야 한다)
-
-로 갈라 준다. 조합이 끝나지 않으면 0.4초 뒤에는 확정시키고 쓴다 — 입력이 안 나가는 것이 최악이다.
-
-> **왜 기다리나 (0.6.3).** 예전에는 조합 중이면 우리가 확정을 재촉하고 바로 썼다. 그런데 우리가
-> 확정시켜도 IME 는 자기 일정대로 확정을 한 번 더 알리고, 그때 음절이 **또** 나간다 — 그 두 번째가
-> 개행 뒤에 붙어 **문자가 새 줄로 내려갔다.** 지금은 IME 의 순서를 건드리지 않으므로 음절이 한 번만,
-> 개행보다 먼저 나간다.
-
-끄려면 `imeOrderGuard: false`.
-
-### 화면 복구 (`↻`)
-
-statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기는 등 화면이 깨졌을 때 누른다.
-폭 재계산 → pty 크기 동기화 → **입력창 자리의 잔상만** 지우기 → 흔들어 SIGWINCH 주기 순으로 진행한다.
-지운 자리는 앱이 자기 렌더 주기에 다시 그린다.
-
-**보고 있던 화면은 지우지 않는다.** 예전에는 마지막에 `Ctrl+L` 을 보내 "전부 다시 그려라" 를 시켰는데,
-Claude Code 는 그걸 **화면 지우기**로 받아 대화가 통째로 스크롤백으로 밀려났다
-(2026-09-11 채증: 정상 화면을 복구했더니 78행 중 0~72행이 비고 입력창만 남았다).
-그래서 `repairSendRedrawKey` 는 기본으로 꺼져 있다 — 실제로 고치는 것은 잔상 지우기와 크기 정합이라
-없어도 복구된다. 스크롤백까지 비우는 `repairHard: true` 도 기본은 꺼져 있다.
-
-## 설정
-
-**설정 창(설정 → AgentDeck)** 에는 실제로 바꿀 일이 있는 것만 있다 — 레이아웃 on/off, 마우스로 바꾼 배치 초기화,
-기동 시 탭 복원 끄기, 미리보기 패널(열기 · 경로 자동 수집 · 새 파일 따라가기), Claude Code 훅 설치/제거, 작업 루트 프로필. 나머지는 Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의
-`agentDeck` 아래에서 조절한다.
-
-| 키 | 기본값 | 설명 |
-|---|---|---|
-| `enabled` | `true` | 사이드바 + 4:3 레이아웃 on/off |
-| `aspectW` / `aspectH` | `4` / `3` | 터미널 뷰포트 비율 |
-| `sidebarDock` | `right` | 사이드바 위치 `left` / `right` / `top` / `bottom`. 헤더 드래그로도 바뀐다 |
-| `sidebarWidth` | `0` | 좌/우 도킹 시 폭(px). 0 = 화면비로 자동 계산 |
-| `sidebarHeight` | `200` | 상/하 도킹 시 높이(px) |
-| `sidebarMin` / `sidebarMax` | `200` / `560` | 자동 계산 폭의 범위(px). 넓은 모니터에서 정확히 4:3 을 원하면 `sidebarMax` 를 `창 너비 − 창 높이 × 4/3` 으로 |
-| `sortByStatus` | `false` | 급한 순서(승인대기 → 오류 → 한도 → 진행중 → 완료 → 대기)로 정렬한다. 켜면 **드래그 재정렬은 막힌다** — 옮겨도 다음 렌더에 제자리로 돌아가기 때문 |
-| `collapsedGroups` | `[]` | 접어 둔 그룹 키. 헤더를 누르면 여기 쌓인다. 설정 창의 `모두 펼치기` 로 비운다 |
-| `viewerOpen` | `false` | 미리보기 패널이 열려 있나. `▤` / `agentdeck-view` 로 토글하거나 **새 파일을 주워 저절로 열리면** 여기 남아 다음 기동에 복원된다. 열림을 사람이 켜 두는 값이 아니다 |
-| `viewerDock` | `right` | 패널이 붙는 방향 `left` / `right`. 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥) |
-| `viewerWidth` | `420` | 패널 폭(px). 경계선 드래그로 바뀐다. 좁은 창에서는 `창폭 − 320 − 140` 까지만 |
-| `searchBox` | `true` | 사이드바에 검색 줄을 보인다. 끄면 걸려 있던 필터도 함께 지운다(감춰진 필터는 만들지 않는다) |
-| `keyboardNav` | `true` | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓`·Enter·Esc 로 다룬다. 포커스가 사이드바에 없으면 아무 키도 가로채지 않으므로 켜 둬서 잃는 것이 없다 |
-| `keyboardCloseTab` | `true` | `Ctrl+W` 로 탭을 닫는다 — 터미널에서는 활성 탭, 목록이 키보드를 가졌으면 포커스 줄의 탭. `keyboardNav` 를 끄면 이 값과 무관하게 꺼진다. 끄면 `Ctrl+W` 가 터미널로 그대로 간다(셸의 앞 단어 지우기) |
-| `keyboardNavWrap` | `false` | 목록 끝에서 `↑↓` 가 반대쪽으로 감긴다. 끄면 끝에서 멈춘다 — "맨 아래에 왔다" 가 보이고 목록이 통째로 튀지 않는다. 끝↔끝은 Home/End 로 |
-| `viewerScrape` | `true` | 화면에 찍힌 파일 경로를 주워 최근 목록에 쌓는다. 끄면 끌어다 놓기·경로 입력만 |
-| `viewerDropOpen` | `ask` | 터미널 위에 파일을 끌어다 놓았을 때 — `ask` 물어본다 / `always` 패널에 띄운다 / `paste` 경로를 붙여넣는다 / `never` 개입하지 않는다(순정) |
-| `viewerPreload` | `true` | 에이전트가 만진 파일을 **닫혀 있는 동안에도** 패널에 얹어 둔다(최근 칩 + 다음에 열 때 띄울 파일). 끄면 아무것도 자동으로 하지 않는다. 설정 창의 `문서 패널에 읽어두기` |
-| `viewerAutoOpen` | `false` | 새 파일을 주우면 **닫힌 패널을 스스로 연다.** 기본 꺼짐 — 여닫기는 사람 몫이고, 내용은 위 `viewerPreload` 가 채워 둔다. 설정 창의 `패널 자동으로 열기` |
-| `viewerFollowMode` | `''` | (옛 값) 0.18.0 부터 위 토글 두 개로 갈랐다. `open`/`show`/`manual` 이 적혀 있으면 기동 때 한 번 두 토글로 옮기고 비운다 |
-| `viewerFollow` | `true` | (더 옛 값) 0.17.0 에 `viewerFollowMode` 로 옮겼다. `false` 였으면 마이그레이션이 `viewerPreload: false` 로 읽고 기본값으로 되돌린다 |
-| `viewerRecentMax` | `12` | 최근 목록에 남겨 두는 파일 수 |
-| `imeOrderGuard` | `true` | pty 에 바이트를 쓰기 전에 조합 중인 한글 음절을 먼저 확정한다 (아래 "한글 입력") |
-| `releaseHomeEnd` | `true` | Home / End 를 Tabby 핫키에서 걷어내 xterm 순정 경로로 돌려준다 |
-| `idleAfterMs` | `2500` | 이 시간 동안 출력이 없으면 `대기` 로 |
-| `autoDetect` | `true` | 출력·제목 패턴으로 상태 추론 |
-| `showElapsed` | `true` | 경과 시간 표시 |
-| `sortByStatus` | `false` | 사이드바 탭을 상태 우선순위(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 정렬한다. 같은 상태끼리는 탭 순서 유지. 끄면 순정 탭바와 같은 순서 |
-| `dragAutoScroll` | `true` | 줄을 끌 때 목록 끝에서 저절로 스크롤된다. 끄면 손을 뗀 뒤 스크롤하고 다시 끌어야 하지만, 그 대신 **맨 끝 줄 뒤에 놓는 조작이 미끄러지지 않는다** |
-| `keepRenderingWhenHidden` | `true` | 창이 가려져 있어도 사이드바를 갱신한다. 끄면 상태 변화가 최대 1분까지 늦게 보일 수 있다 |
-| `subagentCount` | `true` | 사이드바 줄에 도는 서브에이전트 개수를 보인다. 0 개면 아무것도 그리지 않으므로 켜 둬서 잃는 것이 없다. 끄면 대화 기록을 **읽지도 않는다** |
-| `enterAsLabel` | `true` | Enter 로 프롬프트를 보낼 때 입력창 원문을 작업 라벨로 삼는다 |
-| `labelAsTitle` | `true` | 사이드바 제목 줄에 탭 제목 대신 작업 라벨을 쓴다. Tabby 의 탭 제목 자체는 건드리지 않는다 |
-| `noTabRecovery` | `false` | 기동 시 지난 탭을 복원하지 않는다 — Tabby `recoverTabs` 를 false 로 강제. 복원되는 건 셸뿐이고 안의 Claude 세션은 죽어 있어 의미가 없다 (설정 창에서 켠다) |
-| `notifyChannel` | `true` | 훅이 보낸 상태를 받는 통로(로컬 TCP + 상태 파일). 훅을 설치하면 자동으로 켜진다 |
-| `notifyPort` | `47500` | 그 TCP 포트(127.0.0.1 전용). 물려 있으면 임의 포트로 물러나고 실제 번호는 `%LOCALAPPDATA%\tabby-agentdeck\port` 에 적힌다 |
-| `hookPromptDismissed` | `false` | 기동 시 뜨는 훅 설치 안내를 다시 띄우지 않는다 |
-| `claimCtrlV` | `true` | `Ctrl+V` 를 캡처 단계에서 직접 처리한다. 기동 시 `hotkeys.paste`·`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다(두 번 붙는 것 방지). `false` 면 리터럴 0x16 이 앱으로 가고 **붙여넣기는 안 된다** |
-| `pasteImageWithCtrlV` | `true` | 클립보드에 이미지만 있으면 텍스트 붙여넣기 대신 이미지 붙여넣기 키를 보낸다 |
-| `imagePasteKey` | `alt-v` | 그때 보낼 키. `ctrl-v`(0x16) 는 Claude Code·Codex 둘 다, `alt-v`(ESC v) 는 Claude Code 전용 |
-| `claimRightClick` | `true` | 우클릭을 플러그인이 처리한다 (Tabby 의 `terminal.rightClick` 은 `off` 로) |
-| `rightClickMenuMs` | `250` | 이 시간 이상 누르면 붙여넣기 대신 컨텍스트 메뉴 |
-| `terminalOpacity` | `75` | 터미널 배경 불투명도(%). 100 미만이면 `tabby-background` 의 배경 이미지가 비친다. 100 = 순정 |
-| `sidebarOpacity` | `75` | 사이드바 / 창 여백 불투명도(%) |
-| `clipBackgroundToTerminal` | `true` | `tabby-background` 이미지를 터미널 영역으로 잘라 사이드바 밑까지 비치지 않게 한다 |
-| `screenWatch` | `true` | 2초마다 화면이 깨졌는지 판정해 `~/.agentdeck-screen.log` 에 기록만 한다 (복구는 하지 않음). 4MB 를 넘으면 `.1` 로 밀린다 |
-| `autoRepairScreen` | `false` | 깨졌다고 판정되면 조용히 화면 복구까지 한다 |
-| `autoRepairMinStreak` | `2` | 깨짐이 이만큼 연속으로 보여야 복구한다 (그리는 도중의 중간 프레임 오탐 방지) |
-| `autoRepairCooldownMs` | `10000` | 자동 복구 후 이만큼은 다시 하지 않는다 |
-| `autoRepairMaxPerTab` | `3` | 한 탭에서 자동 복구 최대 횟수. 0 = 무제한 |
-| `repairHard` | `false` | 화면 복구가 `xterm.reset()` 까지 한다 (스크롤백도 지워진다) |
-| `repairSendRedrawKey` | `false` | 화면 복구 마지막에 `Ctrl+L` 을 보낸다. **끄는 것이 기본** — Claude Code 는 이걸 재렌더가 아니라 **화면 지우기**로 받아 보고 있던 대화를 스크롤백으로 밀어낸다 (2026-09-11 채증). 켜면 자동 복구에도 적용된다 |
-| `rootProfile` | `false` | 작업 루트 프로필을 만들어 기본 프로필로 삼는다 (설정 창에서 켠다) |
-| `rootProfileName` | `Agent Root` | 그 프로필 이름 |
-| `rootProfileCwd` | `''` | 새 탭이 열릴 경로. 비우면 프로필을 만들지 않는다. 슬래시로 적는다 (예: `D:/Project`) |
-| `rootProfileCommand` | `powershell.exe` | 셸 |
-| `rootProfileArgs` | `-NoLogo -ExecutionPolicy Bypass` | 셸 인자. `Bypass` 는 npm 전역 `.ps1` 래퍼(`claude` 등)가 실행 정책에 막히지 않게 한다 — 그 세션에만 적용 |
-| `rootProfileEnv` | `TERM=xterm-256color`, `COLORTERM=truecolor` | 셸 환경변수 (빠진 것만 채운다) |
-| `alertFlash` | `true` | 창이 뒤에 있을 때 탭이 `승인대기`/`오류`/`한도 도달` 로 넘어가면 작업표시줄 아이콘을 깜빡인다. 창이 포커스를 받으면 멈춘다 |
-| `alertBadge` | `true` | 작업표시줄 아이콘 위에 `승인대기`+`오류`+`한도 도달` 탭 개수를 뱃지(원+숫자)로 얹는다. 0 이면 지운다 |
-| `alertToast` | `false` | 그때 OS 토스트도 띄운다. 누르면 창을 앞으로 가져오고 그 탭을 고른다 |
-
-## 문제 신고
-
-버그를 만났으면 **설정 → AgentDeck → 문제 신고 → `모으기`** 를 누른다.
-진단 로그를 zip 하나로 묶고 그 파일이 있는 폴더를 열어 주므로, 그 zip 을 이슈에 붙이면 된다.
-
-담기는 것
-
-| 파일 | 내용 |
-|---|---|
-| `report.txt` | 플러그인/Tabby/Electron 버전, OS, 설정 값(도킹·화면비·`useConPTY` 등), 이 세션의 최근 진단 200줄 |
-| `agentdeck-diag.log` | `~/.agentdeck-diag.log` — 세션 머리말, 배치·입력·pty 판정, 잡히지 않은 예외와 스택, 삼켜진 실패(`CATCH …`) |
-| `agentdeck-diag.log.1` | 그 직전 분량 (2MB 를 넘겨 밀려난 것) |
-| `agentdeck-screen.log` | **"화면 원문까지 넣기" 를 켤 때만.** 깨진 순간의 터미널 화면이 글자 그대로 들어간다 |
-
-알아 둘 것
-
-- 로그는 **기동해도 지워지지 않는다.** 2MB 를 넘길 때 `.1` 로 한 세대 밀리므로, 어제 겪은 문제도 대개 남아 있다.
-- 로그에는 **탭 제목과 열어 본 파일 경로**가 들어간다. 보내기 전에 열어 봐도 되고, 화면 원문은 기본으로 빠진다.
-- 설정 창을 열 수 없을 만큼 깨졌으면 devtools 콘솔에서 `__agentdeck.collectDiag()` — 같은 zip 을 만들고 경로를 돌려준다.
-  최근 진단 줄만 보려면 `__agentdeck.kickLog`.
-
-## 알려진 문제
-
-### Tabby 1.0.235 에서 새 탭이 열리지 않음
-
-```
-Error: ENOENT, node_modules\node-pty\lib\conpty_console_list_agent not found in ...\resources\app.asar
-```
-
-Tabby 설치본의 패키징 버그로 플러그인과 무관하다. ConPTY 를 끄면 이 경로를 타지 않는다.
-
-```yaml
-# %APPDATA%\tabby\config.yaml
-terminal:
-  useConPTY: false
-```
-
-## 라이선스
-
-MIT
-
-개발 절차·구조·설계 근거·실측 함정은 리포의 `docs/DEVELOPMENT.md`, 회귀 체크리스트는 `docs/REGRESSION.md` 에 있다.
+# tabby-agentdeck
+
+[![npm](https://img.shields.io/npm/v/tabby-agentdeck)](https://www.npmjs.com/package/tabby-agentdeck)
+[![downloads](https://img.shields.io/npm/dm/tabby-agentdeck)](https://www.npmjs.com/package/tabby-agentdeck)
+[![CI](https://github.com/jghwang2/tabby-agentdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/jghwang2/tabby-agentdeck/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/tabby-agentdeck)](LICENSE)
+
+**[웹사이트](https://jghwang2.github.io/tabby-agentdeck/ko.html) · [사용 설명서](https://jghwang2.github.io/tabby-agentdeck/guide/ko.html) · [전체 레퍼런스](docs/REFERENCE.ko.md) · [English](README.md)**
+
+**Claude Code · Codex · Gemini CLI 를 탭 여러 개에 띄워 두고 쓰는 사람**을 위한 [Tabby](https://tabby.sh) 플러그인.
+4:3 터미널, 상태가 실시간으로 보이는 세션 목록, 에이전트 결과물 미리보기 패널.
+
+![tabby-agentdeck — 터미널, 미리보기 패널, 세션 목록](docs/guide/img/00-full.png)
+
+## 단축키
+
+| 키 | 동작 |
+|---|---|
+| `Ctrl+T` (⌘+T) | 작업 루트에 새 탭 |
+| `Ctrl+1` … `Ctrl+9` | 고정 세션 번호 1~9로 이동 (필터·다른 세션 종료에도 번호 유지) |
+| `Ctrl+L` | 세션 목록에 포커스 / 같은 키로 터미널 복귀. 이어서 `↑↓` 이동, `Enter` 선택, `Esc` 나가기 |
+| `Ctrl+W` | 지금 탭 닫기 (목록이 키보드를 가졌으면 포커스 줄) |
+| `Ctrl+O` | 미리보기 패널 여닫기 |
+| `Ctrl+R` | 화면 복구 (`↻` 와 같다). 탭 이름은 줄 더블클릭으로 변경 |
+| `Ctrl+S` | 좌우로 분할 (Tabby 순정) |
+| `Ctrl+D` | 위아래로 분할 (Tabby 순정) |
+| `Ctrl+Q` | 포커스된 분할 패널 닫기 |
+| `Ctrl+Enter` / `Shift+Enter` | 전송하지 않고 줄바꿈 |
+| `Ctrl+V` | 붙여넣기. 클립보드에 이미지만 있으면 이미지로 에이전트에 넘긴다 |
+| 우클릭 | 선택이 있으면 복사, 없으면 붙여넣기. 길게 누르면 컨텍스트 메뉴 |
+| `Ctrl+F` / `Ctrl+S` | 미리보기 패널 안에서 찾기 / 저장 |
+
+배정되지 않은 것은 둘: `agentdeck-toggle`(사이드바 / 4:3 즉시 on-off), `agentdeck-view-mode`(파일 ↔ 변경).
+**설정 → AgentDeck → 단축키** 에서 바꾼다 — Tabby 순정이나 AgentDeck 이 이미 쓰는 키면 적용 전에 무엇과 겹치는지 알려 준다. Tabby 설정 → 단축키 → `agentdeck-*` 로도 된다.
+위 표는 새 설치의 기본값이다. 기존 AgentDeck 단축키는 저장된 값을 유지하며, 각 항목의 **기본값** 버튼으로 새 키를 적용한다. 순정 분할 키 `Ctrl+Shift+S` / `Ctrl+Shift+D`는 `Ctrl+S` / `Ctrl+D`로 바꾸고, 직접 지정한 분할 키는 유지한다.
+
+## 지난 대화 검색
+
+**지난 세션**을 펼치고 전용 검색창에 함수명·오류코드·파일명·세션 ID를 입력한다. 저장된 Claude·Codex 대화의 질문과 답변에서 대소문자 구분 없이 입력한 문자열 그대로 찾는다. 결과를 누르면 일치한 대화가 미리 열리고, **이어서 대화**를 눌러 재개한다. 현재 탭 검색과는 별도다.
+
+검색은 로컬 Node.js 백그라운드 프로세스로 실행하고, 기록이 바뀌면 디스크 캐시를 갱신한다. PATH에서 Node.js를 실행할 수 있어야 한다. MCP 연결이나 AI 요청은 필요 없다. 도구 출력과 시스템 안내는 제외한다. 범위와 저장 위치는 [검색 안내](docs/HISTORY-SEARCH.md)를 참고한다.
+
+## 설치
+
+Tabby 안에서: 설정 → 플러그인 → `agentdeck` 검색 → 설치 → Tabby 재시작.
+세션은 1~9 고정 번호를 사용하며 빈 번호를 재사용합니다. 자동 정렬과 드래그 순서 이동은 사용하지 않습니다.
+선택적으로 연결하는 [세션 통신 MCP](docs/SESSION-COMMUNICATION.md)는 실제 세션 ID로만 송수신합니다. 사람용 번호는 MCP 주소가 아닙니다.
+
+그 외 — 상태·미리보기 패널·diff 와 커밋·지난 세션 이어받기·설정 — 은
+[사용 설명서](https://jghwang2.github.io/tabby-agentdeck/guide/ko.html)와 [전체 레퍼런스](docs/REFERENCE.ko.md)에 있다.
+
+Windows 에서 만들고 검증했다. MIT.