이슈 트래커의 이슈를 로컬 코딩 에이전트의 작업으로 바꾸는 터미널 도구.

Why

이슈는 트래커에 있고 에이전트는 터미널에 있습니다. 그래서 작업 하나를 돌릴 때마다 이슈를 읽고, 레포로 이동하고, 제목과 본문을 프롬프트에 붙여넣고, 결과를 확인하고, 다시 트래커로 돌아가 상태를 바꾸는 왕복이 생깁니다. 에이전트가 일하는 시간보다 일을 넘겨주고 받는 시간이 더 걸리기도 합니다.

agentq는 그 왕복을 없앱니다. 이슈 목록이 터미널에 뜨고, r 한 번으로 미리 정해둔 디렉토리에서 에이전트가 돌고, 결과를 보고 a를 누르면 트래커 상태가 넘어갑니다.

대신 판단은 넘기지 않습니다. 에이전트를 실행하는 것과 결과를 승인하는 것은 사람이 합니다. 자동 실행은 좌표별로 켜는 선택 사항이고, 트래커에 쓰는 것은 언제나 사람의 승인 뒤입니다.

Quick Start

$ agentq

① 소스 연결    Linear 워크스페이스와 API 키를 넣습니다
② 필터 고르기  담당자 나 · 팀 ENG → 큐에 6건이 들어옵니다
③ 매핑 걸기    이 조건의 이슈는 ~/repos/api에서 Claude Code로 돌린다
④ r → a       실행하고, 결과를 보고, 승인하면 Linear 상태가 넘어갑니다

방금 만든 넷이 agentq의 전부입니다.

Key Concepts

소스는 종류가 아니라 연결이 단위입니다 — 회사 Linear와 개인 Linear는 별개 소스이고, 각자의 키와 어휘를 갖습니다. 필터와 매핑은 둘 다 그 소스의 어휘로 쓰지만 방향이 다릅니다: 필터는 뭘 가져올지, 매핑은 가져온 것 중 뭘 어디서 돌릴지. 여러 소스에서 온 작업은 하나의 큐로 합쳐져 한 화면에 뜹니다.

| 개념 | 무엇인가 | 개수 | | --- | --- | --- | | 소스 | 이슈가 사는 곳과의 연결 하나. 종류가 아니라 연결이 단위라, 같은 Linear라도 워크스페이스마다 별개 소스입니다 (linear-1처럼 이름을 갖습니다) | N | | 조회 필터 | 그 소스에서 내 큐로 들여올 이슈의 조건. 소스의 어휘(팀·프로젝트·라벨·상태)로 씁니다 | 소스당 1 | | 매핑 | 이슈의 좌표 → 로컬 디렉토리 + 실행 명령. 어떤 이슈를 어디서 무엇으로 돌릴지 | 소스당 N | | 안전장치 | 동시 실행 상한·타임아웃. 어느 소스의 작업이든 똑같이 적용되는 전역 설정 | 1 |

Install

npm install -g @egg528/agentq
agentq

설정 파일은 없습니다. 첫 실행에서 온보딩이 소스·키·필터를 물어보고, 이후 모든 설정은 s로 여는 설정 화면에서 바꿉니다.

Usage

목록에서 이슈를 고르고:

• r 실행 — 매핑이 없으면 그 자리에서 만듭니다 (디렉토리 → 적용 범위 → 실행 방식)
• a 승인 — 상태를 골라 트래커에 반영합니다. x는 거부
• enter 세션 이어가기 — 에이전트 세션을 터미널에서 그대로 이어받습니다
• A 자동 실행 토글 — auto로 표시한 매핑의 이슈를 알아서 시작합니다 (기본 꺼짐)
• / 검색 · s 설정 · q 종료 · esc 한 단계 뒤로

전체 키맵과 화면 규약은 docs/tui.md에 있습니다.

실행은 자동, 승인은 수동. 자동 실행을 켜도 결과를 트래커에 반영하는 건 사람입니다. 한 번 실행한 이슈는 자동으로 다시 돌지 않습니다 — 재실행은 r로만 합니다.

Requirements

• Node.js 22.13 이상 (node:sqlite 사용 — 네이티브 빌드 없음)
• Linear 개인 API 키 (Settings → Security & access)
• 실행할 에이전트 CLI: Claude Code 또는 Codex (또는 아무 CLI나 커스텀 명령으로)

설정·실행 이력은 ~/.local/share/agentq/agentq.db에 저장됩니다 (SQLite, 퍼미션 600 — API 키가 들어 있습니다). AGENTQ_DATA_DIR로 위치를 바꿀 수 있습니다.

Development

pnpm install
pnpm dev        # tsx로 바로 실행
pnpm test       # vitest
pnpm lint       # biome
pnpm build      # tsdown → dist/

License

MIT