qqqa: 터미널을 떠나지 않고 사용하는 빠르고 가벼운 LLM 어시스턴트 (qq + qa)

9bow · 11월 20, 2025, 9:30오후

qqqa 소개

개발자들에게 있어 터미널은 제2의 고향과도 같습니다. 하지만 코딩을 하거나 서버를 관리하다 보면 수시로 웹 브라우저를 열어 문법을 검색하거나, ChatGPT와 같은 LLM(거대 언어 모델)에게 질문을 던져야 할 때가 많습니다. 이러한 잦은 화면 전환(Context Switching)은 작업의 흐름을 끊고 집중력을 저하시키는 주된 요인이 됩니다. qqqa는 이러한 문제를 해결하기 위해 탄생한, 터미널 환경에 최적화된 빠르고 가벼운 LLM 어시스턴트 도구입니다.

qqqa는 복잡한 설정이나 무거운 의존성 없이 셸(Shell)에서 바로 사용할 수 있는 두 가지 핵심 도구인 qq와 qa를 제공합니다. 이 도구는 'Stateless(상태 비저장)'를 지향하여, 불필요한 대화 히스토리를 관리하지 않고 일회성 질문과 작업에 집중합니다. 덕분에 개발자는 터미널을 벗어나지 않고도 빠르게 코드 스니펫을 얻거나, 셸 명령어를 추천받아 즉시 실행할 수 있습니다. 특히 QWERTY 키보드에서 입력하기 가장 쉬운 키 조합 중 하나인 qq와 qa를 명령어 이름으로 채택하여, 개발자의 타이핑 속도와 편의성까지 고려했습니다.

qqqa 프로젝트는 Unix 철학인 "한 가지 일을 잘해내자(Do one thing and do it well)"를 LLM 도구에 적용했습니다. 복잡한 채팅 인터페이스 대신, 파이프라인(|)을 통해 다른 명령어와 조합하거나 스크립트 내에서 활용하기 쉽도록 설계되었습니다. 또한, OpenRouter, OpenAI, Groq, Ollama 등 다양한 모델 공급자를 지원하여 사용자가 원하는 LLM을 자유롭게 선택할 수 있는 유연성을 제공합니다.

GitHub Copilot CLI 및 기존 터미널 도구와의 비교

qqqa는 GitHub Copilot CLI나 다른 터미널 기반 AI 도구들과 유사해 보일 수 있지만, Stateless(상태 비저장)와 유연성(Flexibility) 측면에서 큰 차별점을 가집니다:

GitHub Copilot CLI와의 차이: GitHub Copilot CLI는 강력하지만 특정 생태계에 종속적이며, 대화형 세션을 유지하는 경우가 많습니다. 반면 qqqa는 세션을 유지하지 않는 단발성 실행을 기본으로 하여, 매 실행이 독립적이고 재현 가능합니다. 또한 특정 벤더에 갇히지 않고 로컬 LLM(Ollama)이나 저렴한 API(OpenRouter) 등 다양한 백엔드를 골라 쓸 수 있습니다.
웹 기반 챗봇과의 차이: 웹 브라우저의 챗봇은 문맥을 길게 유지하며 대화하기 좋지만, 터미널의 에러 로그를 복사해서 붙여넣거나 결과를 다시 터미널로 가져오는 과정이 번거롭습니다. qqqa는 표준 입출력(stdin/stdout)을 지원하므로 cat error.log | qq "이 에러 해결법 알려줘"와 같이 터미널 워크플로우에 자연스럽게 녹아듭니다.

주요 기능 및 사용법

qqqa는 크게 질문을 위한 qq와 작업을 수행하는 에이전트인 qa, 두 가지 바이너리로 구성됩니다. 사용자는 상황에 따라 이 두 명령어를 적절히 활용하여 생산성을 높일 수 있습니다.

qq (Quick Question): 빠른 질문과 답변

qq는 말 그대로 "빠른 질문(Quick Question)"을 위한 도구입니다. 복잡한 문맥 관리 없이 단일 질문을 던지고 답변을 받습니다:

파이프라인 지원: 다른 명령어의 출력을 파이프(|)로 전달하여 질문의 컨텍스트로 사용할 수 있습니다. 예를 들어, git status | qq "다음 작업으로 뭘 해야 할까?"와 같이 현재 상태를 기반으로 조언을 구할 수 있습니다.
안전한 읽기 전용: qq는 시스템을 변경하지 않고 오직 답변만 출력하므로, 어떤 질문이든 안심하고 던질 수 있습니다.
사용 예시:
- qq "재귀적으로 현재 디렉터리 파일 나열하는 명령어 알려줘"
- printf '%s\n' "코드 내용..." | qq "이 코드의 버그를 찾아줘"

qa (Quick Agent): 도구를 사용하는 단일 단계 에이전트

qa는 "빠른 에이전트(Quick Agent)"로, 단순한 답변을 넘어 실제 작업을 수행할 수 있는 기능을 갖추고 있습니다. 파일 읽기/쓰기나 명령어 실행과 같은 도구(Tool)를 사용할 수 있습니다:

실행 및 파일 조작: qa는 사용자의 요청에 따라 파일을 생성하거나 셸 명령어를 제안하고 실행할 수 있습니다. 예를 들어, qa "유튜브 영상에서 오디오만 추출해줘"라고 요청하면 필요한 yt-dlp 및 ffmpeg 명령어를 생성해줍니다.
안전 장치(Safety Rails): qa가 명령어를 실행하거나 파일을 건드리기 전에는 반드시 사용자의 확인 절차를 거칩니다. 이를 통해 AI가 의도치 않게 시스템을 망가뜨리는 것을 방지합니다. 신뢰할 수 있는 작업이라면 -y 옵션으로 자동 승인할 수도 있습니다.
사용 예시:
- qa "src/main.rs 파일을 읽고 무슨 기능을 하는지 설명해줘"
- qa "README.md 파일에 설치 방법 섹션을 추가해줘"

다양한 모델 공급자 및 설정

qqqa는 특정 AI 모델에 얽매이지 않습니다. 기본적으로 ~/.qq/config.json 파일을 통해 설정을 관리하며, 다음과 같은 다양한 공급자를 지원합니다:

OpenRouter (기본값): 다양한 최신 모델을 저렴하고 빠르게 사용할 수 있습니다.
Local LLM (Ollama): 인터넷 연결 없이 로컬에서 Llama 3 등을 돌릴 때 유용합니다. 보안이 중요하거나 오프라인 환경일 때 적합합니다.
OpenAI / Groq / Anthropic: 기존에 사용하던 API 키가 있다면 해당 모델들을 그대로 사용할 수 있습니다.
Claude Code CLI / Codex CLI: 이미 Claude Desktop이나 ChatGPT 등을 구독 중이라면, 해당 CLI를 래핑(Wrapping)하여 추가 비용 없이 모델을 활용할 수 있는 기능도 제공합니다.

qqqa 설치 및 시작하기

설치는 주요 운영체제별로 간편하게 진행할 수 있습니다.

macOS: 다음과 같은 명령어로 Homebrew를 통해 설치합니다.
```
brew tap iagooar/qqqa
brew install qqqa
```
Linux/Windows: GitHub Releases 페이지에서 바이너리를 다운로드하여 PATH에 추가합니다.

설치 후에는 qq --init 명령어를 실행하여 대화형 설정 마법사를 통해 기본 모델 공급자와 API 키를 손쉽게 설정할 수 있습니다.

라이선스

qqqa 프로젝트는 MIT License로 공개 및 배포되고 있습니다. 자유롭게 사용, 수정 및 배포가 가능합니다.

qqqa 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~