**목차:** [디자인 원칙](#design-principles) · [모드](#modes) · [세션](#sessions) · [키(Keys)](#keys) · [다른 도구와의 비교](#compared-with-other-tools) · [설치(Install)](#install) · [파일(Files)](#files) · [개발(Development)](#development) · [라이선스(Licence)](#licence)
## 디자인 원칙
- **사용자의 주의력이 병목입니다.** 여러분이 기다리는 세션을 찾기 위해 여러 세션 사이를 오갈 필요 없이, aq는 Claude Code의 훅(hooks)을 사용하여 작업을 하나의 대기열로 밀어 넣습니다. 즉, 작업이 당신에게 오도록 하고, 당신이 작업으로 향할 필요가 없게 만듭니다. 권한 프롬프트, 질문 및 옵션 메뉴 역시 여기서 답변되며, 새로운 카드가 현재 보고 있는 화면을 가리지 않습니다.
- **간편한 변경, 검토 및 댓글 루프.** [tuicr](https://tuicr.dev/)에서 영감을 받은 코드 리뷰 기능입니다. 한 줄 또는 범위에 대해 댓글을 달고, 이를 PR(Pull Request) 리뷰처럼 에이전트에게 하나의 메시지로 전송할 수 있습니다.
- **프로젝트에 맞춘 검사.** 각 프로젝트는 자체 모드를 가집니다: vibe (검사 없음), review, step (모든 편집은 '예' 승인을 기다림), 또는 quiz. 스크립트는 결제 서비스가 모든 편집을 기다리는 동안 단순히 실행될 수 있습니다.
- **퀴즈 모드.** 코드에 대한 설계 질문에 답하여 변경 사항에 대한 이해도를 확인하고 강화합니다.
- **방해받지 않음 (Unobtrusive).** tmux 세션과 병행하여 실행되며, 복잡한 의존성 없이 훅을 통해 Claude Code와 연결됩니다. aq가 실행되고 있지 않으면 훅은 아무것도 하지 않으며 Claude는 평소처럼 작동합니다.
- **하나의 화면에서 모든 세션 관리.** 대기 중인 것이 없을 때는 모든 세션을 실시간으로 볼 수 있으며, 특정 세션에 메시지를 보내거나, 진행 상황을 문의하거나, 모델 또는 권한 모드를 전환하거나, 새 세션을 시작할 수 있습니다.
- **키보드 우선(Keyboard first)**이며, vim 키 바인딩을 지원합니다.
## 모드 (Modes)
각 프로젝트는 하나의 모드를 가지며, `M` 키로 이를 전환합니다.
**검토 (Review)** (기본값): 세션이 완료되면 해당 diff가 카드로 표시됩니다. 한 줄 또는 범위에 대해 댓글을 달 수 있고, `s`를 누르면 모든 댓글이 전송되며, `a`는 승인하고, `d`는 파일을 완료된 것으로 표시하여 시야에서 치웁니다. 마크다운 파일(계획, 사양, README 등)은 제목, 굵게, 코드, 글머리 기호가 스타일링되어 읽기 모드로 표시되고 표시는 숨겨지며, `m`을 누르면 작성된 상태로 보여집니다. `e`는 커서의 줄에서 파일을 에디터로 열어 사용자가 직접 수정하기를 원하는 변경 사항에 대비할 수 있습니다.
**Step**: 모든 편집은 적용되기 전에 승인을 기다립니다. `y`를 누르면 통과되고, `n`을 누르면 이유와 함께 되돌려 보냅니다.
**퀴즈(Quiz)**: 세션이 종료되면, aq는 중요한 변경 사항(diff) 부분을 골라내어 그것들이 무엇을 하는지, 또는 왜 그렇게 처리되었는지 사용자가 자신의 말로 설명하도록 요청합니다. 평가자(judge)가 답변에 점수를 매깁니다. 만약 틀렸거나 모른다고 하면, 놓친 부분으로 유도하는 질문과 함께 최대 두 번의 기회가 주어지고, 그 후에야 정답이 표시됩니다 (`e`를 누르면 더 빨리 표시). 또한 평가자가 코드 자체에서 발견한 오류(gap)는 수정 사항(fix)으로 되돌려 보낼 수 있습니다.
**느낌(Vibe)**: 아무것도 검사하지 않습니다. 에이전트가 그저 코딩만 합니다.
**질문(Questions)**, 모든 모드에서: 세션이 사용자에게 무언가를 요청하며 턴을 마칠 때 (초안 승인 또는 두 가지 방법 중 선택), 해당 메시지는 카드로 변환됩니다. 질문이 진행 허가(go-ahead)를 요구하면 `a`로 승인하고, 자신의 말로 답변하려면 `Enter`를 누르며, 카드를 치우려면 `x`를 누릅니다. Claude가 자체 옵션 메뉴와 함께 질문할 경우, 카드에 목록이 표시되고 숫자 키로 하나를 선택합니다. 이 답변은 후크(hook)를 통해 다시 전달되므로 세션 내부에 아무것도 입력되지 않습니다. diff와 질문을 모두 포함하는 턴은 검토 카드에 질문을 보여주며, 여기서 전송하면 해당 질문에 대한 답이 됩니다.
## 세션(Sessions)
아무것도 대기하고 있지 않을 때, 각 세션별로 탭이 생성되며 선택된 세션의 화면이 그 아래에서 실시간으로 표시됩니다. 각 탭은 하단에 해당 세션의 권한 모드(permission mode)를 보여주며, 예를 들어 `⏵⏵ auto` 또는 `⏸ plan`과 같습니다. `Enter`는 메시지를 전송합니다 (유휴 상태일 때 한 번 전송). `W`는 중단하지 않고 진행 상황을 묻고, `p`는 PR(Pull Request) 생성을 요청하며, `m`은 모델을 전환하고, `P`는 권한 모드(auto, manual, accept edits 또는 plan)를 설정합니다. 그리고 `Esc Esc`는 세션을 중지시킵니다. `N`은 현재 프로젝트 내에서 새로운 Claude 세션을 자체 tmux 창에 시작하며, 사용자가 입력한 내용이 첫 번째 프롬프트가 됩니다. 해당 상자에서 `Tab`을 누르면 세션에 자체 git worktree (Claude의 `--worktree`)가 부여되어 두 세션이 같은 파일을 편집하는 것을 방지합니다. `Ctrl-O`는 다른 폴더를 선택합니다: 경로를 입력하면 아래에 일치하는 폴더 목록이 나타나고 (`Tab`으로 완성, 화살표로 선택), 아직 존재하지 않는 폴더도 세션 시작 시 생성됩니다.
`!`는 프로젝트 폴더 내의 tmux 팝업에서 셸을 열어, Claude가 스스로 실행할 수 없는 작업(예: sudo, 로그인 또는 권한이 차단된 명령어)을 처리하게 합니다. Claude가 마지막으로 제안한 `! command`는 복사되어 zsh에 이미 입력되어 있으므로 Enter를 누르면 실행됩니다. 셸이 종료되면 팝업은 닫힙니다.
## 키 (Keys)
aq가 처음 시작되면, 가상의 카드들을 사용하여 워크플로우를 시도하는 투어(tour)를 진행하며, 한 번에 어떤 키를 눌러야 하는지 알려줍니다. 먼저 검토(review)(이동, 댓글 작성, 완료 표시, 전송, 승인), 다음으로 `M`을 누르면 단계 모드(step mode)로 진입합니다 (한 개의 편집 허용, 이유와 함께 다음 항목 거부). 그다음은 퀴즈 모드(quiz mode)입니다 (질문에 답하고 심사위원이 발견한 공백(gap)을 수정 사항으로 다시 전송). 마지막으로 세 가지 가상 세션이 있습니다: 하나를 선택하고, 메시지를 보내고, 진행 상황을 문의하거나, 새 것을 시작하여 그 프로젝트를 모드들을 거치게 합니다. 투어에서 다루는 내용은 실제 세션에 도달하지 않습니다. `F2`를 누르면 투어가 다시 실행되며, `F1`은 모든 키 목록을 보여줍니다.
첫날부터 알아두면 좋은 것들:
| Key | Where | What it does |
|---|---|---|
| `M` | anywhere | 다음 프로젝트 모드: 검토(review), 단계(step), 퀴즈(quiz), 분위기(vibe) |
| ... | | |
이동은 vim과 같이 작동합니다: `j` `k`, `Ctrl-d` `Ctrl-u`, `gg` `G`, 변경 사항을 위한 `]c` `[c`, 파일에 대한 `H` `L`.
## 다른 도구와의 비교 (Compared with other tools)
| | aq | [Claude Squad](https://github.com/smtg-ai/claude-squad) | [Conductor](https://www.conductor.build) | [Vibe Kanban](https://github.com/BloopAI/vibe-kanban) | [tuicr](https://github.com/agavra/tuicr) |
|---|---|---|---|---|---|
| Runs in | 터미널 (terminal) | 터미널 (terminal) | macOS 앱 | 브라우저 (browser) | 터미널 (terminal) |
| ... | | |
aq는 세션을 시작(`N`)할 수 있으며, 요청하면 자체 작업 트리(worktree)에서도 작동하지만, 브랜치와 병합(merging)은 사용자님과 Claude에게 맡깁니다: 원하는 대로 Claude를 시작하고 aq가 이를 포착합니다. 만약 모든 세션의 브랜치를 대신 관리해 주는 단일 앱을 원한다면, 다른 도구들 중 하나가 더 적합할 것입니다.
## 설치 (Install)
이 페이지 상단의 프롬프트가 이 모든 것을 자동으로 처리해 줍니다. 수동으로 진행하려면: aq는 Linux 환경의 tmux 내부에서 실행됩니다. [최신 릴리스](https://github.com/nodo-labs-uk/attention-queue/releases/latest)에서 바이너리를 받거나, `cargo install --path .` 명령어로 소스 코드로부터 직접 빌드할 수 있습니다.
```sh
curl -fsSL https://github.com/nodo-labs-uk/attention-queue/releases/latest/download/aq-x86_64-linux.tar.gz | tar xz
install aq-x86_64-linux/aq ~/.local/bin/
