셸(Shell)을 위한 빠르고 상태가 없는(stateless) LLM 기반 어시스턴트: qq는 질문에 답하고, qa는 명령어를 실행합니다.

qqqa는 복잡한 절차 없이 명령줄(command line)에 LLM 지원을 제공하는 2-in-1 상태가 없는(stateless) CLI 도구입니다.

두 가지 바이너리는 다음과 같습니다:

qq

• 단일 질문을 던집니다. 예: "qq how can I recursively list all files in this directory" (qq는 "quick question"의 약자입니다.)

qa

• 작업을 완료하기 위해 선택적으로 도구(tools)를 사용할 수 있는 단일 단계 에이전트(single step agent)입니다: 파일 읽기, 파일 쓰기, 또는 확인 후 명령어 실행이 가능합니다. (qa는 "quick agent"의 약자입니다.)

qqqa는 macOS, Linux, Windows에서 실행됩니다.

기본적으로 이 저장소(repo)에는 OpenRouter(기본값), OpenAI, Groq, 로컬 Ollama 런타임, Codex CLI (ChatGPT 활용), 그리고 Claude Code CLI (사용자의 Claude 구독 재사용)를 위한 프로필이 포함되어 있습니다. Anthropic 프로필 스텁(stub)이 향후 작업을 위해 설정(config)에 존재하지만

OpenRouter는 OpenAI Chat Completions API를 미러링(mirror)하며, 관대한 커뮤니티 호스팅 모델들을 추가하고, openai/gpt-4.1-nano를 빠르고 저렴하게 유지합니다. qqqa는 별도의 설정 없이도 https://openrouter.ai/api/v1과 통신하며 OPENROUTER_API_KEY에서 API 키를 읽어오므로, 키를 입력하기만 하면 첫 실행이 즉시 가능합니다.

더 높은 처리량(throughput)이 필요한 경우, openai/gpt-oss-20b 및 openai/gpt-oss-120b를 대상으로 하는 번들된 groq 프로필을 사용할 수 있으며, ~/.qq/config.json을 편집하거나 새로운 프로필을 생성하여 OpenAI 호환 제공업체를 언제든지 추가할 수 있습니다.

이미 ChatGPT 비용을 지불하고 계신가요? codex 프로필을 선택하면 (qq --init 실행 시, qq --profile codex를 통해, 또는 ~/.qq/config.json 편집을 통해), qqqa는 HTTP 엔드포인트를 호출하는 대신 Codex CLI로 셸 명령을 전달(shell out)합니다. 이를 통해 기존 ChatGPT 구독을 사실상 추가 비용 없이 재사용할 수 있습니다.

참고 사항:

• ChatGPT 데스크톱 앱(Settings → Labs → Codex)을 통해 Codex CLI를 설치하거나 pip install codex-cli를 통해 설치한 후, codex가 PATH에 포함되어 있는지 확인하세요.
• 스트리밍(Streaming)은 사용할 수 없습니다. --no-stream 옵션 없이도 qqqa는 Codex 응답을 버퍼링(buffer)한 후 한 번에 출력합니다. qa는 여전히 JSON 도구 호출(tool calls)을 기대합니다. read_file, write_file 또는 execute_command가 필요한 경우, OpenRouter에서 하는 것과 동일하게 { "tool": string, "arguments": object }로 응답하세요.
• 바이너리가 누락되었거나 에러와 함께 종료되는 경우, qqqa는 stderr/stdout을 노출하여 환경을 빠르게 수정할 수 있도록 돕습니다.

Codex를 기본 프로필로 고정하는 ~/.qq/config.json의 예시 조각입니다:

{
"default_profile": "codex",
"profiles": {
...

Claude 구독을 가지고 계신가요? claude_cli 프로필을 선택하면 qqqa가 claude 바이너리를 사용합니다. 이미 Claude 데스크톱용을 결제하고 있다면 사용료를 사실상 무료로 유지할 수 있습니다.

참고 사항:

• Claude Code를 설치하여 claude 바이너리가 PATH에 있도록 한 후, claude login을 실행하세요.

• Claude Code는 API 기반 LLM과 동일한 방식으로 응답을 스트리밍(streaming)합니다.

• 다른 Claude 데스크톱 모델을 고정(pin)하고 싶으신가요? ~/.qq/config.json 파일 내의 model_providers.claude_cli.cli 아래에 `

binary를 사용하여 ChatGPT 구독을 재사용할 수 있습니다; API 키가 필요 없으며, 버퍼링된 출력만 제공됩니다) - Claude Code CLI + claude-haiku-4-5 ( claude binary를 래핑(wrap)함; qq는 실시간 스트리밍을 수행하고, qa는 도구 호출(tool calls)을 파싱할 수 있도록 버퍼링을 수행함)) - 다른 데스크톱 모델을 강제하고 싶으신가요? 제공자(provider)의 cli 블록 아래에 "model_override"를 추가하세요 (Codex와 Claude 모두 지원됩니다). 이 오버라이드(override)는 프로필 기본값보다 우선하지만, 실행 시 사용하는 --model 플래그에는 양보합니다.

• 다른 데스크톱 모델을 강제하고 싶으신가요? 추가하세요.

또한 설정(config)에 API 키를 저장할 것을 제안합니다 (선택 사항). 환경 변수(environment variables)를 선호한다면, 빈칸으로 두고 다음 중 하나를 설정하세요:

OPENROUTER_API_KEY - OpenRouter용 (기본값)
GROQ_API_KEY - Groq용
OPENAI_API_KEY - OpenAI용
OLLAMA_API_KEY (선택 사항; 비어 있지 않은 문자열이면 무엇이든 작동합니다. local조차도 가능합니다. Authorization 헤더는 비어 있을 수 없기 때문입니다)

• Codex 또는 Claude CLI 프로필에는 API 키가 필요하지 않습니다. 해당 바이너리(binaries)가 인증을 처리합니다 (codex login / claude login).

~/.qq/config.json에 기록되는 기본값:

• 제공자(Providers)
  openrouter → base https://openrouter.ai/api/v1, env OPENROUTER_API_KEY, default headers HTTP-Referer=https://github.com/iagooar/qqqa 및 X-Title=qqqa
openai → base https://api.openai.com/v1, env OPENAI_API_KEY
groq → base https://api.groq.com/openai/v1, env GROQ_API_KEY
ollama → base http://127.0.0.1:11434/v1, env OLLAMA_API_KEY (설정하지 않으면 qqqa가 비어 있지 않은 플레이스홀더(placeholder)를 자동으로 주입합니다)
  anthropic → base https://api.anthropic.com/v1, env ANTHROPIC_API_KEY (향후 지원을 위해 설정 스키마에 포함되어 있으나, 아직은 사용할 수 없습니다)
  codex → mode cli, binary codex, base args exec (Codex CLI 설치 필요; 인증은 codex login으로 처리). cli 블록 내의 선택적 `

플래그를 사용하면 프로필의 모델을 변경하지 않고도 설정할 수 있습니다.codex

→ CLI provider, binarycodex

• 바이너리(binary)가 없으면 실패합니다.

• 프로필 (Profiles)
  openrouter

→ modelopenai/gpt-4.1-nano

(기본값)openai

→ modelgpt-5-mini

groq

→ modelopenai/gpt-oss-20b

ollama

→ modelllama3.1

anthropic

→ modelclaude-3-5-sonnet-20241022

(Anthropic 연동이 완료될 때까지 비활성 플레이스홀더(placeholder) 상태)
codex

→ model labelgpt-5

(표시용으로만 사용됨; Codex CLI가 실제 기반이 되는 ChatGPT 모델을 선택함)

• GPT-5 제품군 모델을 위한 프로필별 선택 사항:
  reasoning_effort

설정하지 않으면

각 요청과 함께 마지막 10개의 qq 또는 qa 명령어를 전송하도록 선택할 수 있습니다. 여전히 실행 시마다 --history (강제 활성화) 또는 -n/--no-history (강제 비활성화)를 사용하여 설정을 덮어쓸 수 있습니다. 첫 번째 토큰이 qq 또는 qa인 명령어만 공유됩니다.

qq는 기본적으로 응답을 스트리밍(streaming)하므로 토큰이 도착하는 즉시 확인할 수 있습니다. 만약 다른 도구로 파이프(piping)를 연결하거나 최종 답변 전체를 한꺼번에 복사하는 경우처럼 클래식한 버퍼형 출력(buffered output)을 선호한다면, --no-stream을 전달하여 응답이 완료될 때까지 출력을 기다리게 할 수 있습니다.

# 가장 간단한 사용법
qq "convert mp4 to mp3"
# 기본적으로 토큰 스트리밍 (포맷팅된 출력)
...

참고: 따옴표 없이 qq를 실행하는 것도 가능하며, 대부분의 경우 따옴표를 사용했을 때와 동일하게 작동합니다.

# 가장 간단한 사용법
qq convert mp4 to mp3

YouTube 비디오에서 오디오를 추출하고 싶지만 정확한 플래그(flags)가 기억나지 않는 상황이라고 가정해 봅시다.

qq로 질문하기:

qq "how do I use ffmpeg to extract audio from a YouTube video into mp3"

일반적인 답변은 도구를 설치한 다음 yt-dlp를 사용하여 오디오를 가져오고 ffmpeg를 사용하여 변환할 것을 제안할 것입니다:

# macOS
brew install yt-dlp ffmpeg
# Debian 또는 Ubuntu
...

qa를 사용하여 저 대신 수행하게 하기:

qa "download audio as mp3 from https://www.youtube.com/watch?v=VIDEO_ID"

에이전트(agent)는 yt-dlp -x --audio-format mp3 URL과 같은 안전한 명령어를 제안하고, 확인을 위해 보여준 뒤 실행합니다. -y를 전달하여 자동으로 승인할 수 있습니다.

qa는 일반 텍스트로 답변하거나 JSON 형식으로 하나의 도구 호출(tool call)을 요청할 수 있습니다. 지원되는 도구는 다음과 같습니다:

read_file: { "path": string } 포함
write_file: { "path": string, "content": string } 포함
execute_command: { "command": string, "cwd?": string } 포함

예시:

# 안전한 방식으로 파일 읽기
qa "read src/bin/qq.rs and tell me what main does"
# 파일 쓰기
...

qa가 실행 중인 환경의 표준 출력(stdout)이 터미널인 경우, 출력은 실시간으로 스트리밍됩니다. 그 후에도 복사가 용이하도록 구조화된 [tool:execute_command] 요약이 여전히 출력됩니다.

execute_command

제안된 명령어를 출력하고 확인을 요청합니다. 작업 디렉터리가 홈 디렉터리 외부에 있는 경우 경고를 표시합니다. 신뢰할 수 있는 워크플로 (workflows)에서는 -y를 사용하여 자동으로 승인할 수 있습니다.

러너 (runner)는 기본 허용 목록 (allowlist) (예: ls, grep, find, rg, awk 등)을 강제하며, 파이프라인 (pipelines), 리다이렉션 (redirection) 및 기타 고위험 구조는 거부합니다. 명령어가 차단되면 qa는 ~/.qq/config.json 내부의 command_allowlist에 해당 명령어를 추가하도록 안내합니다. 한 번 승인하면 해당 선택이 유지되며 향후 실행 시 업데이트됩니다. Windows에서는 활성 환경에 자동으로 적응하므로 dir 또는 Get-ChildItem과 같은 내장 명령어 (built-ins)가 추가 플래그 없이도 계속 작동합니다.

일부 OpenAI 호환 게이트웨이 (OpenAI-compatible gateways) (LiteLLM, 로컬 기업 프록시 등)는 자체 서명된 CA로 TLS를 종료합니다. 제공자별 tls